mirror of https://github.com/microsoft/DirectXTex synced 2024-09-18 22:59:54 +00:00

Table of Contents

Parameters
Return values

DirectXTex

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 resources.

HRESULT ComputePitch(
   DXGI_FORMAT fmt, size_t width, size_t height,
   size_t& rowPitch, size_t& slicePitch, CP_FLAGS flags = CP_FLAGS_NONE );

Parameters

The rowPitch is the number of bytes in a scanline of pixels in the image. A standard pitch is 'byte' aligned and therefore it is equal to bytes-per-pixel * width-of-image. For block-compressed (BC) formats, this is the number of bytes in a row of blocks (which covers up to 4 scanlines at once). The rowPitch can be larger than the number of valid pixels in the image due to alignment padding.

For volume (3D) textures, slicePitch is the number of bytes in each depth slice. For 1D and 2D images, this is simply the total size of the image including any alignment padding.

A non-standard pitch can computed by the use of the flags parameter:

CP_FLAGS_NONE is the default
CP_FLAGS_LEGACY_DWORD is used for some legacy Direct3D 8 era DDS files, particularly 24bpp files, that used a DWORD alignment instead of BYTE for each row
CP_FLAGS_BAD_DXTN_TAILS is used for some legacy Direct3D 8 era DXTn DDS files that write too little data for the mipmap chains smaller than 4x4.
CP_FLAGS_PARAGRAPH uses a 16-byte alignment for each row. This is useful for creating an image to operate on with SSE/SSE2 aligned loads.
CP_FLAGS_YMM uses a 32-byte alignment for each row. This is useful for creating an image to operate on with AVX/AVX-2 __mm256 aligned loads.
CP_FLAGS_ZMM uses a 64-byte alignment for each row. This is useful for creating an image to operate on with AVX-512 __mm512 aligned loads.
CP_FLAGS_PAGE4K uses a 4096-byte alignment for each row. This is an extreme scenario primarily used only for testing.
CP_FLAGS_24BPP used for computing pitch of Direct3D 9 era 24bpp DDS files (which cannot be indicated by a DXGI_FORMAT)
CP_FLAGS_16BPP used for computing pitch of 16bpp DDS files, specifically legacy formats other than DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, or DXGI_FORMAT_B4G4R4A4_UNORM.
CP_FLAGS_8BPP used for computing pitch of 8bpp DDS files
CP_FLAGS_LIMIT_4GB used to limit maximum pixel block allocation to 4 GB.

These flags only effect standard color formats. They have no effect on BC, packed, or planar format.

Return values

In most cases the function returns S_OK and valid output parameters rowPitch and slicePitch.

If the input DXGI format is unknown, then it can return E_INVALIDARG, which only happens if BitsPerPixel returns 0.

In 32-bit builds, the function will return HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW) if either of the computed pitch values exceed the range of size_t.