DirectXTex provides a texture library and includes many functions for converting legacy Direct Draw Surface (DDS) formats, as well as .TGA files and a WIC based bitmaps (including .BMP, .JPG, .PNG, .TIFF and HD Photo images). DirectXTex can be used to build tools or titles. The xtexconv sample includes auxiliary functions which extend DirectXTex with Xbox One specific texture tiling operations using the XG library.
The DirectXTex library is used for the samples provided for Xbox One. See also Running the XDK Samples.
There are a number of headers included in the DirectXTex library, but only DirectXTex.h is public-facing. Scoped.h, DDS.h, BC.h, and DirectXTexP.h provide internal support for the public-facing functions.
To use the DirectXTex library, copy all the files from the Common/DirectXTex folder, which can be found included with most Xbox One samples. DirectXTex.h is the only header that needs to be explictly included in your title code.
Sections:
The public DirectXText functions can be divided into the following groups:
For functions listed alphabetically, see DirectXTex Functions.
The following functions support file I/O for .DDS files, and include support for many legacy (DirectX 9) file formats, and all DirectX 10 and 11 .DDS files.
| Method | Description |
|---|---|
| GetMetadataFromDDSMemory | Returns the texture metadata from a file image stored in a memory buffer. |
| GetMetadataFromDDSFile | Returns the texture metadata from a file. |
| LoadFromDDSMemory | Loads a .DDS file from an image in a memory buffer. |
| LoadFromDDSFile | Loads a .DDS file. |
| SaveToDDSMemory | Saves one or more images in memory buffers to a .DDS file image also in a memory buffer. |
| SaveToDDSFile | Saves one or more images in memory buffers to a .DDS file. |
CodePlex also shows Examples and Related Flags.
The following functions implement a bitmap reader and writer for the Targa Truvision (.TGA) format.
| Method | Description |
|---|---|
| GetMetadataFromTGAMemory | Returns the texture metadata from a file image stored in a memory buffer. |
| GetMetadataFromTGAFile | Returns the texture metadata from a file. |
| LoadFromTGAMemory | Loads a .TGA file from an image in a memory buffer. |
| LoadFromTGAFile | Loads a .TGA file. |
| SaveToTGAMemory | Saves one or more images in memory buffers to a .TGA file image also in a memory buffer. |
| SaveToTGAFile | Saves one or more images in memory buffers to a .TGA file. |
CodePlex also shows Examples and Implementation Notes.
The following functions implement a bitmap reader and writer for the Windows Imaging Component (.WIC) file formats. These functions use the built-in codecs in Windows for the following formats: .BMP, .PNG, .JPEG, .GIF, .TIFF, and JPEG-XR /HD Photo. Containers such as .GIF and .TIFF can contain multi-frame bitmap images.
| Method | Description |
|---|---|
| GetMetadataFromWICMemory | Returns the texture metadata from a file image stored in a memory buffer. |
| GetMetadataFromWICFile | Returns the texture metadata from a file. |
| LoadFromWICMemory | Loads a .WIC file from an image in a memory buffer. |
| LoadFromWICFile | Loads a .WIC file. |
| SaveToWICMemory | Saves one or more images in memory buffers to a .WIC file image also in a memory buffer. |
| SaveToWICFile | Saves one or more images in memory buffers to a .WIC file. |
CodePlex also shows Examples, Related Flags, and Release Notes.
This set of functions provides some texture processing options. Typically this would be from a WIC or TGA formatted image, to a .DDS file.
Some functions have a page at CodePlex showing example code.
| Method | Description |
|---|---|
| FlipRotate | Flip horizontally or vertically, or rotate by 90, 180 or 270 degrees, one or more images. |
| Resize | Resize one or more images. |
| Convert | Converts one or more images from one pixel format to another. Block compressed (BC) formats are not supported. |
| GenerateMipMaps | Generate mipmaps for one or more images. |
| GenerateMipMaps3D | Generate mipmaps for 3D volume textures, from a set of 2D images representing slices of the volume. |
| PremultiplyAlpha | Converts an image assuming the original is not using premultiplied alpha into a premultiplied alpha version of the same image. |
| Compress | Compresses one or more images to a block compression (BC) format. |
| Decompress | Converts one or more images from a block compressed (BC) format to a non-BC format. |
| ComputeNormalMap | Converts a height map to a normal map. |
| CopyRectangle | Copies a rectangular area from a source image to a destination image. Block compression (BC) formats are not supported. |
| ComputeMSE | Computes the mean squared error (MSE) for each component, based on two input images. |
CodePlex also shows Examples (via Texconv) and Related Flags.
The following utility functions are intended for use in tools when working with Direct3D 11 methods and the DirectXTex library.
For runtime loading of resources, we strongly recommend using DDSTextureLoader, and/or WICTextureLoader instead of DirectXTex. For simple screenshot captures, consider using ScreenGrab.
| Method | Description |
|---|---|
| IsSupportedTexture | Given a texture, returns true if it is supported by the D3D11 device. |
| CreateTexture | Creates a texture resource from one or more images. |
| CreateShaderResourceView | Creates both a shader resource view and a texture resource from one or more images. |
| CreateTextureEx | Creates a Direct3D 11 texture resource from a set of images, specifying extended parameters to control the created resource’s usage, binding flags, CPU access flags, and miscellaneous flags. |
| CreateShaderResourceViewEx | Creates a Direct3D 11 resource and shader resource view from a set of images, specifying extended parameters to control the created resource’s usage, binding flags, CPU access flags, and miscellaneous flags. |
| CaptureTexture | Captures a render target and returns an image. |
CodePlex page about these functions
The following functions provide some support for the DXGI_FORMAT.
| Method | Description |
|---|---|
| GetWICCodec | Returns a WIC GUID for a given file container. |
| IsValid | Returns false if the DXGI format is unknown. |
| IsCompressed | Returns true if the DXGI format is in a block compressed (BC) format. |
| IsPacked | Returns true if the DXGI format is a packed format. |
| IsVideo | Returns true if the DXGI format is a DXGI 1.2 format that is not supported for general use by DirectX 11. |
| IsSRGB | Returns true if the DXGI format is RGB based. |
| IsTypeless | Returns true if the DXGI format is a typeless format. |
| HasAlpha | Returns true of the DXGI format includes an alpha channel. Note that BC1 formats return false because they don’t support an alpha channel, although they do have a ‘transparency bit’ trick in the encoding. |
| BitsPerPixel | Returns the bits per pixel, given the DXGI format. |
| BitsPerColor | Returns the color-depth (the 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. |
| ComputePitch | Returns the row and slice pitch, for a given width, height and DXGI format. |
| ComputeScanlines | Returns the number of scanlines in an image, given the height and DXGI format. |
| MakeSRGB | Converts the DXGI format to an equivalent sRGB format, if one exists. |
| MakeTypeless | Converts a DXGI format to a TYPELESS equiavlent 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. |
CodePlex page about these functions
The normal use of the DirectXTex library is in building tools, including viewers, and in preparing textures in .DDS format for the DDSTextureLoader module to load as part of the actual title.
Key to the use of DirectXTex are the Image and ScratchImage structures. The Image structure describes the surface but it does not hold the memory. The ScratchImage structure holds the memory for the various outputs so they can be cleaned up, the DirectXTex library only operates in terms of taking data pointed to by an Image or multiple Image instances and then creating the results in a ScratchImage.
To create a texture array from a series of images:
ScratchImage src[6];
ScratchImage tmp[6];
Image itemp[6];
for(i=0; i<6; ++i)
{
itemp[i] = tmp[i].GetImages()[0];
}
If step 5 is changed to a call to ScratchImage::ScratchImage::InitializeCubeFromImages then a cube map where each image is a face is constructed (it requires a multiply of six faces). If step 5 is changed to a call to ScratchImage::Initialize3DFromImages then a volume map where each image is a slice of depth is constructed.
For more complicated image compositing you can make use of CopyRectangle to move the data from one Image (or ScratchImage) into a particular location in a new ScratchImage. For example: