Managing color space and gamut in plug-ins
Control the appearance of your rendering by using the color gamut API.
Overview
Motion and Final Cut Pro use a color-managed pipeline for rendering. They keep track of the color spaces the source clips define, and convert images and colors from one color space to another as necessary in order to preserve their intended appearance.
When the host app calls your FxPlug plug-in to render, the host app passes input images and colors that the host app already converted to the working color space. The plug-in’s desired color space, which the plug-in controls, and the gamut that Motion and Final Cut Pro use, which the user controls, uniquely determine the working color space. You usually don’t need to convert from one color space to another. (The only exceptions are plug-ins that do specialized processing in specific color spaces.)
Understand color values and color spaces
Both a color’s component values and its defining color space determine its appearance. For example, the RGB values (0.5, 0.5, 0.5) appear as middle gray in the sRGB color space, but in the Rec. 709 color space, the same values appear as a slightly brighter gray. To display the same middle gray in Rec. 709, the plug-in must change the color values so that the sRGB color (0.5, 0.5, 0.5) appears to the eye as the same shade of gray as Rec. 709 (0.45, 0.45, 0.45).
[Image]
The fact that both the component values and the color space control the color appearance can have some surprising implications. For example, in general, two colors with identical components appear differently to the eye if those two colors use different color spaces. Similarly, two colors that appear the same have different color components if those two colors use different color spaces.
When you create a color channel using the FxParameterCreationAPI_v5, the host app assumes that default RGB values you supply are to be in the sRGB color space. The host app also uses the sRGB color space when the inspector displays color component values. However, when FxParameterRetrievalAPI_v7 gets the color components, it converts sRGB values to the working color space. For example, if the color channel shows the components (0.2, 0.4, 0.6) and the working color space is linear Rec. 709, your plug-in receives (0.033, 0.133, 0.3189) as the value of the color. These converted color components are correct; both color values display as the same identical dark blue color.
Set the desired color space
Your plug-in can tell Motion and Final Cut Pro whether you prefer the working color space to be a gamma-corrected color space or a linear color space. Whether your plug-in requires gamma-corrected or linear pixels is the plug-in’s desired color space.
Your plug-in specifies the desired color space by setting the value of the kFxPropertyKey_DesiredProcessingColorInfo key in its properties dictionary to either kFxImageColorInfo_RGB_GAMMA_VIDEO or kFxImageColorInfo_RGB_LINEAR. If your plug-in doesn’t set the value of this key, the default is kFxImageColorInfo_RGB_LINEAR.
Determine the color gamut in use for the working color space
All color spaces have a range of colors that the color space defines, called the color space’s gamut. This gamut usually corresponds to color components that are in the range [0, 1] (some color spaces support extended range, where components can be less than 0 or greater than 1). When a color has components that are outside of the range for a color space, the color is out of gamut.
Display devices also have a gamut. In the past, television, computer, and phone displays commonly had a gamut similar to the Rec. 709 color gamut. Now, however, many devices can display a wider range of colors, which allows the colors to have a brighter or more saturated appearance.
To get the FxColorPrimaries value for the project that uses your plug-in, use the colorPrimaries() method of the FxColorGamutAPI protocol:
The FxColorPrimaries enumerated type defines the two choices of color gamut:
- kFxColorPrimaries_Rec709
Standard Rec. 709 gamut.
- kFxColorPrimaries_Rec2020
Rec. 2020 Wide Gamut HDR.
These values correspond to the color processing settings in Motion or Final Cut Pro. For more information, see Use wide-gamut HDR color processing in Motion and Use wide-gamut HDR color processing in Final Cut Pro.
[Image]
Determine the working color space
Between the plug-in’s desired color space and the gamut the FxColorGamutAPI_v2 protocol returns to your plug-in, you can determine what the actual working color space is when the host app calls your plug-in. This table describes the working color space for each combination of desired color space and color gamut value. The rows of this table are desired color space values, while the columns are gamut values.
The linear Rec. 709 color space | The linear Rec. 2020 color space | |
The Rec. 709 color space | The Rec. 2020 color space |
When the host app calls your plug-in to render, Motion and Final Cut Pro provide input images in the working color space. If you retrieve the values of color parameters, the host app provides the values in the working color space (unless your color parameter uses kFxParameterFlag_DONT_REMAP_COLORS, in which case, the host app retrieves the components without conversion). Similarly, Motion and Final Cut Pro assume that the output image your plug-in renders is in the working color space.
As mentioned earlier, your plug-in must be able to accept colors outside the [0, 1] range. Values above 1.0 generally behave in an intuitive way: the higher the value, the brighter the color. Thus, (1.5, 0, 0) is a brighter red than (1, 0, 0). However, negative values don’t correspond to dimmer colors, as one might expect; instead, they correspond to higher saturation. For example, (1, 1, 0) is a fully (in-gamut) saturated yellow. But (1, 1, -0.2) is an even more saturated yellow that is out of gamut for the color space.
Negative color components can produce unexpected results in certain calculations. For example, the host app computes luminance as a weighted sum of the RGB components. If one or more of the components is negative, it artificially skews the luminance lower and can lead to unexpected rendering results. Nontrivial blending operations can also produce surprising results with component values outside of [0, 1].
You must determine the best way for your plug-in to deal with such values. Simple options include clamping or taking the absolute value of the components; more sophisticated methods try to map out-of-gamut colors to in-gamut colors. The best solution depends on what your plug-in does and what results your users expect. There is no universally correct answer.
Convert pixels between RGB and YCbCr
FxColorGamutAPI_v2 has two methods for obtaining matrices to convert pixels between RGB and YCbCr color spaces. Plug-ins commonly convert pixels between RGB and YCbCr color spaces using a single matrix multiply of the pixel and the desired conversion matrix. These two methods retrieve the appropriate matrices:
You can use the matrix that colorMatrixFromDesiredRGBToYCbCr() returns to convert from RGB pixels the host provides to your plug-in in the working space to the equivalent YCbCr pixels. Conversely, you can use the matrix that colorMatrixFromYCbCrToDesiredRGB() returns to convert YCbCr pixels back to the RGB working color space.
If you need to convert from RGB to luminance only, you can use the matrix the colorMatrixFromDesiredRGBToYCbCr() method returns. Computing the dot product of the first row of the matrix with the RGB color obtains the luminance.