CalculateMipLevels

DirectXTex

Validates and calculates the appropriate number of mipmap levels for given texture dimensions. These utility functions help determine the correct mipmap chain length for 1D, 2D, and 3D textures.

bool CalculateMipLevels(
   size_t width, size_t height,
   size_t& mipLevels ) noexcept;

bool CalculateMipLevels3D(
   size_t width, size_t height, size_t depth,
   size_t& mipLevels ) noexcept;

Parameters

For CalculateMipLevels:

• width - The width of the base texture in pixels
• height - The height of the base texture in pixels
• mipLevels - Input/output parameter for the desired/calculated mipmap levels

For CalculateMipLevels3D:

• width - The width of the base texture in pixels
• height - The height of the base texture in pixels
• depth - The depth of the base texture in pixels
• mipLevels - Input/output parameter for the desired/calculated mipmap levels

The mipLevels parameter behavior depends on its input value:

• If mipLevels is 0: The function calculates and returns the maximum possible number of mipmap levels for the given dimensions.
• If mipLevels is 1: The function sets mipLevels to 1 (no mipmaps, just the base level).
• If mipLevels is greater than 1: The function validates that the requested number of levels is possible for the given dimensions.

Algorithm

The maximum number of mipmap levels is calculated by repeatedly halving each dimension (width, height, and depth for 3D) until at least one dimension reaches 1 pixel. The total number of levels includes the original base level plus all reduced levels.

For example:

• A 256×256 texture can have up to 9 mipmap levels: 256×256, 128×128, 64×64, 32×32, 16×16, 8×8, 4×4, 2×2, 1×1
• A 256×128×64 3D texture can have up to 9 mipmap levels: 256×128×64, 128×64×32, 64×32×16, 32×16×8, 16×8×4, 8×4×2, 4×2×1, 2×1×1, 1×1×1

Returns

true if the operation succeeded and mipLevels contains a valid value.

false if the requested mipLevels exceeds the maximum possible for the given dimensions. In this case, mipLevels is not modified.

Example Usage

// Calculate maximum mipmap levels for a 1024x512 texture
size_t mipLevels = 0;
if (CalculateMipLevels(1024, 512, mipLevels))
{
    // mipLevels will be 11 (1024->512->256->128->64->32->16->8->4->2->1)
}

// Validate that 5 mipmap levels are possible for a 256x256 texture
mipLevels = 5;
if (CalculateMipLevels(256, 256, mipLevels))
{
    // Valid: 256x256 can support up to 9 levels, so 5 is acceptable
}

// Calculate maximum mipmap levels for a 64x64x32 volume texture
mipLevels = 0;
if (CalculateMipLevels3D(64, 64, 32, mipLevels))
{
    // mipLevels will be 7 (64×64×32->32×32×16->16×16×8->8×8×4->4×4×2->2×2×1->1×1×1)
}

Remarks

These functions are commonly used in conjunction with mipmap generation functions like GenerateMipMaps and GenerateMipMaps3D to ensure the requested number of mipmap levels is valid before attempting generation.

The functions use a simple bit-shifting algorithm to calculate mipmap dimensions, which is the standard approach for power-of-two and non-power-of-two textures in DirectX.

Exceptions

These functions are marked noexcept, and do not throw C++ exceptions.

See Also

GenerateMipMaps, GenerateMipMaps3D, TexMetadata