EXT_surface_SMPTE2086_metadata

EGL_EXT_surface_SMPTE2086_metadata

Weiwan Liu (weiwliu 'at' nvidia.com)

Tom Cooksey
Courtney Goeltzenleuchter
Mathias Heyer
Lauri Hyvarinen
James Jones
Daniel Koch
Jeff Leger
Sandeep Shinde

No known IP claims.

Complete

Version 8 - Oct 16, 2017

EGL Extension #109

This extension requires EGL 1.4.

This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).

This extension adds a new set of EGL surface attributes for the metadata
defined by the SMPTE (the Society of Motion Picture and Television
Engineers) ST 2086 standard. The SMPTE 2086 metadata includes the color
primaries, white point and luminance range of the mastering display, which
all together define the color volume that contains all the possible colors
the mastering display can produce. The mastering display is the display
where creative work is done and creative intent is established. To preserve
such creative intent as much as possible and achieve consistent color
reproduction on different viewing displays, it is useful for the display
pipeline to know the color volume of the original mastering display where
content is created or tuned. This avoids performing unnecessary mapping of
colors that are not displayable on the original mastering display.

This extension adds the ability to pass the SMPTE 2086 metadata via EGL,
from which the color volume can be derived. While the general purpose of the
metadata is to assist in the transformation between different color volumes
of different displays and help achieve better color reproduction, it is not
in the scope of this extension to define how exactly the metadata should be
used in such a process. It is up to the implementation to determine how to
make use of the metadata.

None.

Accepted as attribute by eglSurfaceAttrib and eglQuerySurface:

    EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT       0x3341
    EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT       0x3342
    EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT       0x3343
    EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT       0x3344
    EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT       0x3345
    EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT       0x3346
    EGL_SMPTE2086_WHITE_POINT_X_EXT            0x3347
    EGL_SMPTE2086_WHITE_POINT_Y_EXT            0x3348
    EGL_SMPTE2086_MAX_LUMINANCE_EXT            0x3349
    EGL_SMPTE2086_MIN_LUMINANCE_EXT            0x334A

Add the following paragraph before the "Errors" section on page 43,

    If attribute is EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_-
    DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_-
    SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT
    or EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, then value indicates the
    corresponding xy chromaticity coordinate[12] of the mastering display's
    red, green or blue color primary, as configured for the mastering
    process. The floating-point display primary coordinates should be
    multiplied by EGL_METADATA_SCALING_EXT (50000)[13], before being passed
    into eglSurfaceAttrib as integers.

    If attribute is EGL_SMPTE2086_WHITE_POINT_X_EXT or EGL_SMPTE2086_WHITE_-
    POINT_Y_EXT, then value indicates the corresponding xy chromaticity
    coordinate[12] of the mastering display's white point, as configured for
    the mastering process. The floating-point white point chromaticity
    coordinates should be multiplied by EGL_METADATA_SCALING_EXT (50000),
    before being passed into eglSurfaceAttrib as integers.

    If attribute is EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_-
    LUMINANCE_EXT, then value indicates the maximum or minimum display
    luminance of the mastering display, as configured for the mastering
    process. The unit of value is 1 nit (candela per square meter). The
    floating-point luminance values should be multiplied by
    EGL_METADATA_SCALING_EXT, a constant scaling factor of 50000, before
    being passed into eglSurfaceAttrib as integers.

    By defining the mastering display's color volume through color
    primaries, white point, and luminance range, applications give EGL
    and the underlying display pipeline hints as to how to reproduce colors
    more closely to the original content when created on the mastering
    display. Exactly how the color volume information is used to assist the
    color reproduction process is implementation dependant.

    The initial values of EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_-
    SMPTE2086_DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT,
    EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_-
    EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, EGL_SMPTE2086_WHITE_POINT_X_-
    EXT, EGL_SMPTE2086_WHITE_POINT_Y_EXT, EGL_SMPTE2086_MAX_LUMINANCE_EXT
    and EGL_SMPTE2086_MIN_LUMINANCE_EXT are EGL_DONT_CARE, which causes the
    hints to be ignored. If value is not in the implementation's supported
    range for attribute, a EGL_BAD_PARAMETER error is generated, and some or
    all of the metadata fields are ignored.

