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

Table of Contents

Parameters
Example
Remarks
Release Notes

DirectXTex

Generates mipmaps for an image or a set of images.

This generates mipmaps for 1D and 2D dimension textures. For 3D dimension textures (a.k.a. volume maps), see GenerateMipMaps3D.

HRESULT GenerateMipMaps( const Image& baseImage, TEX_FILTER_FLAGS filter,
    size_t levels,
    ScratchImage& mipChain, bool allow1D = false );

HRESULT GenerateMipMaps( const Image* srcImages, size_t nimages,
    const TexMetadata& metadata,
    TEX_FILTER_FLAGS filter, size_t levels,
    ScratchImage& mipChain );

Parameters

baseImage: The mipmap chain is created by repeatedly down-sizing a base image. The first level of the resulting mipChain is set to a copy of the input baseImage.

filter: One or more Filter Flags. The default value is TEX_FILTER_DEFAULT.

levels: Number of mip map levels including base. A value of 0 indicates creating a full mipmap chain down to 1x1

allow1D: If set to true and given an input baseImage with a height of 1 then the resulting mipChain will be a TEX_DIMENSION_TEXTURE1D. Otherwise the resulting mipChain is a TEX_DIMENSION_TEXTURE2D.

Example

ScratchImage baseImage;

...

ScratchImage mipChain;
hr = GenerateMipMaps( baseImage.GetImages(), baseImage.GetImageCount(),
    baseImage.GetMetadata(), TEX_FILTER_DEFAULT, 0, mipChain );
if ( FAILED(hr) )
    ...

Remarks

This function does not operate directly on block compressed images. See Decompress and Compress.

This function cannot operate directly on a planar format image. See ConvertToSinglePlane for a method for converting planar data to a format that is supported by this routine.

The second version of GenerateMipMaps is intended for working with 1D arrays, 2D arrays, cubemaps, and cubemap arrays with mipmaps. For volume maps, see GenerateMipMaps3D

This function is implemented with both WIC and non-WIC code paths. The WIC code paths are used for > 8-bit color depth formats, sRGB color formats, or when WRAP/MIRROR semantics are requested.

Release Notes

When resizing HDR images, be sure to stick with the default of TEX_FILTER_FANT when using WIC as the IWICBitmapScalar has limited supported for high bit-depth and extended range formats. By default, the DirectXTex library chooses to use non-WIC codepaths when generating mipmaps for > 8 color-depth images with LINEAR or CUBIC filtering, with sRGB images, with MIRROR/WRAP semantics, or when using TRIANGLE filtering. It will also select non-WIC paths when dealing with 16k textures that are too large for WIC.
On Windows 10 Creators Update (16299) or later, WIC has better handling when using the IWICBitmapScalar with 10:10:10:2 and float16 formats. On older versions of Windows, it will return the results for these formats as 32bpp which is then reconverted to the target format but with a loss of precision. You may want to use TEX_FILTER_FORCE_NON_WIC if the results you are getting appear to be losing precision on older releases of Windows.