1Name 2 3 EXT_yuv_surface 4 5Name Strings 6 7 EGL_EXT_yuv_surface 8 9Contributors 10 11 Matt Trusten 12 Jeff Vigil 13 Arshad Bebal 14 Mohan Maiya 15 Amit Bansal 16 Tom Longo 17 Eric Engestrom 18 19Contacts 20 21 Jeff Vigil, Qualcomm (jvigil 'at' qualcomm.com) 22 23Notice 24 25 Copyright (c) 2014 Qualcomm Technologies, Inc. All Rights Reserved. 26 Qualcomm Technologies Proprietary and Confidential 27 28Status 29 30 Complete 31 32Version 33 34 Version 9, May 4th, 2017 35 36Number 37 38 EGL Extension #86 39 40Dependencies 41 42 EGL 1.4 is required. 43 44 This extension is written against the wording of the EGL 1.4 45 Specification. 46 47Overview 48 49 This extension defines a set of new EGL configuration attributes and values 50 which allows EGL to create and use YUV surfaces. 51 52 YUV formats can be described using a few simple parameters, and every format 53 can be given with these six parameters. These parameters include the color 54 order, the number of planes, subsample, plane depth, color conversion and 55 depth range. 56 57 This extension describes how EGL will handle YUV surfaces, but requires that 58 the client API describe how to fill such a surface. An example of such an 59 extension would be GL_EXT_yuv_target. 60 61New Types 62 63 None 64 65New Procedures and Functions 66 67 None 68 69New Tokens 70 71 A new set of EGLConfig attributes are available: 72 EGL_YUV_ORDER_EXT 0x3301 73 EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311 74 EGL_YUV_SUBSAMPLE_EXT 0x3312 75 EGL_YUV_DEPTH_RANGE_EXT 0x3317 76 EGL_YUV_CSC_STANDARD_EXT 0x330A 77 EGL_YUV_PLANE_BPP_EXT 0x331A 78 79 Accepted as a new value for the EGL_COLOR_BUFFER_TYPE attribute: 80 EGL_YUV_BUFFER_EXT 0x3300 81 82 Accepted values for the EGL_YUV_ORDER_EXT attribute: 83 EGL_YUV_ORDER_YUV_EXT 0x3302 84 EGL_YUV_ORDER_YVU_EXT 0x3303 85 EGL_YUV_ORDER_YUYV_EXT 0x3304 86 EGL_YUV_ORDER_UYVY_EXT 0x3305 87 EGL_YUV_ORDER_YVYU_EXT 0x3306 88 EGL_YUV_ORDER_VYUY_EXT 0x3307 89 EGL_YUV_ORDER_AYUV_EXT 0x3308 90 91 Accepted values for the EGL_YUV_SUBSAMPLE_EXT attribute: 92 EGL_YUV_SUBSAMPLE_4_2_0_EXT 0x3313 93 EGL_YUV_SUBSAMPLE_4_2_2_EXT 0x3314 94 EGL_YUV_SUBSAMPLE_4_4_4_EXT 0x3315 95 96 Accepted values for the EGL_YUV_DEPTH_RANGE_EXT attribute: 97 EGL_YUV_DEPTH_RANGE_LIMITED_EXT 0x3318 98 EGL_YUV_DEPTH_RANGE_FULL_EXT 0x3319 99 100 Accepted values for the EGL_YUV_CSC_STANDARD_EXT attribute: 101 EGL_YUV_CSC_STANDARD_601_EXT 0x330B 102 EGL_YUV_CSC_STANDARD_709_EXT 0x330C 103 EGL_YUV_CSC_STANDARD_2020_EXT 0x330D 104 105 Accepted values for the EGL_YUV_PLANE_BPP_EXT attribute: 106 EGL_YUV_PLANE_BPP_0_EXT 0x331B 107 EGL_YUV_PLANE_BPP_8_EXT 0x331C 108 EGL_YUV_PLANE_BPP_10_EXT 0x331D 109 110Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) 111 112Change the options of paragraph 6 from section 2.2: Rendering Contexts and 113Drawing Surfaces 114 115 A context can be used with any EGLSurface that it is compatible with 116 (subject to the restrictions discussed in the section on address space). A 117 surface and context are compatible if 118 * They support the same type of color buffer (RGB or luminance) 119 120To the following: 121 122 A context can be used with any EGLSurface that it is compatible with 123 (subject to the restrictions discussed in the section on address space). A 124 surface and context are compatible if 125 * They support the same type of color buffer (RGB, YUV, or luminance) 126 127Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) 128 129Change the section marked from Buffer Descriptions and Attributes in Section 3.4 130to: 131 132 The Color Buffer 133 134 The color buffer contains pixel color values, and is shared by all 135 client APIs rendering to a surface. 136 EGL_COLOR_BUFFER_TYPE indicates the color buffer type, and must be 137 either EGL_RGB_BUFFER for an RGB color buffer, EGL_LUMINANCE_BUFFER for a 138 luminance color buffer, or EGL_YUV_BUFFER_EXT for a YUV color buffer. For 139 an RGB buffer, EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE must be non-zero, 140 and EGL_LUMINANCE_SIZE must be zero. For a luminance buffer, EGL_RED_SIZE, 141 EGL_GREEN_SIZE, EGL_BLUE_SIZE must be zero, and EGL_LUMINANCE_SIZE must be 142 non-zero. For both RGB and luminance color buffers, EGL_ALPHA_SIZE may be 143 zero or non-zero (the latter indicates the existence of a destination alpha 144 buffer). For a YUV buffer, all of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_- 145 SIZE, EGL_LUMINANCE_SIZE, and EGL_ALPHA_SIZE must be zero. Instead, the 146 depth in bits per pixel for YUV is described using EGL_YUV_PLANE_BPP_EXT, 147 which describes the size of a single pixel in the Y plane, and the other 148 plane depths are derived from this. 149 EGL_YUV_ORDER_EXT is used to describe the plane order. 150 EGL_YUV_NUMBER_OF_PLANES_EXT describes the number of planes that will 151 be used for this surface. The allowed values for EGL_YUV_NUMBER_OF_PLANES_- 152 EXT must be greater than zero and not more than three. 153 EGL_YUV_SUBSAMPLE_EXT allows the user to decide how the surface will be 154 subsampled. 155 156 Valid combinations are: 157 158 EGL_YUV_SUBSAMPLE_EXT EGL_YUV_NUMBER_OF_PLANES_EXT EGL_YUV_ORDER_EXT EGL_YUV_PLANE_BPP_EXT 159 ------------------------- ----------------------------- ------------------ ------------------------ 160 EGL_YUV_SUBSAMPLE_4_2_0_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or 161 EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT 162 163 EGL_YUV_SUBSAMPLE_4_2_2_EXT 1 EGL_YUV_ORDER_YUYV_EXT or EGL_YUV_PLANE_BPP_8_EXT or 164 EGL_YUV_ORDER_YVYU_EXT or EGL_YUV_PLANE_BPP_10_EXT 165 EGL_YUV_ORDER_UYVY_EXT or 166 EGL_YUV_ORDER_VYUY_EXT 167 168 EGL_YUV_SUBSAMPLE_4_2_2_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or 169 EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT 170 171 EGL_YUV_SUBSAMPLE_4_4_4_EXT 1 EGL_YUV_ORDER_AYUV_EXT EGL_YUV_PLANE_BPP_8_EXT or 172 EGL_YUV_PLANE_BPP_10_EXT 173 174 Usage examples: 175 176 Format Combination 177 ------------------ -------------------------------------------------------------- 178 NV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT 179 - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 180 - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT 181 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT 182 183 NV21 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT 184 - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 185 - 2 Planes : Y + VU EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT 186 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT 187 188 YV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT 189 - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 3 190 - 3 Planes : Y + V + U EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT 191 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT 192 193 YUY2 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT 194 - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 195 - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT 196 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT 197 198 AYUV EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_4_4_EXT 199 - YUV444 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 200 - 1 Plane : A + Y + U + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_AYUV_EXT 201 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT 202 203 YUV420 Semi-Planar 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT 204 - YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2 205 - 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT 206 - 10 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT 207 208 YUV422 Interleaved 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT 209 - YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1 210 - 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT 211 - 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT 212 213 EGL_YUV_PLANE_BPP_EXT describes the bit depth for the different 214 planes of a YUV surface. The available options are EGL_YUV_PLANE_BPP_0_- 215 EXT, EGL_YUV_PLANE_BPP_8_EXT and EGL_YUV_PLANE_BPP_10_EXT. If EGL_YUV_- 216 PLANE_BPP_0_EXT is specified, no color buffer will be created for the 217 surface. 218 EGL_YUV_DEPTH_RANGE_EXT describes the range of the pixel value and is 219 dependent on the EGL_YUV_PLANE_BPP_EXT setting: 220 221 EGL_YUV_PLANE_BPP_EXT EGL_YUV_DEPTH_RANGE_LIMITED_EXT EGL_YUV_DEPTH_RANGE_FULL_EXT 222 (Inclusive) (Inclusive) 223 ------------------------- -------------------------------- ----------------------------- 224 EGL_YUV_PLANE_BPP_8_EXT or Y: 16 to 235, UV: 16 to 240 Y: 0 to 255, UV: 0 to 255 225 EGL_YUV_PLANE_BPP_10_EXT Y: 64 to 940, UV: 64 to 960 Y: 0 to 1023, UV: 0 to 1023 226 227 If OpenGL or OpenGL ES rendering is supported for a luminance color 228 buffer (as described by the value of the EGL_RENDERABLE_TYPE attribute, 229 described below), it is treated as RGB rendering with the value of 230 GL_RED_BITS equal to EGL_LUMINANCE_SIZE and the values of GL_GREEN_BITS and 231 GL_BLUE_BITS equal to zero. The red component of fragments is written to the 232 luminance channel of the color buffer, the green and blue components are 233 discarded, and the alpha component is written to the alpha channel of the 234 color buffer (if present). 235 When rendering to the YUV surface, if EGL_YUV_ORDER_EXT is not EGL_- 236 YUV_ORDER_AYUV_EXT, the alpha channel will always be fully opaque. 237 Otherwise it is defined by the value provided to the alpha sample. 238 EGL_BUFFER_SIZE gives the total of the color component bits of the color 239 buffer for EGL_RGB_BUFFER or for EGL_LUMINANCE_BUFFER. For an RGB color 240 buffer, the total is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, 241 and EGL_ALPHA_SIZE. For a luminance color buffer, the total is the sum of 242 EGL_LUMINANCE_SIZE and EGL_ALPHA_SIZE. When EGL_COLOR_BUFFER_TYPE is of type 243 EGL_YUV_BUFFER_EXT, this will reflect the enumeration provided 244 as an integer) for EGL_YUV_PLANE_BPP_EXT, giving a value of 0, 8 or 10. 245 246 Other EGLConfig Attribute Descriptions 247 248 EGL_YUV_CSC_STANDARD_EXT can be set to either EGL_YUV_CSC_STANDARD_- 249 601_EXT, EGL_YUV_CSC_STANDARD_709_EXT, or EGL_YUV_CSC_2020_EXT. If the 250 standard chosen is EGL_YUV_CSC_STANDARD_709_EXT, then the color conversion 251 follows the ITU-R BT.709 standard. If EGL_YUV_CSC_STANDARD_EXT is set to 252 EGL_YUV_CSC_2020_EXT, then the color conversion will be processed based on 253 ITU-R BT.2020. 254 255 256Change option 2 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: 257 258 2. Special: by EGL_COLOR_BUFFER_TYPE where the precendence is EGL_RGB_- 259 BUFFER, EGL_LUMINANCE_BUFFER, EGL_YUV_BUFFER_EXT. 260 261Change option 3 in the section marked as 3.4.1.2 Sorting of EGLConfigs to: 262 263 3. Special: by larger total number of color bits (for an RGB color buffer, 264 this is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and 265 EGL_ALPHA_SIZE; for a luminance color buffer, the sum of EGL_LUMINANCE_SIZE 266 and EGL_ALPHA_SIZE; for YUV color buffers, this returns the integer value 267 with respect to the enumeration provided for EGL_YUV_PLANE_BPP_EXT) If the 268 requrested number of bits in attrib_list for a particular color component 269 is 0 or EGL_DONT_CARE, then the number of bits for the component is not 270 considered. Due to this, YUV color buffers are always last based on this 271 rule. 272 273The following options should be added between options 9 and 10 in section 2743.4.1.2 (EGL_ALPHA_MASK_SIZE and EGL_NATIVE_VISUAL_TYPE): 275 276 10. Special: EGL_YUV_ORDER_EXT will be sorted in the following order: 277 EGL_NONE, EGL_YUV_ORDER_YUV_EXT, EGL_YUV_ORDER_YVU_EXT, EGL_YUV_ORDER_- 278 YUYV_EXT, EGL_YUV_ORDER_YVYU_EXT, EGL_YUV_ORDER_UYVY_EXT, EGL_YUV_ORDER_- 279 VYUY_EXT, and EGL_YUV_ORDER_AYUV_EXT. 280 281Change option 10 in section 3.4.1.2 (EGL_NATIVE_VISUAL_TYPE) to: 282 283 11. Special: by EGL_NATIVE_VISUAL_TYPE (the actual sort order is 284 implementation-defined, depending on the meaning of native visual types). 285 286New State 287 288 Add to table 3.1 (EGLConfig Attributes): 289 290 Attribute Type Notes 291 ----------------------------- ---- -------------------------------------------- 292 EGL_YUV_ORDER_EXT enum The order in which the samples will be found 293 inside the surface 294 EGL_YUV_NUMBER_OF_PLANES_EXT integer Number of planes for the surface, in the range of [1,3] 295 EGL_YUV_SUBSAMPLE_EXT enum Describes the sampling rate of the different planes. 296 EGL_YUV_DEPTH_RANGE_EXT enum Luma plane range. limited is [16,240] and 297 full range is [0,255] 298 EGL_YUV_CSC_STANDARD_EXT enum The standard used for color conversion. 299 EGL_YUV_PLANE_BPP_EXT enum How many bits are used for each plane of 300 the YUV surface 301 302 Add to table 3.4 (Default values and match criteria for EGLConfig 303 attributes): 304 305 Attribute Default Selection Sort Sort 306 Criteria Order Priority 307 ------------------------- -------------------------------- --------- ------- -------- 308 EGL_YUV_ORDER_EXT EGL_DONT_CARE Exact Special 10 309 EGL_YUV_NUMBER_OF_PLANES_EXT 0 At least None 310 EGL_YUV_SUBSAMPLE_EXT EGL_DONT_CARE Exact None 311 EGL_YUV_DEPTH_RANGE_EXT EGL_DONT_CARE Exact None 312 EGL_YUV_CSC_STANDARD_EXT EGL_DONT_CARE Exact None 313 EGL_YUV_PLANE_BPP_EXT EGL_DONT_CARE Exact None 314 315Issues 316 1. How will a EGL surface created with a YUV config properly detect that 317 valid values were used when filling pixel data? 318 319 This problem occurs in situations when a specification which defines 320 rendering to the YUV surface cannot guarantee values that conform to the 321 configuration attributes. One possible situation for this is when a 322 the GL client is using GL_EXT_yuv_target and the EGL YUV surface is the 323 draw buffer. The shader can transform the values inside the shader, and 324 there is no guarantee that the values will fall into the EGL_YUV_DEPTH_- 325 RANGE_EXT value chosen. Other client specifications could have similar 326 issues and it may not be performant for some hardware to detect this 327 discrepancy. This includes interactions with extensions such as EGL_- 328 lock_surface, or any others that provide a mechanism to change the 329 contents of the YUV surface. 330 331 One of the problems that can occur in situations like this will be 332 compound mathematical error should operations need to take place on the 333 buffer data. 334 335 Proposal: Due to the performance problems or inability in some hardware 336 to deal with this issue, the pixel contents will be undefined and any 337 further operations to the pixel contents will also be undefined. 338 Therefore it is up to the application to guarantee the correct values 339 are stored within the surface. The EGL implementation need not attempt 340 any form of verification on the pixel data of the YUV surface, nor does 341 it have to guarantee the pixel data, even with communicating the surface 342 to other modules through a post or any other operation EGL performs. 343 344 2. Should an EGL_COLOR_BUFFER_TYPE = EGL_DONT_CARE request enumerate all 345 YUV configs? 346 347 Resolved: Revision #9 changes the default values and selection criteria 348 to allow for full enumeration of all YUV configs. The default value of 349 EGL_COLOR_BUFFER_TYPE remains EGL_RGB_BUFFER, so this change only 350 affects explicit EGL_DONT_CARE requests. 351 352Example Configuration for NV12: 353 354 const EGLint config_attribs[] = 355 { 356 EGL_SURFACE_TYPE, EGL_WINDOW_BIT, 357 EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, 358 EGL_COLOR_BUFFER_TYPE, EGL_YUV_BUFFER_EXT, 359 EGL_YUV_ORDER_EXT, EGL_ORDER_YUV_EXT, 360 EGL_YUV_NUMBER_OF_PLANES_EXT, 2, 361 EGL_YUV_SUBSAMPLE_EXT, EGL_YUV_SUBSAMPLE_4_2_0_EXT, 362 EGL_YUV_DEPTH_RANGE_EXT, EGL_YUV_DEPTH_RANGE_LIMITED_EXT, 363 EGL_YUV_CSC_STANDARD_EXT, EGL_YUV_CSC_STANDARD_601_EXT, 364 EGL_YUV_PLANE_BPP_EXT, EGL_YUV_PLANE_BPP_8_EXT, 365 EGL_NONE 366 }; 367 368Revision History 369#1 March 12th, 2014 Initial Draft. 370 371#2 March 25th, 2014 Reformated and added more detail. 372 373#3 March 26th, 2014 Added usage examples. 374 Added memory layout definitions. 375 376#4 March 26th, 2014 Fixed some typos and formatting. 377 378#5 May 21st, 2014 Fixed some inconsistencies. 379 Added EGL_YUV_PLANE_DEPTH_0_QCOM. 380 381#6 May 27th, 2014 Relaxed some requirements. 382 Changed EGL_YUV_PLANE_DEPTH_<0,8,10>_QCOM to 383 EGL_YUV_PLANE_BPP_<0,8,10>_QCOM. 384 Added more detail. 385 386#7 October 7th, 2014 Issue (1) added. 387 Minor updates made (EXT_yuv_target) 388 389#8 October 24th, 2014 Updated for EXT and token values. 390 391#9 April 26th, 2017 Changed attributes default values and selection 392 criteria (see issue #2). 393 Changed status from Draft to Complete. 394