Содержание
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 thanDXGI_FORMAT_B5G6R5_UNORM
,DXGI_FORMAT_B5G5R5A1_UNORM
, orDXGI_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
.
For Use
- Universal Windows Platform apps
- Windows desktop apps
- Windows 11
- Windows 10
- Windows 8.1
- Windows 7 Service Pack 1
- Xbox One
- Xbox Series X|S
- Windows Subsystem for Linux
Architecture
- x86
- x64
- ARM64
For Development
- Visual Studio 2022
- Visual Studio 2019 (16.11)
- clang/LLVM v12 - v18
- GCC 10.5, 11.4, 12.3
- MinGW 12.2, 13.2
- CMake 3.20
Related Projects
DirectX Tool Kit for DirectX 11
DirectX Tool Kit for DirectX 12
Tools
See also
All content and source code for this package are subject to the terms of the MIT License.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.