Convert

DirectXTex

Convert an image or set of images from one pixel format to another.

HRESULT Convert(
    const Image& srcImage,
    DXGI_FORMAT format, TEX_FILTER_FLAGS filter,
    float threshold, ScratchImage& image );

HRESULT Convert(
    const Image* srcImages, size_t nimages,
    const TexMetadata& metadata,
    DXGI_FORMAT format, TEX_FILTER_FLAGS filter,
    float threshold, ScratchImage& result );

HRESULT ConvertEx(
    const Image& srcImage,
    DXGI_FORMAT format, const ConvertOptions& options,
    ScratchImage& image,
    std::function<bool (size_t, size_t)> statusCallBack = nullptr);

HRESULT ConvertEx(
    const Image* srcImages,
    size_t nimages, const TexMetadata& metadata,
    DXGI_FORMAT format, const ConvertOptions& options,
    ScratchImage& result,
    std::function<bool (size_t, size_t)> statusCallBack = nullptr);

Parameters

format: Target format for conversion.

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

threshold: Alpha threshold used for converting to single bit alpha channels (0.0 to 1.0 range). Typically use is to pass TEX_THRESHOLD_DEFAULT (0.5).

options: The Ex versions take the parameters filter, threshold, etc. using the ConvertOptions structure.

statusCallBack: This is an optional status callback invoked during processing. If the status callback returns false, then the function is exited with an E_ABORT.

Example

ScratchImage srcImage;

...

ScratchImage destImage;
hr = Convert( srcImage.GetImages(), srcImage.GetImageCount(),
    srcImage.GetMetadata(),
    DXGI_FORMAT_R8G8B8A8_UNORM, TEX_FILTER_DEFAULT, TEX_THRESHOLD_DEFAULT,
    destImage );
if ( FAILED(hr) )
    ...

...
ConvertOptions opts = {};
opts.filter = TEX_FILTER_DEFAULT;
opts.threshold = TEX_THRESHOLD_DEFAULT;

hr = ConvertEx( srcImage.GetImages(), srcImage.GetImageCount(),
    srcImage.GetMetadata(),
    DXGI_FORMAT_R8G8B8A8_UNORM, opts,
    destImage,
    [&](size_t current, size_t count) -> bool
    {
        // Do status update here current of count
        return true;
    });
 );
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.

This function is implemented with both WIC and non-WIC code paths. The non-WIC paths is generally used when the standard WIC conversion behavior is unintuitive for textures or would modify the color space in unexpected ways.