PremultiplyAlpha

DirectXTex

This converts an image to using premultiplied alpha. The format and size are not changed.

Note that the conversion to premultipled alpha is not fully reversible. For example if alpha is 0, then all the color information becomes 0.

HRESULT PremultiplyAlpha( const Image& srcImage, TEX_PMALPHA_FLAGS flags,
    ScratchImage& image );

HRESULT PremultiplyAlpha( const Image* srcImages, size_t nimages,
    const TexMetadata& metadata, TEX_PMALPHA_FLAGS flags,
    ScratchImage& result );

Breaking Change notice: The flags parameter was not present in the August 2013 and previous versions of DirectXTex.

Parameters

flags: Combination of options to apply

• PMALPHA_IGNORE_SRGB Ignore any sRGB colorspace conversions

• TEX_PMALPHA_REVERSE If set to true, then the conversion goes from premultipled alpha to nonpremultipled alpha (a.k.a. straight alpha).

This controls color space transformation for conversions.

• TEX_PMALPHA_SRGB_IN Indicates the input format is the sRGB format. This is implied if using a DXGI_FORMAT_*_SRGB format
• TEX_PMALPHA_SRGB_OUT Indicates the output format is the sRGB format. This is implied if using a DXGI_FORMAT_*_SRGB format
• TEX_PMALPHA_SRGB This is the same as setting both TEX_PMALPHA_SRGB_IN and TEX_PMALPHA_SRGB_OUT

Returns

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

Exceptions

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

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 is most useful for working with rendering that relies on premultiplied alpha blending (see DirectX Tool Kit for DX11 / DX12).

Example

ScratchImage srcImage;

...

ScratchImage destImage;
hr = PremultiplyAlpha( srcImage.GetImages(), srcImage.GetImageCount(),
    srcImage.GetMetadata(), TEX_PMALPHA_DEFAULT, destImage );
if ( FAILED(hr) )
    ...

Further reading

Premultiplied alpha
Premultiplied alpha and image composition
Premultiplied alpha in XNA Game Studio 4.0

Gamma Correction vs. Premultiplied Pixels