Color management effect
Use the color management effect to transform an image from one ICC (International Color Consortium) color profile to another. The effect transforms the image according to the ICC specification.
The CLSID for this effect is CLSID_D2D1ColorManagement.
- Effect properties
- Rendering intent modes
- Input image alpha modes
- Compliance with ICC specification
- Alpha channel behavior
- Quality modes
- Sample code
- Requirements
- Related topics
Effect properties
| Display name and index enumeration | Description |
|---|---|
| SourceContext D2D1_COLORMANAGEMENT_PROP_SOURCE_COLOR_CONTEXT |
The source color space information. The type is ID2D1ColorContext. The default value is NULL. |
| SourceIntent D2D1_COLORMANAGEMENT_PROP_SOURCE_RENDERING_INTENT |
Which ICC rendering intent to use. The type is D2D1_COLORMANAGEMENT_RENDERING_INTENT. The default value is D2D1_COLORMANAGEMENT_RENDERING_INTENT_PERCEPTUAL. |
| DestinationContext D2D1_COLORMANAGEMENT_PROP_DESTINATION_COLOR_CONTEXT |
The destination color space information. The type is ID2D1ColorContext. The default value is NULL. |
| DestinationIntent D2D1_COLORMANAGEMENT_PROP_DESTINATION_RENDERING_INTENT |
Which ICC rendering intent to use. The type is D2D1_COLORMANAGEMENT_RENDERING_INTENT. The default value is D2D1_COLORMANAGEMENT_RENDERING_INTENT_PERCEPTUAL. |
| AlphaMode D2D1_COLORMANAGEMENT_PROP_ALPHA_MODE |
How to interpret alpha data that is contained in the input image. The type is D2D1_COLORMANAGEMENT_ALPHA_MODE. The default value is D2D1_COLORMANAGEMENT_ALPHA_MODE_PREMULTIPLIED. |
| Quality D2D1_COLORMANAGEMENT_PROP_QUALITY |
The quality level of the transform. The type is D2D1_COLORMANAGEMENT_QUALITY. The default value is D2D1_COLORMANAGEMENT_QUALITY_NORMAL. |
Rendering intent modes
| Enumeration | Description |
|---|---|
| D2D1_COLORMANAGEMENT_RENDERING_INTENT_PERCEPTUAL | The effect compresses or expands the full color gamut of the image to fill the color gamut of the device, to produce a perceptually pleasing output that preserves color details but may sacrifice colorimetric accuracy. It is useful for general reproduction of real life content such as photos. |
| D2D1_COLORMANAGEMENT_RENDERING_INTENT_RELATIVE_COLORIMETRIC | The effect adjusts any colors that fall outside the gamut that the output device can render to the closest color that can be rendered. It does not preserve the white point. |
| D2D1_COLORMANAGEMENT_RENDERING_INTENT_SATURATION | The effect preserves the saturation of pure colors in the image at the possible expense of hue and lightness. It is useful for graphics like charts and diagrams. |
| D2D1_COLORMANAGEMENT_RENDERING_INTENT_ABSOLUTE_COLORIMETRIC | The effect adjusts any colors that fall outside the gamut that the output device can render to the closest color that can be rendered. The effect does not change the in-gamut colors and preserves the white point. |
Input image alpha modes
| Enumeration | Description |
|---|---|
| D2D1_COLORMANAGEMENT_ALPHA_MODE_PREMULTIPLIED | The effect assumes the alpha mode is premultiplied. |
| D2D1_COLORMANAGEMENT_ALPHA_MODE_STRAIGHT | The effect assumes the alpha mode is straight. |
D2D1_GAMMA1_G2084 behavior changes
If your application uses the D2D1_GAMMA1_G2084 space, or one of the DXGI_COLOR_SPACE_TYPE enumeration values that use the SMPTE ST.2084 (Perceptual Quantizer) color space, then the application intends to work with HDR data.
The ID2D1DeviceContext5::CreateColorContextFromSimpleColorProfile and ID2D1DeviceContext5::CreateColorContextFromDxgiColorSpace APIs don't account for that; rather, the HDR content is scaled to fit in the 0-1 range during the G2084 DeGamma operation.
In practice, content that is encoded in this gamma space uses a reference WhiteLevel of 10,000 Nits, which would normally be represented in CCCS as 10,000 / 80 = 125.0. So, to better facilitate your app, it's simplest for this gamma conversion to also scale the luminance by a factor of 125. As of Windows 10, version 1809 (10.0; Build 17763), the behavior of the color management effect is such that it applies this scaling. That means that you, as the developer, don't have to apply a second White level adjustment effect into the pipeline.
Compliance with ICC specification
The color management effect is compliant with the ICC v4.3 specification, with these limitations:
- The effect supports 1, 3, and 4 channel color spaces.
- The effect doesn't support ColorSpace or Named Color profiles.
Alpha channel behavior
In general, the effect sets alpha to 1 (opaque) if there is no alpha data in the source image and the alpha data is discarded if there is no room in the destination image. The table here describes the alpha behavior.
| Source colorspace, pixel format | Destination colorspace, pixel format | Alpha behavior |
|---|---|---|
| 1 channel, R pixel format |
1 channel, R pixel format | (No alpha data) |
| 1 channel, RGBA pixel format | Alpha data is set to 1 (opaque) | |
| 3 channel, RGBA pixel format | Alpha data is set to 1 (opaque) | |
| 4 channel, RGBA pixel format | (No alpha data) | |
| 1 channel, RGBA pixel format |
1 channel, R pixel format | Alpha data is discarded |
| 1 channel, RGBA pixel format | Alpha data is passed through | |
| 3 channel, RGBA pixel format | Alpha data is passed through | |
| 4 channel, RGBA pixel format | Alpha data is discarded | |
| 3 channel, RGBA pixel format |
1 channel, R pixel format | Alpha data is discarded |
| 1 channel, RGBA pixel format | Alpha data is passed through | |
| 3 channel, RGBA pixel format | Alpha data is passed through | |
| 4 channel, RGBA pixel format | Alpha data is discarded | |
| 4 channel, RGBA pixel format |
1 channel, R pixel format | (No alpha data) |
| 1 channel, RGBA pixel format | Alpha data is set to 1 (opaque) | |
| 3 channel, RGBA pixel format | Alpha data is set to 1 (opaque) | |
| 4 channel, RGBA pixel format | (No alpha data) |
Quality modes
| Mode | Description |
|---|---|
| D2D1_COLORMANAGEMENT_QUALITY_PROOF | The lowest quality mode. This mode requires feature level 9_1 or above. |
| D2D1_COLORMANAGEMENT_QUALITY_NORMAL | Normal quality mode. This mode requires feature level 9_1 or above. |
| D2D1_COLORMANAGEMENT_QUALITY_BEST | The best quality mode. This mode requires feature level 10_0 or above, as well as floating point precision buffers. This mode supports floating point precision as well as extended range as defined in the ICC v4.3 specification. |
The color management effect fails when drawing if the application requests a quality mode that is not supported by the hardware. You can determine the feature level when you call D3D11CreateDevice. You can check for floating point buffer support by calling ID2D1EffectContext::IsBufferPrecisionSupported with the value D2D1_BUFFER_PRECISION_32BPC_FLOAT.
Sample code
For an example of this effect, download the Direct2D effects photo adjustment sample, and see Lesson 4 of the sample.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps] |
| Minimum supported server | Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps] |
| Header | d2d1effects.h |
| Library | d2d1.lib, dxguid.lib |
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for