The FxColorGamutAPI protocol defines the host application methods for retrieving information about a project's color gamut and conversions to other color spaces.


@protocol FxColorGamutAPI


The FxPlug 3.1.1 SDK introduced this new API for working with wide gamut projects. This functionality was introduced in Motion 5.3 and FinalCutPro X 10.3.

Standard and Wide Gamut Footage

All display devices have a range of colors they are able to display. This range is called its gamut. The gamut is defined by its white point, black point, and 3 color primaries defined in the CIE XYZ color space.

In earlier versions, Final Cut Pro X and Motion assumed that the images they produced would be displayed on a device in the Rec. 709 colorspace. Starting with Final Cut Pro X 10.3 and Motion 5.3, users now have the option to choose whether they wish to work in the standard (Rec. 709) color gamut or the wide (Rec. 2020) color gamut.

Televisions, computers, and cell phones have traditionally had displays that worked in the Rec. 709 color space, or the very similar sRGB color space. (Both have the same color primaries.) Recently, new devices that can output a wider range of colors have started being introduced. These include, for example, the wide gamut 5K retina iMac and iPad Pro 9.7” model. They are able to display colors outside of the Rec. 709 color space, allowing them to be more saturated. Now, Final Cut Pro X and Motion can display such footage on capable devices and generate it on export. Regardless of your display device, you can now set your project to work in a wider color gamut.

Your Plug-In and Color Gamuts

Previously, your plug-in was able to request that the host application deliver input frames and interpret output frames in either linear or gamma-corrected space. You could also retrieve the image’s color space via the [-FxImage colorSpace] method. Now, you can mark your images as using either Rec. 709 color primaries (standard gamut) or Rec. 2020 color primaries (wide gamut). To check an image’s color primaries, use the [FxImage fxColorPrimaries] method.

    @method     fxColorPrimaries
    @abstract   Returns an enum describing the color space of the image.
- (FxColorPrimaries)fxColorPrimaries;

The FxColorPrimaries type is an enumerated type with the following values.

    @typedef    FxColorPrimaries
    @discussion An enum that represents a set of color primaries
enum {
    kFxColorPrimaries_Rec709 = 0,
typedef NSUInteger FxColorPrimaries;

These tell you which color primaries the pixels of your images are in. All images are delivered to your plug-in using the same color primaries. You can use the FxColorGamutAPI to handle working with different color primaries. The -colorPrimaries method tells you which primaries your plug-in should render with.

- (FxColorPrimaries)colorPrimaries;

The value returned by the [-FxColorGamutAPI colorPrimaries] method should match the value returned by the [-FxImage fxColorPrimaries] method.

It's common for plug-ins to convert pixels between RGB and Y’CbCr color spaces. Doing so involves a single matrix multiply of the pixel with the proper conversion matrix. Rec. 709 and Rec. 2020 use different matrices for these conversions. The FxColorGamutAPI offers two new methods to retrieve the appropriate matrix.

- (FxMatrix44*)colorMatrixFromDesiredRGBToYCbCrAtTime:(FxTime)time;
- (FxMatrix44*)colorMatrixFromYCbCrToDesiredRGBAtTime:(FxTime)time;

The matrices returned by these methods should be appropriate to use for any images your plug-in receives from or generates for the host. If you only need to convert from RGB to grayscale, you can use the first row of the matrix returned by the -colorMatrixFromDesiredRGBToYCbCrAtTime: method, and take the dot product of the first row of the matrix with your RGB color to convert to grayscale.

Working in Different Color Gamuts

Your plug-ins should be prepared to receive pixels in both Rec. 709 and Rec. 2020. In any given project, they only receive one or the other, but they must be able to work in both.

If a user places wide gamut footage into a standard gamut project and then applies your plug-in to it, some of the color components in the image may contain negative values if they are out-of-gamut for the Rec. 709 color space.

It’s not only images that have different color primaries. Color values are now returned to your plug-in in the same color gamut as the project. Color parameters now allow the user to set each color channel to a value in the range of [-1,2].


Getting Color Gamut Information

- colorMatrixFromDesiredRGBToYCbCrAtTime:

Returns a color matrix for converting RGB values in the project's working gamut into YCbCr values.


- colorMatrixFromYCbCrToDesiredRGBAtTime:

Returns a color matrix for converting YCbCr values to an RGB value in the project's working gamut.


- colorPrimaries

Returns an enumerated type describing the color primaries of the project's working gamut.