AuroraMiddleware/DirectXTex

Fork 0

mirror of https://github.com/microsoft/DirectXTex synced 2024-11-09 14:30:05 +00:00

Table of Contents

Header
Namespace
Initialization
Functions

DDS I/O Functions
HDR I/O Functions
TGA I/O Functions
WIC I/O Functions
Texture Functions
Direct3D 11 / DirectX 12 Helper Functions
Utility Functions

WIC helpers
DXGI format tests
DXGI format properties
Image layout
DXGI format type promoters

Structures
Adding to a VS solution

Using project-to-project references
Using NuGet package manager

Archived

Using the vcpkg C++ library manager
CMake
Extensions
Dependencies

Release Notes
Additional Information

The DirectXTex library includes a full-featured DDS reader and writer including legacy format conversions, a TGA reader and writer, a HDR reader and writer, a WIC-based bitmap reader and writer (BMP, JPEG, PNG, TIFF, and HD Photo), and various texture processing functions.

This library is intended primarily for tool usage. For a library that is more optimized for runtime use, see DirectX Tool Kit for DX11 / DX12.

Support for EXR requires the OpenEXR library and additional code. See Adding OpenEXR for more details.

Header

The majority of the header files here are intended for internal implementation of the library only (BC.h, DDS.h, DirectXTexP.h, and scoped.h). Only DirectXTex.h (and DirectXTex.inl) is meant as a 'public' header for the library.

#include "DirectXTex.h"

By default, the library supports Direct3D 11. If you want to support Direct3D 12, then you need to #include <d3d12.h> before you do #include "DirectXTex.h".

Namespace

All the functions in the library are in the DirectX C++ namespace.

Initialization

The library assumes that the client code will have already called CoInitialize, CoInitializeEx, or Windows::Foundation::Initialize as needed by the application before calling any DirectXTex routines. Most DirectXTex functions use the Windows Imaging Component which requires COM.

For a Universal Windows Platform (UWP) app using /ZW, the Windows Runtime and COM is initialized by the C/C++ Run-Time. For C++/WinRT applications, this is done by calling winrt::init_apartment();.

For a classic Windows desktop application you have to do this explicitly:

HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
if (FAILED(hr))
    // error

If you need Windows Runtime functionality in your application on Windows 10 or Windows 11, use:

#if (_WIN32_WINNT >= 0x0A00 /*_WIN32_WINNT_WIN10*/)
    Microsoft::WRL::Wrappers::RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
        // error
#else
    HRESULT hr = CoInitializeEx(nullptr, COINITBASE_MULTITHREADED);
    if (FAILED(hr))
        // error
#endif

If you get an E_NOINTERFACE HRESULT back from a DirectXTex function, then you likely didn't initialize COM on the calling thread.

Functions

DDS I/O Functions

These functions perform file I/O for DirectDraw Surface (.DDS) files. These functions support many legacy Direct3D 9 .DDS files and all Direct3D 10.x/11.x era DX10 extension .DDS files.

GetMetadataFromDDSMemory - Extracts the metadata from a DDS file in memory
GetMetadataFromDDSFile - Extracts the metadata from a DDS file on disk
LoadFromDDSMemory - Loads image data from a DDS file in memory
LoadFromDDSFile - Loads image data from a DDS file on disk
SaveToDDSMemory - Creates a DDS file in memory
SaveToDDSFile - Creates a DDS file on disk
EncodeDDSHeader - Helper for creating your own DDS files

HDR I/O Functions

The Radiance RGBE (.HDR) format is commonly used as a texture source file format in game development for high-dynamic range images, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

GetMetadataFromHDRMemory - Extracts the metadata from a HDR file in memory
GetMetadataFromHDRFile - Extracts the metadata from a HDR file on disk
LoadFromHDRMemory - Loads image data from a HDR file in memory
LoadFromHDRFile - Loads image data from a HDR file on disk
SaveToHDRMemory - Creates a HDR file in memory
SaveToHDRFile - Creates a HDR file on disk

TGA I/O Functions

The Targa Truevision (.TGA) format is commonly used as a texture source file format in game development, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

GetMetadataFromTGAMemory - Extracts the metadata from a TGA file in memory
GetMetadataFromTGAFile - Extracts the metadata from a TGA file on disk
LoadFromTGAMemory - Loads image data from a TGA file in memory
LoadFromTGAFile - Loads image data from a TGA file on disk
SaveToTGAMemory - Creates a TGA file in memory
SaveToTGAFile - Creates a TGA file on disk

WIC I/O Functions