Add the following footnote at the end of page 43, and increment all the
subsequent footnote numbers in Chapter 3,

        [12] Chromaticity coordinates x and y are as specified in CIE
    15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are
    limited to between 0 and 1 for real colors for the mastering display.

Change the original footnote 12 at the end of section "3.5.6 Surface
Attributes" on page 45 to,

        [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000)
    are used where EGL needs to take or return floating-point attribute
    values, which would normally be smaller than 1, as integers while still
    retaining sufficient precision to be meaningful.

Addition to Table 3.5 "Queryable surface attributes and types",

                  Attribute                   Type
    ------------------------------------------------
    EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT     integer
    EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT     integer
    EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT     integer
    EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT     integer
    EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT     integer
    EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT     integer
    EGL_SMPTE2086_WHITE_POINT_X_EXT          integer
    EGL_SMPTE2086_WHITE_POINT_Y_EXT          integer
    EGL_SMPTE2086_MAX_LUMINANCE_EXT          integer
    EGL_SMPTE2086_MIN_LUMINANCE_EXT          integer

                  Description
    ------------------------------------------------------------------------------------------
    x chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT
    y chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT
    x chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT
    y chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT
    x chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT
    y chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT
    x chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT
    y chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT
    Maximum luminance in nit multiplied by EGL_METADATA_SCALING_EXT
    Minimum luminance in nit multiplied by EGL_METADATA_SCALING_EXT

Add the following paragraph at the end of section "3.5.6 Surface Attributes"
on page 45,

    Querying EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_DISPLAY_-
    PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_SMPTE2086_-
    DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT or EGL_-
    SMPTE2086_DISPLAY_PRIMARY_BY_EXT returns respectively the xy
    chromaticity coordinate of the mastering display's red, green or blue
    color primary, multiplied by the constant value EGL_METADATA_SCALING_EXT
    (50000). The display primary coordinates can be set via eglSurfaceAttrib
    as described above.

    Querying EGL_SMPTE2086_WHITE_POINT_X_EXT, or EGL_SMPTE2086_WHITE_POINT_-
    Y_EXT returns respectively the xy chromaticity coordinate of the
    mastering display's white point, multiplied by the constant value EGL_-
    METADATA_SCALING (50000). The white point coordinates can be set via
    eglSurfaceAttrib as described above.

    Querying EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_-
    LUMINANCE_EXT returns respectively the maximum and minimum display
    luminance of the mastering display. The values returned are in units of
    1 nit (candela per square meter), multiplied by the constant value EGL_-
    METADATA_SCALING (50000). The value of EGL_SMPTE2086_MAX_LUMINANCE_EXT
    and EGL_SMPTE2086_MIN_LUMINANCE_EXT can be set via eglSurfaceAttrib as
    described above.

Described in the body text above.

1. Should this extension define a valid data range for each metadata field?

   RESOLVED: No. It is not in the scope of this extension to define how the
   metadata hints should be used in the display pipeline and, as a result,
   what the valid data ranges are for the metadata fields. It is
   implementation dependant, but related standards, such as SMPTE ST 2086,
   can be used as reference. As described in the body, implemetations may
   generate a EGL_BAD_PARAMTER error to notify applications that the input
   metadata values are invalid or not supported.

Version 1, 2016/04/22
  - Initial draft

Version 2, 2016/05/25
  - Rename to EXT and introduce a new scaling factor

Version 3, 2016/10/19
  - Add an error and revise issue 1

Version 4, 2016/11/22
  - Change status to complete

Version 5, 2016/11/29
  - Add token assigments

Version 6, 2017/02/28
  - Add 'EXT' suffix to 'EGL_METADATA_SCALING'

Version 7, 2017/10/13
  - Rename EGL_INVALID_VALUE (which doesn't exist) to EGL_FALSE

Version 8, 2017/10/16
  - Fix v7 change to use EGL_BAD_PARAMETER as the error code
generated vs. EGL_FALSE which is the expected return value of
the function.