blob: 15b854eb7d5c191bf5e7f26b018a2c0821322985 [file] [log] [blame]
Name
EXT_yuv_surface
Name Strings
EGL_EXT_yuv_surface
Contributors
Matt Trusten
Jeff Vigil
Arshad Bebal
Mohan Maiya
Amit Bansal
Tom Longo
Eric Engestrom
Contacts
Jeff Vigil, Qualcomm (jvigil 'at' qualcomm.com)
Notice
Copyright (c) 2014 Qualcomm Technologies, Inc. All Rights Reserved.
Qualcomm Technologies Proprietary and Confidential
Status
Complete
Version
Version 9, May 4th, 2017
Number
EGL Extension #86
Dependencies
EGL 1.4 is required.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension defines a set of new EGL configuration attributes and values
which allows EGL to create and use YUV surfaces.
YUV formats can be described using a few simple parameters, and every format
can be given with these six parameters. These parameters include the color
order, the number of planes, subsample, plane depth, color conversion and
depth range.
This extension describes how EGL will handle YUV surfaces, but requires that
the client API describe how to fill such a surface. An example of such an
extension would be GL_EXT_yuv_target.
New Types
None
New Procedures and Functions
None
New Tokens
A new set of EGLConfig attributes are available:
EGL_YUV_ORDER_EXT 0x3301
EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311
EGL_YUV_SUBSAMPLE_EXT 0x3312
EGL_YUV_DEPTH_RANGE_EXT 0x3317
EGL_YUV_CSC_STANDARD_EXT 0x330A
EGL_YUV_PLANE_BPP_EXT 0x331A
Accepted as a new value for the EGL_COLOR_BUFFER_TYPE attribute:
EGL_YUV_BUFFER_EXT 0x3300
Accepted values for the EGL_YUV_ORDER_EXT attribute:
EGL_YUV_ORDER_YUV_EXT 0x3302
EGL_YUV_ORDER_YVU_EXT 0x3303
EGL_YUV_ORDER_YUYV_EXT 0x3304
EGL_YUV_ORDER_UYVY_EXT 0x3305
EGL_YUV_ORDER_YVYU_EXT 0x3306
EGL_YUV_ORDER_VYUY_EXT 0x3307
EGL_YUV_ORDER_AYUV_EXT 0x3308
Accepted values for the EGL_YUV_SUBSAMPLE_EXT attribute:
EGL_YUV_SUBSAMPLE_4_2_0_EXT 0x3313
EGL_YUV_SUBSAMPLE_4_2_2_EXT 0x3314
EGL_YUV_SUBSAMPLE_4_4_4_EXT 0x3315
Accepted values for the EGL_YUV_DEPTH_RANGE_EXT attribute:
EGL_YUV_DEPTH_RANGE_LIMITED_EXT 0x3318
EGL_YUV_DEPTH_RANGE_FULL_EXT 0x3319
Accepted values for the EGL_YUV_CSC_STANDARD_EXT attribute:
EGL_YUV_CSC_STANDARD_601_EXT 0x330B
EGL_YUV_CSC_STANDARD_709_EXT 0x330C
EGL_YUV_CSC_STANDARD_2020_EXT 0x330D
Accepted values for the EGL_YUV_PLANE_BPP_EXT attribute:
EGL_YUV_PLANE_BPP_0_EXT 0x331B
EGL_YUV_PLANE_BPP_8_EXT 0x331C
EGL_YUV_PLANE_BPP_10_EXT 0x331D
Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation)
Change the options of paragraph 6 from section 2.2: Rendering Contexts and
Drawing Surfaces
A context can be used with any EGLSurface that it is compatible with
(subject to the restrictions discussed in the section on address space). A
surface and context are compatible if
* They support the same type of color buffer (RGB or luminance)
To the following:
A context can be used with any EGLSurface that it is compatible with
(subject to the restrictions discussed in the section on address space). A
surface and context are compatible if
* They support the same type of color buffer (RGB, YUV, or luminance)
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Change the section marked from Buffer Descriptions and Attributes in Section 3.4
to:
The Color Buffer
The color buffer contains pixel color values, and is shared by all
client APIs rendering to a surface.
EGL_COLOR_BUFFER_TYPE indicates the color buffer type, and must be
either EGL_RGB_BUFFER for an RGB color buffer, EGL_LUMINANCE_BUFFER for a
luminance color buffer, or EGL_YUV_BUFFER_EXT for a YUV color buffer. For
an RGB buffer, EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE must be non-zero,
and EGL_LUMINANCE_SIZE must be zero. For a luminance buffer, EGL_RED_SIZE,
EGL_GREEN_SIZE, EGL_BLUE_SIZE must be zero, and EGL_LUMINANCE_SIZE must be
non-zero. For both RGB and luminance color buffers, EGL_ALPHA_SIZE may be
zero or non-zero (the latter indicates the existence of a destination alpha
buffer). For a YUV buffer, all of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_-
SIZE, EGL_LUMINANCE_SIZE, and EGL_ALPHA_SIZE must be zero. Instead, the
depth in bits per pixel for YUV is described using EGL_YUV_PLANE_BPP_EXT,
which describes the size of a single pixel in the Y plane, and the other
plane depths are derived from this.
EGL_YUV_ORDER_EXT is used to describe the plane order.
EGL_YUV_NUMBER_OF_PLANES_EXT describes the number of planes that will
be used for this surface. The allowed values for EGL_YUV_NUMBER_OF_PLANES_-
EXT must be greater than zero and not more than three.
EGL_YUV_SUBSAMPLE_EXT allows the user to decide how the surface will be
subsampled.
Valid combinations are:
EGL_YUV_SUBSAMPLE_EXT EGL_YUV_NUMBER_OF_PLANES_EXT EGL_YUV_ORDER_EXT EGL_YUV_PLANE_BPP_EXT
------------------------- ----------------------------- ------------------ ------------------------
EGL_YUV_SUBSAMPLE_4_2_0_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_SUBSAMPLE_4_2_2_EXT 1 EGL_YUV_ORDER_YUYV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVYU_EXT or EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_ORDER_UYVY_EXT or
EGL_YUV_ORDER_VYUY_EXT
EGL_YUV_SUBSAMPLE_4_2_2_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_SUBSAMPLE_4_4_4_EXT 1 EGL_YUV_ORDER_AYUV_EXT EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_PLANE_BPP_10_EXT
Usage examples:
Format Combination
------------------ --------------------------------------------------------------
NV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
NV21 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + VU EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 3
- 3 Planes : Y + V + U EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YUY2 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT
- YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
AYUV EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_4_4_EXT
- YUV444 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : A + Y + U + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_AYUV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YUV420 Semi-Planar 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT
- 10 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT
YUV422 Interleaved 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT
- YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_PLANE_BPP_EXT describes the bit depth for the different
planes of a YUV surface. The available options are EGL_YUV_PLANE_BPP_0_-
EXT, EGL_YUV_PLANE_BPP_8_EXT and EGL_YUV_PLANE_BPP_10_EXT. If EGL_YUV_-
PLANE_BPP_0_EXT is specified, no color buffer will be created for the
surface.
EGL_YUV_DEPTH_RANGE_EXT describes the range of the pixel value and is
dependent on the EGL_YUV_PLANE_BPP_EXT setting:
EGL_YUV_PLANE_BPP_EXT EGL_YUV_DEPTH_RANGE_LIMITED_EXT EGL_YUV_DEPTH_RANGE_FULL_EXT
(Inclusive) (Inclusive)
------------------------- -------------------------------- -----------------------------
EGL_YUV_PLANE_BPP_8_EXT or Y: 16 to 235, UV: 16 to 240 Y: 0 to 255, UV: 0 to 255
EGL_YUV_PLANE_BPP_10_EXT Y: 64 to 940, UV: 64 to 960 Y: 0 to 1023, UV: 0 to 1023
If OpenGL or OpenGL ES rendering is supported for a luminance color
buffer (as described by the value of the EGL_RENDERABLE_TYPE attribute,
described below), it is treated as RGB rendering with the value of
GL_RED_BITS equal to EGL_LUMINANCE_SIZE and the values of GL_GREEN_BITS and
GL_BLUE_BITS equal to zero. The red component of fragments is written to the
luminance channel of the color buffer, the green and blue components are
discarded, and the alpha component is written to the alpha channel of the
color buffer (if present).
When rendering to the YUV surface, if EGL_YUV_ORDER_EXT is not EGL_-
YUV_ORDER_AYUV_EXT, the alpha channel will always be fully opaque.
Otherwise it is defined by the value provided to the alpha sample.
EGL_BUFFER_SIZE gives the total of the color component bits of the color
buffer for EGL_RGB_BUFFER or for EGL_LUMINANCE_BUFFER. For an RGB color
buffer, the total is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE,
and EGL_ALPHA_SIZE. For a luminance color buffer, the total is the sum of
EGL_LUMINANCE_SIZE and EGL_ALPHA_SIZE. When EGL_COLOR_BUFFER_TYPE is of type
EGL_YUV_BUFFER_EXT, this will reflect the enumeration provided
as an integer) for EGL_YUV_PLANE_BPP_EXT, giving a value of 0, 8 or 10.
Other EGLConfig Attribute Descriptions
EGL_YUV_CSC_STANDARD_EXT can be set to either EGL_YUV_CSC_STANDARD_-
601_EXT, EGL_YUV_CSC_STANDARD_709_EXT, or EGL_YUV_CSC_2020_EXT. If the
standard chosen is EGL_YUV_CSC_STANDARD_709_EXT, then the color conversion
follows the ITU-R BT.709 standard. If EGL_YUV_CSC_STANDARD_EXT is set to
EGL_YUV_CSC_2020_EXT, then the color conversion will be processed based on
ITU-R BT.2020.
Change option 2 in the section marked as 3.4.1.2 Sorting of EGLConfigs to:
2. Special: by EGL_COLOR_BUFFER_TYPE where the precendence is EGL_RGB_-
BUFFER, EGL_LUMINANCE_BUFFER, EGL_YUV_BUFFER_EXT.
Change option 3 in the section marked as 3.4.1.2 Sorting of EGLConfigs to:
3. Special: by larger total number of color bits (for an RGB color buffer,
this is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and
EGL_ALPHA_SIZE; for a luminance color buffer, the sum of EGL_LUMINANCE_SIZE
and EGL_ALPHA_SIZE; for YUV color buffers, this returns the integer value
with respect to the enumeration provided for EGL_YUV_PLANE_BPP_EXT) If the
requrested number of bits in attrib_list for a particular color component
is 0 or EGL_DONT_CARE, then the number of bits for the component is not
considered. Due to this, YUV color buffers are always last based on this
rule.
The following options should be added between options 9 and 10 in section
3.4.1.2 (EGL_ALPHA_MASK_SIZE and EGL_NATIVE_VISUAL_TYPE):
10. Special: EGL_YUV_ORDER_EXT will be sorted in the following order:
EGL_NONE, EGL_YUV_ORDER_YUV_EXT, EGL_YUV_ORDER_YVU_EXT, EGL_YUV_ORDER_-
YUYV_EXT, EGL_YUV_ORDER_YVYU_EXT, EGL_YUV_ORDER_UYVY_EXT, EGL_YUV_ORDER_-
VYUY_EXT, and EGL_YUV_ORDER_AYUV_EXT.
Change option 10 in section 3.4.1.2 (EGL_NATIVE_VISUAL_TYPE) to:
11. Special: by EGL_NATIVE_VISUAL_TYPE (the actual sort order is
implementation-dened, depending on the meaning of native visual types).
New State
Add to table 3.1 (EGLConfig Attributes):
Attribute Type Notes
----------------------------- ---- --------------------------------------------
EGL_YUV_ORDER_EXT enum The order in which the samples will be found
inside the surface
EGL_YUV_NUMBER_OF_PLANES_EXT integer Number of planes for the surface, in the range of [1,3]
EGL_YUV_SUBSAMPLE_EXT enum Describes the sampling rate of the different planes.
EGL_YUV_DEPTH_RANGE_EXT enum Luma plane range. limited is [16,240] and
full range is [0,255]
EGL_YUV_CSC_STANDARD_EXT enum The standard used for color conversion.
EGL_YUV_PLANE_BPP_EXT enum How many bits are used for each plane of
the YUV surface
Add to table 3.4 (Default values and match criteria for EGLConfig
attributes):
Attribute Default Selection Sort Sort
Criteria Order Priority
------------------------- -------------------------------- --------- ------- --------
EGL_YUV_ORDER_EXT EGL_DONT_CARE Exact Special 10
EGL_YUV_NUMBER_OF_PLANES_EXT 0 At least None
EGL_YUV_SUBSAMPLE_EXT EGL_DONT_CARE Exact None
EGL_YUV_DEPTH_RANGE_EXT EGL_DONT_CARE Exact None
EGL_YUV_CSC_STANDARD_EXT EGL_DONT_CARE Exact None
EGL_YUV_PLANE_BPP_EXT EGL_DONT_CARE Exact None
Issues
1. How will a EGL surface created with a YUV config properly detect that
valid values were used when filling pixel data?
This problem occurs in situations when a specification which defines
rendering to the YUV surface cannot guarantee values that conform to the
configuration attributes. One possible situation for this is when a
the GL client is using GL_EXT_yuv_target and the EGL YUV surface is the
draw buffer. The shader can transform the values inside the shader, and
there is no guarantee that the values will fall into the EGL_YUV_DEPTH_-
RANGE_EXT value chosen. Other client specifications could have similar
issues and it may not be performant for some hardware to detect this
discrepancy. This includes interactions with extensions such as EGL_-
lock_surface, or any others that provide a mechanism to change the
contents of the YUV surface.
One of the problems that can occur in situations like this will be
compound mathematical error should operations need to take place on the
buffer data.
Proposal: Due to the performance problems or inability in some hardware
to deal with this issue, the pixel contents will be undefined and any
further operations to the pixel contents will also be undefined.
Therefore it is up to the application to guarantee the correct values
are stored within the surface. The EGL implementation need not attempt
any form of verification on the pixel data of the YUV surface, nor does
it have to guarantee the pixel data, even with communicating the surface
to other modules through a post or any other operation EGL performs.
2. Should an EGL_COLOR_BUFFER_TYPE = EGL_DONT_CARE request enumerate all
YUV configs?
Resolved: Revision #9 changes the default values and selection criteria
to allow for full enumeration of all YUV configs. The default value of
EGL_COLOR_BUFFER_TYPE remains EGL_RGB_BUFFER, so this change only
affects explicit EGL_DONT_CARE requests.
Example Configuration for NV12:
const EGLint config_attribs[] =
{
EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
EGL_COLOR_BUFFER_TYPE, EGL_YUV_BUFFER_EXT,
EGL_YUV_ORDER_EXT, EGL_ORDER_YUV_EXT,
EGL_YUV_NUMBER_OF_PLANES_EXT, 2,
EGL_YUV_SUBSAMPLE_EXT, EGL_YUV_SUBSAMPLE_4_2_0_EXT,
EGL_YUV_DEPTH_RANGE_EXT, EGL_YUV_DEPTH_RANGE_LIMITED_EXT,
EGL_YUV_CSC_STANDARD_EXT, EGL_YUV_CSC_STANDARD_601_EXT,
EGL_YUV_PLANE_BPP_EXT, EGL_YUV_PLANE_BPP_8_EXT,
EGL_NONE
};
Revision History
#1 March 12th, 2014 Initial Draft.
#2 March 25th, 2014 Reformated and added more detail.
#3 March 26th, 2014 Added usage examples.
Added memory layout definitions.
#4 March 26th, 2014 Fixed some typos and formatting.
#5 May 21st, 2014 Fixed some inconsistencies.
Added EGL_YUV_PLANE_DEPTH_0_QCOM.
#6 May 27th, 2014 Relaxed some requirements.
Changed EGL_YUV_PLANE_DEPTH_<0,8,10>_QCOM to
EGL_YUV_PLANE_BPP_<0,8,10>_QCOM.
Added more detail.
#7 October 7th, 2014 Issue (1) added.
Minor updates made (EXT_yuv_target)
#8 October 24th, 2014 Updated for EXT and token values.
#9 April 26th, 2017 Changed attributes default values and selection
criteria (see issue #2).
Changed status from Draft to Complete.