These functions use the Windows Imaging Component (WIC) to read or write an image file. There are built-in WIC codecs in Windows for .BMP, .PNG, .GIF, .TIFF, .JPEG, and JPEG-XR / HD Photo images. Some containers (.GIF and .TIFF) can contain multi-frame bitmaps files.

GetMetadataFromWICMemory - Extracts the metadata from a WIC-supported file in memory
GetMetadataFromWICFile - Extracts the metadata from a WIC-supported file on disk
LoadFromWICMemory - Loads image data from a WIC-supported file in memory
LoadFromWICFile - Loads image data from a WIC-supported file on disk
SaveToWICMemory - Creates a WIC-supported file in memory
SaveToWICFile - Creates a WIC-supported file on disk

These functions also work with additional installed codecs. For example, you can read HEIF files if you install the HEIF WIC Codec, but this only supports reading so the save functions can't write these files.

Texture Functions

Functions for doing texture processing based on DirectXTex data typically loaded from a WIC or TGA image file and then written to a .DDS file.

The majority of these functions cannot operate on planar or palettized formats. For video formats, AYUV, Y410, Y416, YUY2, Y216, and Y416 are supported and all operations are performed in RGB colorspace.

FlipRotate - Flip and/or rotate image or set of images
Resize - Resize an image or set of images
Convert - Convert an image or set of images from one pixel format to another
ConvertToSinglePlane - Converts a planar image or set of images to a single-plane pixel format
GenerateMipMaps - Generates mipmaps for an image or a set of images
GenerateMipMaps3D - Generates mipmaps for a 3D volume texture from a set of images representing the slices
ScaleMipMapsAlphaForCoverage - Scales mipmaps to preserve alpha coverage
PremultiplyAlpha - This converts to/from premultiplied alpha
Compress - Compresses an image or set of images to a BC format
Decompress - Decompresses a BC format to a non-BC format image
ComputeNormalMap - Converts a height-map to a normal-map
CopyRectangle - Copies a rectangle from a soure image to a destination image. Does not support block compressed formats
ComputeMSE - Computes the mean-squared error for each component based on two input images
EvaluateImage - Evaluates a user-defined function for an input image
TransformImage - Create a new image from an existing image with a user-defined function

See Filter Flags, Texconv, Texassemble

Direct3D 11 / DirectX 12 Helper Functions

Functions for working with the Direct3D 11 / DirectX 12 API using DirectXTex image data.

IsSupportedTexture - Returns true if the given texture metadata is supported by the device
CreateTexture - Creates a Direct3D resource from a set of images
CreateShaderResourceView - Creates a Direct3D 11 resource and shader resource view from a set of images
CaptureTexture - Captures a Direct3D render target and returns an image.

Utility Functions

These functions provide utility functionality when working with DXGI_FORMAT throughout the library.

WIC helpers

GetWICCodec - Returns a WIC GUID for a given file container given a simple enumeration value. This function is optional and you can instead use the WIC container GUID directly instead.

This function exists to make it easier to use the WIC I/O DirectXTex functions without having to include the wincodec.h header globally.

GetWICFactory - Helper to obtain a WIC factory. If not already initialized, a new one is created.
SetWICFactory - Helper to set the WIC factory to use in DirectXTex.

DXGI format tests

IsValid - Returns false if the DXGI format is unknown.
IsCompressed - Returns true if the DXGI format is a block compressed format.
IsPacked - Returns true if the DXGI format is a 'packed' format (such as 4:2:2 video formats)
IsVideo - Returns true if the DXGI format is a DXGI 1.2 'video' format defined for Direct3D 11.1 video.
IsPlanar - Returns true if the DXGI format is a 'planar' format (such as 4:2:0 or 4:1:1 video formats).
IsPalettized - Returns true if the DXGI format is a paletted format (only legacy Direct3D 11.1 video formats are paletted).
IsDepthStencil - Returns true if the DXGI format is for use with depth/stencil resources.
IsSRGB - Returns true if the DXGI format is an sRGB format.
IsBGR - Returns true if the DXGI format is a BGR (as opposed to RGB) format.
IsTypeless - Returns true if the DXGI format is a 'typeless' format. If partialTypeless is 'true' (the default) then formats with both typeless and typed content return true. If partialTypeless is 'false', then the mixed DXGI types (such as DXGI_FORMAT_R32_FLOAT_X8X24_TYPELESS) will return false instead.

DXGI format properties

