1 //------------------------------------------------------------------------------------- 2 // DirectXTex.h 3 // 4 // DirectX Texture Library 5 // 6 // THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF 7 // ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO 8 // THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 9 // PARTICULAR PURPOSE. 10 // 11 // Copyright (c) Microsoft Corporation. All rights reserved. 12 // 13 // http://go.microsoft.com/fwlink/?LinkId=248926 14 //------------------------------------------------------------------------------------- 15 16 #pragma once 17 18 #if defined(WINAPI_FAMILY) && (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) && (_WIN32_WINNT <= _WIN32_WINNT_WIN8) 19 #error WIC is not supported on Windows Phone 8.0 20 #endif 21 22 // VS 2010's stdint.h conflicts with intsafe.h 23 #pragma warning(push) 24 #pragma warning(disable : 4005) 25 #include <stdint.h> 26 #pragma warning(pop) 27 28 #include <algorithm> 29 #include <functional> 30 31 #if defined(_XBOX_ONE) && defined(_TITLE) 32 #include <d3d11_x.h> 33 #define DCOMMON_H_INCLUDED 34 #else 35 #include <d3d11_1.h> 36 #endif 37 38 #include <ocidl.h> 39 40 // VS 2010 doesn't support explicit calling convention for std::function 41 #ifndef DIRECTX_STD_CALLCONV 42 #if defined(_MSC_VER) && (_MSC_VER < 1700) 43 #define DIRECTX_STD_CALLCONV 44 #else 45 #define DIRECTX_STD_CALLCONV __cdecl 46 #endif 47 #endif 48 49 // VS 2010/2012 do not support =default =delete 50 #ifndef DIRECTX_CTOR_DEFAULT 51 #if defined(_MSC_VER) && (_MSC_VER < 1800) 52 #define DIRECTX_CTOR_DEFAULT {} 53 #define DIRECTX_CTOR_DELETE ; 54 #else 55 #define DIRECTX_CTOR_DEFAULT =default; 56 #define DIRECTX_CTOR_DELETE =delete; 57 #endif 58 #endif 59 60 #define DIRECTX_TEX_VERSION 132 61 62 namespace DirectX 63 { 64 65 //--------------------------------------------------------------------------------- 66 // DXGI Format Utilities 67 bool __cdecl IsValid( _In_ DXGI_FORMAT fmt ); 68 bool __cdecl IsCompressed( _In_ DXGI_FORMAT fmt ); 69 bool __cdecl IsPacked( _In_ DXGI_FORMAT fmt ); 70 bool __cdecl IsVideo( _In_ DXGI_FORMAT fmt ); 71 bool __cdecl IsPlanar( _In_ DXGI_FORMAT fmt ); 72 bool __cdecl IsPalettized( _In_ DXGI_FORMAT fmt ); 73 bool __cdecl IsDepthStencil(_In_ DXGI_FORMAT fmt ); 74 bool __cdecl IsSRGB( _In_ DXGI_FORMAT fmt ); 75 bool __cdecl IsTypeless( _In_ DXGI_FORMAT fmt, _In_ bool partialTypeless = true ); 76 77 bool __cdecl HasAlpha( _In_ DXGI_FORMAT fmt ); 78 79 size_t __cdecl BitsPerPixel( _In_ DXGI_FORMAT fmt ); 80 81 size_t __cdecl BitsPerColor( _In_ DXGI_FORMAT fmt ); 82 83 enum CP_FLAGS 84 { 85 CP_FLAGS_NONE = 0x0, // Normal operation 86 CP_FLAGS_LEGACY_DWORD = 0x1, // Assume pitch is DWORD aligned instead of BYTE aligned 87 CP_FLAGS_PARAGRAPH = 0x2, // Assume pitch is 16-byte aligned instead of BYTE aligned 88 CP_FLAGS_YMM = 0x4, // Assume pitch is 32-byte aligned instead of BYTE aligned 89 CP_FLAGS_ZMM = 0x8, // Assume pitch is 64-byte aligned instead of BYTE aligned 90 CP_FLAGS_PAGE4K = 0x200, // Assume pitch is 4096-byte aligned instead of BYTE aligned 91 CP_FLAGS_24BPP = 0x10000, // Override with a legacy 24 bits-per-pixel format size 92 CP_FLAGS_16BPP = 0x20000, // Override with a legacy 16 bits-per-pixel format size 93 CP_FLAGS_8BPP = 0x40000, // Override with a legacy 8 bits-per-pixel format size 94 }; 95 96 void __cdecl ComputePitch( _In_ DXGI_FORMAT fmt, _In_ size_t width, _In_ size_t height, 97 _Out_ size_t& rowPitch, _Out_ size_t& slicePitch, _In_ DWORD flags = CP_FLAGS_NONE ); 98 99 size_t __cdecl ComputeScanlines( _In_ DXGI_FORMAT fmt, _In_ size_t height ); 100 101 DXGI_FORMAT __cdecl MakeSRGB( _In_ DXGI_FORMAT fmt ); 102 DXGI_FORMAT __cdecl MakeTypeless( _In_ DXGI_FORMAT fmt ); 103 DXGI_FORMAT __cdecl MakeTypelessUNORM( _In_ DXGI_FORMAT fmt ); 104 DXGI_FORMAT __cdecl MakeTypelessFLOAT( _In_ DXGI_FORMAT fmt ); 105 106 //--------------------------------------------------------------------------------- 107 // Texture metadata 108 enum TEX_DIMENSION 109 // Subset here matches D3D10_RESOURCE_DIMENSION and D3D11_RESOURCE_DIMENSION 110 { 111 TEX_DIMENSION_TEXTURE1D = 2, 112 TEX_DIMENSION_TEXTURE2D = 3, 113 TEX_DIMENSION_TEXTURE3D = 4, 114 }; 115 116 enum TEX_MISC_FLAG 117 // Subset here matches D3D10_RESOURCE_MISC_FLAG and D3D11_RESOURCE_MISC_FLAG 118 { 119 TEX_MISC_TEXTURECUBE = 0x4L, 120 }; 121 122 enum TEX_MISC_FLAG2 123 { 124 TEX_MISC2_ALPHA_MODE_MASK = 0x7L, 125 }; 126 127 enum TEX_ALPHA_MODE 128 // Matches DDS_ALPHA_MODE, encoded in MISC_FLAGS2 129 { 130 TEX_ALPHA_MODE_UNKNOWN = 0, 131 TEX_ALPHA_MODE_STRAIGHT = 1, 132 TEX_ALPHA_MODE_PREMULTIPLIED = 2, 133 TEX_ALPHA_MODE_OPAQUE = 3, 134 TEX_ALPHA_MODE_CUSTOM = 4, 135 }; 136 137 struct TexMetadata 138 { 139 size_t width; 140 size_t height; // Should be 1 for 1D textures 141 size_t depth; // Should be 1 for 1D or 2D textures 142 size_t arraySize; // For cubemap, this is a multiple of 6 143 size_t mipLevels; 144 uint32_t miscFlags; 145 uint32_t miscFlags2; 146 DXGI_FORMAT format; 147 TEX_DIMENSION dimension; 148 149 size_t __cdecl ComputeIndex( _In_ size_t mip, _In_ size_t item, _In_ size_t slice ) const; 150 // Returns size_t(-1) to indicate an out-of-range error 151 IsCubemapTexMetadata152 bool __cdecl IsCubemap() const { return (miscFlags & TEX_MISC_TEXTURECUBE) != 0; } 153 // Helper for miscFlags 154 IsPMAlphaTexMetadata155 bool __cdecl IsPMAlpha() const { return ((miscFlags2 & TEX_MISC2_ALPHA_MODE_MASK) == TEX_ALPHA_MODE_PREMULTIPLIED) != 0; } SetAlphaModeTexMetadata156 void __cdecl SetAlphaMode( TEX_ALPHA_MODE mode ) { miscFlags2 = (miscFlags2 & ~TEX_MISC2_ALPHA_MODE_MASK) | static_cast<uint32_t>(mode); } 157 // Helpers for miscFlags2 158 IsVolumemapTexMetadata159 bool __cdecl IsVolumemap() const { return (dimension == TEX_DIMENSION_TEXTURE3D); } 160 // Helper for dimension 161 }; 162 163 enum DDS_FLAGS 164 { 165 DDS_FLAGS_NONE = 0x0, 166 167 DDS_FLAGS_LEGACY_DWORD = 0x1, 168 // Assume pitch is DWORD aligned instead of BYTE aligned (used by some legacy DDS files) 169 170 DDS_FLAGS_NO_LEGACY_EXPANSION = 0x2, 171 // Do not implicitly convert legacy formats that result in larger pixel sizes (24 bpp, 3:3:2, A8L8, A4L4, P8, A8P8) 172 173 DDS_FLAGS_NO_R10B10G10A2_FIXUP = 0x4, 174 // Do not use work-around for long-standing D3DX DDS file format issue which reversed the 10:10:10:2 color order masks 175 176 DDS_FLAGS_FORCE_RGB = 0x8, 177 // Convert DXGI 1.1 BGR formats to DXGI_FORMAT_R8G8B8A8_UNORM to avoid use of optional WDDM 1.1 formats 178 179 DDS_FLAGS_NO_16BPP = 0x10, 180 // Conversions avoid use of 565, 5551, and 4444 formats and instead expand to 8888 to avoid use of optional WDDM 1.2 formats 181 182 DDS_FLAGS_EXPAND_LUMINANCE = 0x20, 183 // When loading legacy luminance formats expand replicating the color channels rather than leaving them packed (L8, L16, A8L8) 184 185 DDS_FLAGS_FORCE_DX10_EXT = 0x10000, 186 // Always use the 'DX10' header extension for DDS writer (i.e. don't try to write DX9 compatible DDS files) 187 188 DDS_FLAGS_FORCE_DX10_EXT_MISC2 = 0x20000, 189 // DDS_FLAGS_FORCE_DX10_EXT including miscFlags2 information (result may not be compatible with D3DX10 or D3DX11) 190 }; 191 192 enum WIC_FLAGS 193 { 194 WIC_FLAGS_NONE = 0x0, 195 196 WIC_FLAGS_FORCE_RGB = 0x1, 197 // Loads DXGI 1.1 BGR formats as DXGI_FORMAT_R8G8B8A8_UNORM to avoid use of optional WDDM 1.1 formats 198 199 WIC_FLAGS_NO_X2_BIAS = 0x2, 200 // Loads DXGI 1.1 X2 10:10:10:2 format as DXGI_FORMAT_R10G10B10A2_UNORM 201 202 WIC_FLAGS_NO_16BPP = 0x4, 203 // Loads 565, 5551, and 4444 formats as 8888 to avoid use of optional WDDM 1.2 formats 204 205 WIC_FLAGS_ALLOW_MONO = 0x8, 206 // Loads 1-bit monochrome (black & white) as R1_UNORM rather than 8-bit grayscale 207 208 WIC_FLAGS_ALL_FRAMES = 0x10, 209 // Loads all images in a multi-frame file, converting/resizing to match the first frame as needed, defaults to 0th frame otherwise 210 211 WIC_FLAGS_IGNORE_SRGB = 0x20, 212 // Ignores sRGB metadata if present in the file 213 214 WIC_FLAGS_DITHER = 0x10000, 215 // Use ordered 4x4 dithering for any required conversions 216 217 WIC_FLAGS_DITHER_DIFFUSION = 0x20000, 218 // Use error-diffusion dithering for any required conversions 219 220 WIC_FLAGS_FILTER_POINT = 0x100000, 221 WIC_FLAGS_FILTER_LINEAR = 0x200000, 222 WIC_FLAGS_FILTER_CUBIC = 0x300000, 223 WIC_FLAGS_FILTER_FANT = 0x400000, // Combination of Linear and Box filter 224 // Filtering mode to use for any required image resizing (only needed when loading arrays of differently sized images; defaults to Fant) 225 }; 226 227 HRESULT __cdecl GetMetadataFromDDSMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, _In_ DWORD flags, 228 _Out_ TexMetadata& metadata ); 229 HRESULT __cdecl GetMetadataFromDDSFile( _In_z_ LPCWSTR szFile, _In_ DWORD flags, 230 _Out_ TexMetadata& metadata ); 231 232 HRESULT __cdecl GetMetadataFromTGAMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, 233 _Out_ TexMetadata& metadata ); 234 HRESULT __cdecl GetMetadataFromTGAFile( _In_z_ LPCWSTR szFile, 235 _Out_ TexMetadata& metadata ); 236 237 HRESULT __cdecl GetMetadataFromWICMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, _In_ DWORD flags, 238 _Out_ TexMetadata& metadata ); 239 HRESULT __cdecl GetMetadataFromWICFile( _In_z_ LPCWSTR szFile, _In_ DWORD flags, 240 _Out_ TexMetadata& metadata ); 241 242 //--------------------------------------------------------------------------------- 243 // Bitmap image container 244 struct Image 245 { 246 size_t width; 247 size_t height; 248 DXGI_FORMAT format; 249 size_t rowPitch; 250 size_t slicePitch; 251 uint8_t* pixels; 252 }; 253 254 class ScratchImage 255 { 256 public: ScratchImage()257 ScratchImage() 258 : _nimages(0), _size(0), _image(nullptr), _memory(nullptr) {} ScratchImage(ScratchImage && moveFrom)259 ScratchImage(ScratchImage&& moveFrom) 260 : _nimages(0), _size(0), _image(nullptr), _memory(nullptr) { *this = std::move(moveFrom); } ~ScratchImage()261 ~ScratchImage() { Release(); } 262 263 ScratchImage& __cdecl operator= (ScratchImage&& moveFrom); 264 265 HRESULT __cdecl Initialize( _In_ const TexMetadata& mdata, _In_ DWORD flags = CP_FLAGS_NONE ); 266 267 HRESULT __cdecl Initialize1D( _In_ DXGI_FORMAT fmt, _In_ size_t length, _In_ size_t arraySize, _In_ size_t mipLevels, _In_ DWORD flags = CP_FLAGS_NONE ); 268 HRESULT __cdecl Initialize2D( _In_ DXGI_FORMAT fmt, _In_ size_t width, _In_ size_t height, _In_ size_t arraySize, _In_ size_t mipLevels, _In_ DWORD flags = CP_FLAGS_NONE ); 269 HRESULT __cdecl Initialize3D( _In_ DXGI_FORMAT fmt, _In_ size_t width, _In_ size_t height, _In_ size_t depth, _In_ size_t mipLevels, _In_ DWORD flags = CP_FLAGS_NONE ); 270 HRESULT __cdecl InitializeCube( _In_ DXGI_FORMAT fmt, _In_ size_t width, _In_ size_t height, _In_ size_t nCubes, _In_ size_t mipLevels, _In_ DWORD flags = CP_FLAGS_NONE ); 271 272 HRESULT __cdecl InitializeFromImage( _In_ const Image& srcImage, _In_ bool allow1D = false, _In_ DWORD flags = CP_FLAGS_NONE ); 273 HRESULT __cdecl InitializeArrayFromImages( _In_reads_(nImages) const Image* images, _In_ size_t nImages, _In_ bool allow1D = false, _In_ DWORD flags = CP_FLAGS_NONE ); 274 HRESULT __cdecl InitializeCubeFromImages( _In_reads_(nImages) const Image* images, _In_ size_t nImages, _In_ DWORD flags = CP_FLAGS_NONE ); 275 HRESULT __cdecl Initialize3DFromImages( _In_reads_(depth) const Image* images, _In_ size_t depth, _In_ DWORD flags = CP_FLAGS_NONE ); 276 277 void __cdecl Release(); 278 279 bool __cdecl OverrideFormat( _In_ DXGI_FORMAT f ); 280 GetMetadata()281 const TexMetadata& __cdecl GetMetadata() const { return _metadata; } 282 const Image* __cdecl GetImage(_In_ size_t mip, _In_ size_t item, _In_ size_t slice) const; 283 GetImages()284 const Image* __cdecl GetImages() const { return _image; } GetImageCount()285 size_t __cdecl GetImageCount() const { return _nimages; } 286 GetPixels()287 uint8_t* __cdecl GetPixels() const { return _memory; } GetPixelsSize()288 size_t __cdecl GetPixelsSize() const { return _size; } 289 290 bool __cdecl IsAlphaAllOpaque() const; 291 292 private: 293 size_t _nimages; 294 size_t _size; 295 TexMetadata _metadata; 296 Image* _image; 297 uint8_t* _memory; 298 299 // Hide copy constructor and assignment operator 300 ScratchImage( const ScratchImage& ); 301 ScratchImage& operator=( const ScratchImage& ); 302 }; 303 304 //--------------------------------------------------------------------------------- 305 // Memory blob (allocated buffer pointer is always 16-byte aligned) 306 class Blob 307 { 308 public: Blob()309 Blob() : _buffer(nullptr), _size(0) {} Blob(Blob && moveFrom)310 Blob(Blob&& moveFrom) : _buffer(nullptr), _size(0) { *this = std::move(moveFrom); } ~Blob()311 ~Blob() { Release(); } 312 313 Blob& __cdecl operator= (Blob&& moveFrom); 314 315 HRESULT __cdecl Initialize( _In_ size_t size ); 316 317 void __cdecl Release(); 318 GetBufferPointer()319 void *__cdecl GetBufferPointer() const { return _buffer; } GetBufferSize()320 size_t __cdecl GetBufferSize() const { return _size; } 321 322 private: 323 void* _buffer; 324 size_t _size; 325 326 // Hide copy constructor and assignment operator 327 Blob( const Blob& ); 328 Blob& operator=( const Blob& ); 329 }; 330 331 //--------------------------------------------------------------------------------- 332 // Image I/O 333 334 // DDS operations 335 HRESULT __cdecl LoadFromDDSMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, _In_ DWORD flags, 336 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 337 HRESULT __cdecl LoadFromDDSFile( _In_z_ LPCWSTR szFile, _In_ DWORD flags, 338 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 339 340 HRESULT __cdecl SaveToDDSMemory( _In_ const Image& image, _In_ DWORD flags, 341 _Out_ Blob& blob ); 342 HRESULT __cdecl SaveToDDSMemory( _In_reads_(nimages) const Image* images, _In_ size_t nimages, _In_ const TexMetadata& metadata, _In_ DWORD flags, 343 _Out_ Blob& blob ); 344 345 HRESULT __cdecl SaveToDDSFile( _In_ const Image& image, _In_ DWORD flags, _In_z_ LPCWSTR szFile ); 346 HRESULT __cdecl SaveToDDSFile( _In_reads_(nimages) const Image* images, _In_ size_t nimages, _In_ const TexMetadata& metadata, _In_ DWORD flags, _In_z_ LPCWSTR szFile ); 347 348 // TGA operations 349 HRESULT __cdecl LoadFromTGAMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, 350 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 351 HRESULT __cdecl LoadFromTGAFile( _In_z_ LPCWSTR szFile, 352 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 353 354 HRESULT __cdecl SaveToTGAMemory( _In_ const Image& image, _Out_ Blob& blob ); 355 HRESULT __cdecl SaveToTGAFile( _In_ const Image& image, _In_z_ LPCWSTR szFile ); 356 357 // WIC operations 358 HRESULT __cdecl LoadFromWICMemory( _In_reads_bytes_(size) LPCVOID pSource, _In_ size_t size, _In_ DWORD flags, 359 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 360 HRESULT __cdecl LoadFromWICFile( _In_z_ LPCWSTR szFile, _In_ DWORD flags, 361 _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image ); 362 363 HRESULT __cdecl SaveToWICMemory( _In_ const Image& image, _In_ DWORD flags, _In_ REFGUID guidContainerFormat, 364 _Out_ Blob& blob, _In_opt_ const GUID* targetFormat = nullptr, 365 _In_opt_ std::function<void DIRECTX_STD_CALLCONV(IPropertyBag2*)> setCustomProps = nullptr ); 366 HRESULT __cdecl SaveToWICMemory( _In_count_(nimages) const Image* images, _In_ size_t nimages, _In_ DWORD flags, _In_ REFGUID guidContainerFormat, 367 _Out_ Blob& blob, _In_opt_ const GUID* targetFormat = nullptr, 368 _In_opt_ std::function<void DIRECTX_STD_CALLCONV(IPropertyBag2*)> setCustomProps = nullptr ); 369 370 HRESULT __cdecl SaveToWICFile( _In_ const Image& image, _In_ DWORD flags, _In_ REFGUID guidContainerFormat, 371 _In_z_ LPCWSTR szFile, _In_opt_ const GUID* targetFormat = nullptr, 372 _In_opt_ std::function<void DIRECTX_STD_CALLCONV(IPropertyBag2*)> setCustomProps = nullptr ); 373 HRESULT __cdecl SaveToWICFile( _In_count_(nimages) const Image* images, _In_ size_t nimages, _In_ DWORD flags, _In_ REFGUID guidContainerFormat, 374 _In_z_ LPCWSTR szFile, _In_opt_ const GUID* targetFormat = nullptr, 375 _In_opt_ std::function<void DIRECTX_STD_CALLCONV(IPropertyBag2*)> setCustomProps = nullptr ); 376 377 enum WICCodecs 378 { 379 WIC_CODEC_BMP =1, // Windows Bitmap (.bmp) 380 WIC_CODEC_JPEG, // Joint Photographic Experts Group (.jpg, .jpeg) 381 WIC_CODEC_PNG, // Portable Network Graphics (.png) 382 WIC_CODEC_TIFF, // Tagged Image File Format (.tif, .tiff) 383 WIC_CODEC_GIF, // Graphics Interchange Format (.gif) 384 WIC_CODEC_WMP, // Windows Media Photo / HD Photo / JPEG XR (.hdp, .jxr, .wdp) 385 WIC_CODEC_ICO, // Windows Icon (.ico) 386 }; 387 388 REFGUID __cdecl GetWICCodec( _In_ WICCodecs codec ); 389 390 //--------------------------------------------------------------------------------- 391 // Texture conversion, resizing, mipmap generation, and block compression 392 393 enum TEX_FR_FLAGS 394 { 395 TEX_FR_ROTATE0 = 0x0, 396 TEX_FR_ROTATE90 = 0x1, 397 TEX_FR_ROTATE180 = 0x2, 398 TEX_FR_ROTATE270 = 0x3, 399 TEX_FR_FLIP_HORIZONTAL = 0x08, 400 TEX_FR_FLIP_VERTICAL = 0x10, 401 }; 402 403 HRESULT __cdecl FlipRotate( _In_ const Image& srcImage, _In_ DWORD flags, _Out_ ScratchImage& image ); 404 HRESULT __cdecl FlipRotate( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 405 _In_ DWORD flags, _Out_ ScratchImage& result ); 406 // Flip and/or rotate image 407 408 enum TEX_FILTER_FLAGS 409 { 410 TEX_FILTER_DEFAULT = 0, 411 412 TEX_FILTER_WRAP_U = 0x1, 413 TEX_FILTER_WRAP_V = 0x2, 414 TEX_FILTER_WRAP_W = 0x4, 415 TEX_FILTER_WRAP = ( TEX_FILTER_WRAP_U | TEX_FILTER_WRAP_V | TEX_FILTER_WRAP_W ), 416 TEX_FILTER_MIRROR_U = 0x10, 417 TEX_FILTER_MIRROR_V = 0x20, 418 TEX_FILTER_MIRROR_W = 0x40, 419 TEX_FILTER_MIRROR = ( TEX_FILTER_MIRROR_U | TEX_FILTER_MIRROR_V | TEX_FILTER_MIRROR_W ), 420 // Wrap vs. Mirror vs. Clamp filtering options 421 422 TEX_FILTER_SEPARATE_ALPHA = 0x100, 423 // Resize color and alpha channel independently 424 425 TEX_FILTER_RGB_COPY_RED = 0x1000, 426 TEX_FILTER_RGB_COPY_GREEN = 0x2000, 427 TEX_FILTER_RGB_COPY_BLUE = 0x4000, 428 // When converting RGB to R, defaults to using grayscale. These flags indicate copying a specific channel instead 429 // When converting RGB to RG, defaults to copying RED | GREEN. These flags control which channels are selected instead. 430 431 TEX_FILTER_DITHER = 0x10000, 432 // Use ordered 4x4 dithering for any required conversions 433 TEX_FILTER_DITHER_DIFFUSION = 0x20000, 434 // Use error-diffusion dithering for any required conversions 435 436 TEX_FILTER_POINT = 0x100000, 437 TEX_FILTER_LINEAR = 0x200000, 438 TEX_FILTER_CUBIC = 0x300000, 439 TEX_FILTER_BOX = 0x400000, 440 TEX_FILTER_FANT = 0x400000, // Equiv to Box filtering for mipmap generation 441 TEX_FILTER_TRIANGLE = 0x500000, 442 // Filtering mode to use for any required image resizing 443 444 TEX_FILTER_SRGB_IN = 0x1000000, 445 TEX_FILTER_SRGB_OUT = 0x2000000, 446 TEX_FILTER_SRGB = ( TEX_FILTER_SRGB_IN | TEX_FILTER_SRGB_OUT ), 447 // sRGB <-> RGB for use in conversion operations 448 // if the input format type is IsSRGB(), then SRGB_IN is on by default 449 // if the output format type is IsSRGB(), then SRGB_OUT is on by default 450 451 TEX_FILTER_FORCE_NON_WIC = 0x10000000, 452 // Forces use of the non-WIC path when both are an option 453 454 TEX_FILTER_FORCE_WIC = 0x20000000, 455 // Forces use of the WIC path even when logic would have picked a non-WIC path when both are an option 456 }; 457 458 HRESULT __cdecl Resize( _In_ const Image& srcImage, _In_ size_t width, _In_ size_t height, _In_ DWORD filter, 459 _Out_ ScratchImage& image ); 460 HRESULT __cdecl Resize( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 461 _In_ size_t width, _In_ size_t height, _In_ DWORD filter, _Out_ ScratchImage& result ); 462 // Resize the image to width x height. Defaults to Fant filtering. 463 // Note for a complex resize, the result will always have mipLevels == 1 464 465 HRESULT __cdecl Convert( _In_ const Image& srcImage, _In_ DXGI_FORMAT format, _In_ DWORD filter, _In_ float threshold, 466 _Out_ ScratchImage& image ); 467 HRESULT __cdecl Convert( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 468 _In_ DXGI_FORMAT format, _In_ DWORD filter, _In_ float threshold, _Out_ ScratchImage& result ); 469 // Convert the image to a new format 470 471 HRESULT __cdecl ConvertToSinglePlane( _In_ const Image& srcImage, _Out_ ScratchImage& image ); 472 HRESULT __cdecl ConvertToSinglePlane( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 473 _Out_ ScratchImage& image ); 474 // Converts the image from a planar format to an equivalent non-planar format 475 476 HRESULT __cdecl GenerateMipMaps( _In_ const Image& baseImage, _In_ DWORD filter, _In_ size_t levels, 477 _Inout_ ScratchImage& mipChain, _In_ bool allow1D = false ); 478 HRESULT __cdecl GenerateMipMaps( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 479 _In_ DWORD filter, _In_ size_t levels, _Inout_ ScratchImage& mipChain ); 480 // levels of '0' indicates a full mipchain, otherwise is generates that number of total levels (including the source base image) 481 // Defaults to Fant filtering which is equivalent to a box filter 482 483 HRESULT __cdecl GenerateMipMaps3D( _In_reads_(depth) const Image* baseImages, _In_ size_t depth, _In_ DWORD filter, _In_ size_t levels, 484 _Out_ ScratchImage& mipChain ); 485 HRESULT __cdecl GenerateMipMaps3D( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 486 _In_ DWORD filter, _In_ size_t levels, _Out_ ScratchImage& mipChain ); 487 // levels of '0' indicates a full mipchain, otherwise is generates that number of total levels (including the source base image) 488 // Defaults to Fant filtering which is equivalent to a box filter 489 490 enum TEX_PMALPHA_FLAGS 491 { 492 TEX_PMALPHA_DEFAULT = 0, 493 494 TEX_PMALPHA_IGNORE_SRGB = 0x1, 495 // ignores sRGB colorspace conversions 496 497 TEX_PMALPHA_SRGB_IN = 0x1000000, 498 TEX_PMALPHA_SRGB_OUT = 0x2000000, 499 TEX_PMALPHA_SRGB = ( TEX_PMALPHA_SRGB_IN | TEX_PMALPHA_SRGB_OUT ), 500 // if the input format type is IsSRGB(), then SRGB_IN is on by default 501 // if the output format type is IsSRGB(), then SRGB_OUT is on by default 502 }; 503 504 HRESULT __cdecl PremultiplyAlpha( _In_ const Image& srcImage, _In_ DWORD flags, _Out_ ScratchImage& image ); 505 HRESULT __cdecl PremultiplyAlpha( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, _In_ DWORD flags, _Out_ ScratchImage& result ); 506 // Converts to a premultiplied alpha version of the texture 507 508 enum TEX_COMPRESS_FLAGS 509 { 510 TEX_COMPRESS_DEFAULT = 0, 511 512 TEX_COMPRESS_RGB_DITHER = 0x10000, 513 // Enables dithering RGB colors for BC1-3 compression 514 515 TEX_COMPRESS_A_DITHER = 0x20000, 516 // Enables dithering alpha for BC1-3 compression 517 518 TEX_COMPRESS_DITHER = 0x30000, 519 // Enables both RGB and alpha dithering for BC1-3 compression 520 521 TEX_COMPRESS_UNIFORM = 0x40000, 522 // Uniform color weighting for BC1-3 compression; by default uses perceptual weighting 523 524 TEX_COMPRESS_BC7_USE_3SUBSETS = 0x80000, 525 // Enables exhaustive search for BC7 compress for mode 0 and 2; by default skips trying these modes 526 527 TEX_COMPRESS_SRGB_IN = 0x1000000, 528 TEX_COMPRESS_SRGB_OUT = 0x2000000, 529 TEX_COMPRESS_SRGB = ( TEX_COMPRESS_SRGB_IN | TEX_COMPRESS_SRGB_OUT ), 530 // if the input format type is IsSRGB(), then SRGB_IN is on by default 531 // if the output format type is IsSRGB(), then SRGB_OUT is on by default 532 533 TEX_COMPRESS_PARALLEL = 0x10000000, 534 // Compress is free to use multithreading to improve performance (by default it does not use multithreading) 535 }; 536 537 HRESULT __cdecl Compress( _In_ const Image& srcImage, _In_ DXGI_FORMAT format, _In_ DWORD compress, _In_ float alphaRef, 538 _Out_ ScratchImage& cImage ); 539 HRESULT __cdecl Compress( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 540 _In_ DXGI_FORMAT format, _In_ DWORD compress, _In_ float alphaRef, _Out_ ScratchImage& cImages ); 541 // Note that alphaRef is only used by BC1. 0.5f is a typical value to use 542 543 HRESULT __cdecl Compress( _In_ ID3D11Device* pDevice, _In_ const Image& srcImage, _In_ DXGI_FORMAT format, _In_ DWORD compress, 544 _In_ float alphaWeight, _Out_ ScratchImage& image ); 545 HRESULT __cdecl Compress( _In_ ID3D11Device* pDevice, _In_ const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 546 _In_ DXGI_FORMAT format, _In_ DWORD compress, _In_ float alphaWeight, _Out_ ScratchImage& cImages ); 547 // DirectCompute-based compression (alphaWeight is only used by BC7. 1.0 is the typical value to use) 548 549 HRESULT __cdecl Decompress( _In_ const Image& cImage, _In_ DXGI_FORMAT format, _Out_ ScratchImage& image ); 550 HRESULT __cdecl Decompress( _In_reads_(nimages) const Image* cImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 551 _In_ DXGI_FORMAT format, _Out_ ScratchImage& images ); 552 553 //--------------------------------------------------------------------------------- 554 // Normal map operations 555 556 enum CNMAP_FLAGS 557 { 558 CNMAP_DEFAULT = 0, 559 560 CNMAP_CHANNEL_RED = 0x1, 561 CNMAP_CHANNEL_GREEN = 0x2, 562 CNMAP_CHANNEL_BLUE = 0x3, 563 CNMAP_CHANNEL_ALPHA = 0x4, 564 CNMAP_CHANNEL_LUMINANCE = 0x5, 565 // Channel selection when evaluting color value for height 566 // Luminance is a combination of red, green, and blue 567 568 CNMAP_MIRROR_U = 0x1000, 569 CNMAP_MIRROR_V = 0x2000, 570 CNMAP_MIRROR = 0x3000, 571 // Use mirror semantics for scanline references (defaults to wrap) 572 573 CNMAP_INVERT_SIGN = 0x4000, 574 // Inverts normal sign 575 576 CNMAP_COMPUTE_OCCLUSION = 0x8000, 577 // Computes a crude occlusion term stored in the alpha channel 578 }; 579 580 HRESULT __cdecl ComputeNormalMap( _In_ const Image& srcImage, _In_ DWORD flags, _In_ float amplitude, 581 _In_ DXGI_FORMAT format, _Out_ ScratchImage& normalMap ); 582 HRESULT __cdecl ComputeNormalMap( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 583 _In_ DWORD flags, _In_ float amplitude, _In_ DXGI_FORMAT format, _Out_ ScratchImage& normalMaps ); 584 585 //--------------------------------------------------------------------------------- 586 // Misc image operations 587 struct Rect 588 { 589 size_t x; 590 size_t y; 591 size_t w; 592 size_t h; 593 RectRect594 Rect() DIRECTX_CTOR_DEFAULT 595 Rect( size_t _x, size_t _y, size_t _w, size_t _h ) : x(_x), y(_y), w(_w), h(_h) {} 596 }; 597 598 HRESULT __cdecl CopyRectangle( _In_ const Image& srcImage, _In_ const Rect& srcRect, _In_ const Image& dstImage, 599 _In_ DWORD filter, _In_ size_t xOffset, _In_ size_t yOffset ); 600 601 enum CMSE_FLAGS 602 { 603 CMSE_DEFAULT = 0, 604 605 CMSE_IMAGE1_SRGB = 0x1, 606 CMSE_IMAGE2_SRGB = 0x2, 607 // Indicates that image needs gamma correction before comparision 608 609 CMSE_IGNORE_RED = 0x10, 610 CMSE_IGNORE_GREEN = 0x20, 611 CMSE_IGNORE_BLUE = 0x40, 612 CMSE_IGNORE_ALPHA = 0x80, 613 // Ignore the channel when computing MSE 614 615 CMSE_IMAGE1_X2_BIAS = 0x100, 616 CMSE_IMAGE2_X2_BIAS = 0x200, 617 // Indicates that image should be scaled and biased before comparison (i.e. UNORM -> SNORM) 618 }; 619 620 HRESULT __cdecl ComputeMSE( _In_ const Image& image1, _In_ const Image& image2, _Out_ float& mse, _Out_writes_opt_(4) float* mseV, _In_ DWORD flags = 0 ); 621 622 //--------------------------------------------------------------------------------- 623 // Direct3D 11 functions 624 bool __cdecl IsSupportedTexture( _In_ ID3D11Device* pDevice, _In_ const TexMetadata& metadata ); 625 626 HRESULT __cdecl CreateTexture( _In_ ID3D11Device* pDevice, _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 627 _Outptr_ ID3D11Resource** ppResource ); 628 629 HRESULT __cdecl CreateShaderResourceView( _In_ ID3D11Device* pDevice, _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 630 _Outptr_ ID3D11ShaderResourceView** ppSRV ); 631 632 HRESULT __cdecl CreateTextureEx( _In_ ID3D11Device* pDevice, _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 633 _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags, _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags, _In_ bool forceSRGB, 634 _Outptr_ ID3D11Resource** ppResource ); 635 636 HRESULT __cdecl CreateShaderResourceViewEx( _In_ ID3D11Device* pDevice, _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages, _In_ const TexMetadata& metadata, 637 _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags, _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags, _In_ bool forceSRGB, 638 _Outptr_ ID3D11ShaderResourceView** ppSRV ); 639 640 HRESULT __cdecl CaptureTexture( _In_ ID3D11Device* pDevice, _In_ ID3D11DeviceContext* pContext, _In_ ID3D11Resource* pSource, _Out_ ScratchImage& result ); 641 642 #include "DirectXTex.inl" 643 644 }; // namespace 645