mirror of https://github.com/microsoft/DirectXTex synced 2024-11-21 12:00:06 +00:00

Table of Contents

Fields

ScratchImage

Methods

DirectXTex

The Image class is a structure that defines the system memory image most DirectXTex functions operate on.

struct Image
{
    size_t      width;
    size_t      height;
    DXGI_FORMAT format;
    size_t      rowPitch;
    size_t      slicePitch;
    uint8_t*    pixels;
}

Fields

height: For a 1D image this value should be 1.
rowPitch: The number of bytes in a row of pixels including any alignment. It's at least as large as width * BitsPerPixel(format).
slicePitch: The number of bytes in a 3D slice of a volume map. It's at least as large as rowPitch * height.

You should make use of ComputePitch to obtain the row & slice pitch values to ensure you are properly checking for any potential overflow.

pixels: Pointer to the system memory buffer for the pixel data.

Note that for 1D and 2D images, slicePitch should be set to the full size of the image.

ScratchImage

For DirectXTex functions that create new images, the results are returned in an instance of ScratchImage which is a 'container' for Image instances:

Methods

Initialize: Creates a new scratch image given a TexMetadata description. The images are zero'd.
Initialize1D: Creates a 1D or 1D array scratch image with optional mipmap levels. The images are zero'd.
Initialize2D: Creates a 2D or 2D array scratch image with optional mipmap levels. The images are zero'd.
Initialize3D: Create a volume scratch image with optional mipmap levels. The images are zero'd.
InitializeCube: Creates a cubemap or cubemap array wiht optional mipmap levels. The images are zero'd.
InitializeFromImage: Creates a new scratch 1D or 2D image initialized from a source Image. The result has no mipmaps.
InitializeArrayFromImages: Creates a new scratch 1D or 2D array image initialized from an array of source Image instances. The result has no mipmaps.
InitializeCubeFromImages: Creates a cubemap from an array of Image instances. The result has no mipmaps.
Initialize3DFromImages: Creates a volume from an array of Image instances. The result has no mipmaps.

The Initialize functions all accept CP_FLAGS, which is defaulted to CP_FLAGS_NONE.

Release: Releases all memory associated with the ScratchImage.
OverrideFormat: Changes the format for all Image instances in the instance.

Note, the developer user must ensure the new format bits-per-pixel size matches the original or the result will be invalid.

GetMetadata: Returns the TexMetadata structure which describes the instance.
GetImage: Returns the Image given parameters for miplevel (0-based), array item (0-based), and volume slice (0-based). Returns nullptr if the input parameters are out of range.
GetImages, GetImageCount: Returns the array of Image instances and the count.
GetPixels, GetPixelsSize: Returns the system memory that holds all image pixels for the scratch image instance and the size in bytes. This includes all alignment padding as well.
IsAlphaAllOpaque: Returns true if all alpha-channel data in the image is set to fully opaque.