1Name 2 3 EXT_surface_SMPTE2086_metadata 4 5Name Strings 6 7 EGL_EXT_surface_SMPTE2086_metadata 8 9Contact 10 11 Weiwan Liu (weiwliu 'at' nvidia.com) 12 13Contributors 14 15 Tom Cooksey 16 Courtney Goeltzenleuchter 17 Mathias Heyer 18 Lauri Hyvarinen 19 James Jones 20 Daniel Koch 21 Jeff Leger 22 Sandeep Shinde 23 24IP Status 25 26 No known IP claims. 27 28Status 29 30 Complete 31 32Version 33 34 Version 8 - Oct 16, 2017 35 36Number 37 38 EGL Extension #109 39 40Dependencies 41 42 This extension requires EGL 1.4. 43 44 This extension is written against the wording of the EGL 1.5 specification 45 (August 27, 2014). 46 47Overview 48 49 This extension adds a new set of EGL surface attributes for the metadata 50 defined by the SMPTE (the Society of Motion Picture and Television 51 Engineers) ST 2086 standard. The SMPTE 2086 metadata includes the color 52 primaries, white point and luminance range of the mastering display, which 53 all together define the color volume that contains all the possible colors 54 the mastering display can produce. The mastering display is the display 55 where creative work is done and creative intent is established. To preserve 56 such creative intent as much as possible and achieve consistent color 57 reproduction on different viewing displays, it is useful for the display 58 pipeline to know the color volume of the original mastering display where 59 content is created or tuned. This avoids performing unnecessary mapping of 60 colors that are not displayable on the original mastering display. 61 62 This extension adds the ability to pass the SMPTE 2086 metadata via EGL, 63 from which the color volume can be derived. While the general purpose of the 64 metadata is to assist in the transformation between different color volumes 65 of different displays and help achieve better color reproduction, it is not 66 in the scope of this extension to define how exactly the metadata should be 67 used in such a process. It is up to the implementation to determine how to 68 make use of the metadata. 69 70New Procedures and Functions 71 72 None. 73 74New Tokens 75 76 Accepted as attribute by eglSurfaceAttrib and eglQuerySurface: 77 78 EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT 0x3341 79 EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT 0x3342 80 EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT 0x3343 81 EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT 0x3344 82 EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT 0x3345 83 EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT 0x3346 84 EGL_SMPTE2086_WHITE_POINT_X_EXT 0x3347 85 EGL_SMPTE2086_WHITE_POINT_Y_EXT 0x3348 86 EGL_SMPTE2086_MAX_LUMINANCE_EXT 0x3349 87 EGL_SMPTE2086_MIN_LUMINANCE_EXT 0x334A 88 89Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification 90 91 Add the following paragraph before the "Errors" section on page 43, 92 93 If attribute is EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_- 94 DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_- 95 SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT 96 or EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, then value indicates the 97 corresponding xy chromaticity coordinate[12] of the mastering display's 98 red, green or blue color primary, as configured for the mastering 99 process. The floating-point display primary coordinates should be 100 multiplied by EGL_METADATA_SCALING_EXT (50000)[13], before being passed 101 into eglSurfaceAttrib as integers. 102 103 If attribute is EGL_SMPTE2086_WHITE_POINT_X_EXT or EGL_SMPTE2086_WHITE_- 104 POINT_Y_EXT, then value indicates the corresponding xy chromaticity 105 coordinate[12] of the mastering display's white point, as configured for 106 the mastering process. The floating-point white point chromaticity 107 coordinates should be multiplied by EGL_METADATA_SCALING_EXT (50000), 108 before being passed into eglSurfaceAttrib as integers. 109 110 If attribute is EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- 111 LUMINANCE_EXT, then value indicates the maximum or minimum display 112 luminance of the mastering display, as configured for the mastering 113 process. The unit of value is 1 nit (candela per square meter). The 114 floating-point luminance values should be multiplied by 115 EGL_METADATA_SCALING_EXT, a constant scaling factor of 50000, before 116 being passed into eglSurfaceAttrib as integers. 117 118 By defining the mastering display's color volume through color 119 primaries, white point, and luminance range, applications give EGL 120 and the underlying display pipeline hints as to how to reproduce colors 121 more closely to the original content when created on the mastering 122 display. Exactly how the color volume information is used to assist the 123 color reproduction process is implementation dependant. 124 125 The initial values of EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_- 126 SMPTE2086_DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, 127 EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_- 128 EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, EGL_SMPTE2086_WHITE_POINT_X_- 129 EXT, EGL_SMPTE2086_WHITE_POINT_Y_EXT, EGL_SMPTE2086_MAX_LUMINANCE_EXT 130 and EGL_SMPTE2086_MIN_LUMINANCE_EXT are EGL_DONT_CARE, which causes the 131 hints to be ignored. If value is not in the implementation's supported 132 range for attribute, a EGL_BAD_PARAMETER error is generated, and some or 133 all of the metadata fields are ignored. 134 135 Add the following footnote at the end of page 43, and increment all the 136 subsequent footnote numbers in Chapter 3, 137 138 [12] Chromaticity coordinates x and y are as specified in CIE 139 15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are 140 limited to between 0 and 1 for real colors for the mastering display. 141 142 Change the original footnote 12 at the end of section "3.5.6 Surface 143 Attributes" on page 45 to, 144 145 [13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000) 146 are used where EGL needs to take or return floating-point attribute 147 values, which would normally be smaller than 1, as integers while still 148 retaining sufficient precision to be meaningful. 149 150 Addition to Table 3.5 "Queryable surface attributes and types", 151 152 Attribute Type 153 ------------------------------------------------ 154 EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT integer 155 EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT integer 156 EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT integer 157 EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT integer 158 EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT integer 159 EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT integer 160 EGL_SMPTE2086_WHITE_POINT_X_EXT integer 161 EGL_SMPTE2086_WHITE_POINT_Y_EXT integer 162 EGL_SMPTE2086_MAX_LUMINANCE_EXT integer 163 EGL_SMPTE2086_MIN_LUMINANCE_EXT integer 164 165 Description 166 ------------------------------------------------------------------------------------------ 167 x chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT 168 y chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT 169 x chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT 170 y chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT 171 x chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT 172 y chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT 173 x chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT 174 y chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT 175 Maximum luminance in nit multiplied by EGL_METADATA_SCALING_EXT 176 Minimum luminance in nit multiplied by EGL_METADATA_SCALING_EXT 177 178 Add the following paragraph at the end of section "3.5.6 Surface Attributes" 179 on page 45, 180 181 Querying EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_DISPLAY_- 182 PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_SMPTE2086_- 183 DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT or EGL_- 184 SMPTE2086_DISPLAY_PRIMARY_BY_EXT returns respectively the xy 185 chromaticity coordinate of the mastering display's red, green or blue 186 color primary, multiplied by the constant value EGL_METADATA_SCALING_EXT 187 (50000). The display primary coordinates can be set via eglSurfaceAttrib 188 as described above. 189 190 Querying EGL_SMPTE2086_WHITE_POINT_X_EXT, or EGL_SMPTE2086_WHITE_POINT_- 191 Y_EXT returns respectively the xy chromaticity coordinate of the 192 mastering display's white point, multiplied by the constant value EGL_- 193 METADATA_SCALING (50000). The white point coordinates can be set via 194 eglSurfaceAttrib as described above. 195 196 Querying EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_- 197 LUMINANCE_EXT returns respectively the maximum and minimum display 198 luminance of the mastering display. The values returned are in units of 199 1 nit (candela per square meter), multiplied by the constant value EGL_- 200 METADATA_SCALING (50000). The value of EGL_SMPTE2086_MAX_LUMINANCE_EXT 201 and EGL_SMPTE2086_MIN_LUMINANCE_EXT can be set via eglSurfaceAttrib as 202 described above. 203 204Errors 205 206 Described in the body text above. 207 208Issues 209 210 1. Should this extension define a valid data range for each metadata field? 211 212 RESOLVED: No. It is not in the scope of this extension to define how the 213 metadata hints should be used in the display pipeline and, as a result, 214 what the valid data ranges are for the metadata fields. It is 215 implementation dependant, but related standards, such as SMPTE ST 2086, 216 can be used as reference. As described in the body, implemetations may 217 generate a EGL_BAD_PARAMTER error to notify applications that the input 218 metadata values are invalid or not supported. 219 220Revision History 221 222 Version 1, 2016/04/22 223 - Initial draft 224 225 Version 2, 2016/05/25 226 - Rename to EXT and introduce a new scaling factor 227 228 Version 3, 2016/10/19 229 - Add an error and revise issue 1 230 231 Version 4, 2016/11/22 232 - Change status to complete 233 234 Version 5, 2016/11/29 235 - Add token assigments 236 237 Version 6, 2017/02/28 238 - Add 'EXT' suffix to 'EGL_METADATA_SCALING' 239 240 Version 7, 2017/10/13 241 - Rename EGL_INVALID_VALUE (which doesn't exist) to EGL_FALSE 242 243 Version 8, 2017/10/16 244 - Fix v7 change to use EGL_BAD_PARAMETER as the error code 245 generated vs. EGL_FALSE which is the expected return value of 246 the function. 247 248