HasAlpha - Returns true of the DXGI format includes an alpha channel. Note that BC1 formats return true because they have a 'transparency bit' trick in the encoding to handle 1-bit alpha.
BitsPerPixel - Returns the bits-per-pixel for a given DXGI format. For example, it returns 32 for DXGI_FORMAT_R10G10B10A2_UNORM.
BitsPerColor - Returns the color-depth (aka bit-depth) for a given DXGI format. For formats with a mix of different channel sizes, it returns the color-depth of the largest channel. For example, it returns 10 for DXGI_FORMAT_R10G10B10A2_UNORM.
BytesPerBlock - Returns the number of bytes in a compressed block given a DXGI block-compression format.
FormatDataType - Returns the primary data-type for the given DXGI format. The result is FORMAT_TYPE_FLOAT, FORMAT_TYPE_UNORM, FORMAT_TYPE_SNORM, FORMAT_TYPE_UINT, FORMAT_TYPE_SINT, or FORMAT_TYPE_TYPELESS.

Image layout

ComputePitch - Returns both the row and slice pitch for a given width, height, and DXGI format. It supports a number of flags for overriding the default byte-alignment usually used by DDS files and Direct3D 11 resources.
ComputeScanlines - Returns the number of horizontal scanlines in an image given the DXGI format and pixel height.

DXGI format type promoters

MakeSRGB - Converts a DXGI format to the sRGB equivalent if any.
MakeLinear - Converts a DXGI format to the non-sRGB equivalent.
MakeTypeless - Converts a DXGI format to a TYPELESS equivalent if any. This does not modify depth/stencil formats which have multiple 'typeless' mappings.
MakeTypelessUNORM - Converts a TYPELESS DXGI format to a UNORM equivalent if any.
MakeTypelessFLOAT - Converts a TYPELESS DXGI format to a FLOAT equivalent if any.

Note if there is no format that matches the desired property for the input format, the original format is returned.

Structures

TexMetadata contains metadata information about the texture resource and organization such as width, height, depth, format, dimension, etc.

Image contains information about the surface including width, height, format, rowPitch, slicePitch, and a pointer to pixel data. Note that for 1D and 2D images, slicePitch should be set to the full size of the image.

ScratchImage is a helper class that manages memory for functions that return a Image or set of Images.

Blob is a helper class that manages for functions that return a binary blob of data.

Rect contains a simple pixel-based rectangle used by the CopyRectangle function.

Adding to a VS solution

Using project-to-project references

In your application's solution, right-click on the Solution and use "Add \ Existing Project..." to add the appropriate .vcxproj file to your solution.

DirectXTex_Desktop_2022	Windows desktop applications for Windows 7 Service Pack 1 or later building with VS 2022 Community, Professional or higher with the latest installed Windows SDK.
DirectXTex_Desktop_2022_Win10	Windows desktop applications for Windows 10/Windows 11 building with VS 2022 Community, Professional or higher with with the latest installed Windows SDK. This includes DirectX 12 support.
DirectXTex_Windows10_2022	Universal Windows Platform (UWP) apps building with VS 2022 with the latest installed Windows SDK. This includes DirectX 12 support.

DirectXTex_Desktop_2019	Windows desktop applications for Windows 7 Service Pack 1 or later building with VS 2019 Community, Professional or higher with the latest installed Windows SDK.
DirectXTex_Desktop_2019_Win10	Windows desktop applications for Windows 10/Windows 11 building with VS 2019 Community, Professional or higher with the latest installed Windows SDK. This includes DirectX 12 support.
DirectXTex_GDK_2019	Windows 10, Windows 11, and Xbox games building with VS 2019 using the Microsoft GDK.

For VS 2019, use of the 16.11 is required as all previous versions are no longer supported.

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTex project name and click OK. For a Universal Windows Platform (UWP) app or Xbox One solution, you need to set Reference Assembly Output to false since DirectXTex is a static C++ library and not a WinRT component.

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Platforms", and then add the relative path to DirectXTex;--assuming you have the DirectXTex folder in the same directory as your sln file, it should be $(SolutionDir$)\DirectXTex;--to the Additional Include Directories properties. Click Apply.

See the Visual C++ Team Blog

DirectXTex was never supported on Windows Phone 8.0, because WIC is not available on that platform. The .DDS files it generates are suitable for use on Windows Phone 8.x assuming the pixel format is supported by the device (Feature Level 9.3).

Using NuGet package manager

Alternatively you can use NuGet to install one of the DirectXTex packages. Use Project / Manage NuGet Packages... then select "Online" and search for "DirectXTex".

directxtex_desktop_2019	This NuGet package is configured for Windows desktop C++ applications building with VS 2019 or VS 2022 Community/Professional or higher for Windows 7 Service Pack 1 or later.
directxtex_desktop_win10	This NuGet package is configured for Windows desktop C++ applications building with VS 2019 or VS 2022 Community/Professional or higher for Windows 10/Windows 11.This includes DirectX 12 support.
directxtex_uwp	This NuGet package is configured for Universal Windows Platform apps for Windows 10/Windows 11 building with VS 2019, or VS 2022 Community/Professional or higher. This includes DirectX 12 support.

