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 );

struct ConvertOptions
{
    TEX_FILTER_FLAGS filter;
    float            threshold;
};

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.

Returns

These functions will succeed with an S_OK or will return an HRESULT error code (E_INVALIDARG, E_OUTOFMEMORY, E_FAIL, E_POINTER, E_UNEXPECTED, HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW), HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED), or an error code from Windows Imaging Component).

If the statusCallBack return false, then the function exits with E_ABORT.

On Linux or Windows Subsystem for Linux, any attempt to use WIC results in E_NOTIMPL.

Exceptions

The majority of these functions are marked noexcept, and do not throw C++ exceptions.

The functions which take a statusCallBack are not marked noexcept since it is possible for the callback itself to generate an exception.

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.

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))