You should use the NuGet interface to check for updates if you have an older version installed.

Archived

These packages are no longer supported:

Using the vcpkg C++ library manager

DirectXTex is also available through the vcpkg C++ Library Manager.

vcpkg install directxtex

For the 64-bit version of the library, use:

vcpkg install directxtex:x64-windows

For the Universal Windows Platform (UWP) versions, use:

vcpkg install directxtex:x64-uwp

arm, arm64, x86, x64, windows, windows-static, windows-static-md, and uwp triplets are supported.

The vcpkg port supports five optional features. The default is to build with DirectX 11 support, but without DirectX 12 support except for UWP which always includes it.

dx11: Adds DirectX 11 API support functions for Windows desktop or UWP.
dx12: Adds DirectX 12 API support functions for Windows 10/Windows 11
tools: Installs texture command-line tools
spectre: Builds the library with Spectre-mitigation enabled
openexr: Adds OpenEXR support
xbox: Adds support for Xbox off-line content processing; requires the Microsoft GDKX

For Windows Subsystem for Linux, use:

./vcpkg install directxtex:x64-linux

./vcpkg install directxtex:arm64-linux

To add the JPEG/PNG auxiliary functions for Linux:

./vcpkg install directxtex[jpeg,png]:x64-linux

Non-Win32 support requires a C++17 conformant compiler & library. GNUC 9 will work; GNUC 11.3 or later is recommended.

For Xbox Series X|S with the Microsoft GDK with Xbox Extensions installed:

vcpkg install directxtex:x64-xbox-scarlett

For Xbox One with the Microsoft GDK with Xbox Extensions installed:

vcpkg install directxtex:x64-xbox-xboxone

CMake

You can reference the DirectXTex CMake package using:

find_package(directxtex CONFIG REQUIRED)

target_link_libraries(foo Microsoft::DirectXTex)

If using CMakePresets.json set the environment variable VCPKG_ROOT and add:

"cacheVariables": {
  CMAKE_TOOLCHAIN_FILE": {
    value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
    "type": "FILEPATH"
  }
},

If not using vcpkg, you have to provide a per-configuration path to the individual installed package in the directxtex_DIR variable. Otherwise the find_package will fail.

Extensions

To support offline texture operations for Xbox, there are DirectXTexXbox extension functions available as well. This also supports the XboxDDSTextureLoader module for DirectX Tool Kit DX11 / DX12.

Dependencies

The DirectXTex library assumes your binary is linking with the following system libraries:

dxguid.lib: Provides COM GUID values for IID_ID3D11Device, IID_ID3D12Device, IID_ID3D12Resource, WKPDID_D3DDebugObjectName, etc.
windowscodecs.lib or uuid.lib: Provides COM GUID values for WIC usage such as CLSID_WICImagingFactory, CLSID_WICImagingFactory1, CLSID_WICImagingFactory2, etc.
For Win32 desktop applications, ole32.lib: Provides CoCreateInstance. For other platforms, this export is in the umbrella library (WindowsApps.lib, onecore.lib, etc.).

On Windows Subsystem for Linux, Windows Imaging Component (WIC) is not available so functionality that requires WIC is not present for that platform. Only DDS, HDR, and TGA file support is included. To support PNG and/or JPEG on this platform, see Using-JPEG-PNG-OSS.

Release Notes

The alpha mode specification for DDS files was updated between the March 2013 and April 2013 releases. Any DDS files created using the DDS_FLAGS_FORCE_DX10_EXT_MISC2 flag or the texconv -dx10 switch using the March 2013 release should be refreshed.
Due to the underlying Windows BMP WIC codec, alpha channels are not supported for 16bpp or 32bpp BMP pixel format files. In Windows 8.x and later, the Windows BMP WIC codec does support 32bpp pixel formats with alpha when using the BITMAPV5HEADER file header. Note the updated WIC is available on Windows 7 SP1 with KB 2670838 installed.
While DXGI 1.0 and DXGI 1.1 include 5:6:5 (DXGI_FORMAT_B5G6R5_UNORM) and 5:5:5:1 (DXGI_FORMAT_B5G5R5A1_UNORM) pixel format enumerations, the DirectX 10.x and 11.0 Runtimes do not support these formats for use with Direct3D. The DirectX 11.1 runtime, DXGI 1.2, and the WDDM 1.2 driver model or later fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).
Loading of 96bpp floating-point TIFF files results in a corrupted image prior to Windows 8. This fix is available on Windows 7 SP1 with KB 2670838 installed.