1Name 2 3 NV_stream_consumer_gltexture_yuv 4 5Name Strings 6 7 EGL_NV_stream_consumer_gltexture_yuv 8 9Contributors 10 11 James Jones 12 Daniel Kartch 13 Nikhil Mahale 14 Daniel Koch 15 Jeff Gilbert 16 17Contacts 18 19 James Jones, NVIDIA (jajones 'at' nvidia 'dot' com) 20 21Status 22 23 Complete 24 25Version 26 27 Version 4 - November 14, 2017 28 29Number 30 31 EGL Extension #94 32 33Extension Type 34 35 EGL display extension 36 37Dependencies 38 39 Requires EGL_KHR_stream_consumer_gltexture 40 References EGL_EXT_yuv_surface 41 42Interactions with EGL_EXT_yuv_surface 43 44 This extension makes use of several tokens defined in the 45 EGL_EXT_yuv_surface extension spec. However support for this 46 EGLStream extension does not require the EGLSurface extension, or 47 vice versa. Only the tokens are shared. 48 49Overview 50 51 The EGL_KHR_stream_consumer_gltexture extension allows EGLStream 52 frames to be latched to a GL texture for use in rendering. These 53 frames are assumed to be stored in RGB format and accessed as such 54 by shader programs. If the producer uses a different color space, 55 the stream implementation must perform an implicit conversion. 56 57 In cases where the producer operates in a native YUV color space, it 58 may be desirable for shaders to directly access the YUV components, 59 without conversion. This extension adds a new variant of the 60 function to bind GL textures as stream consumers which allows 61 attributes to specify the color space. 62 63New Types 64 65 None 66 67New Functions 68 69 EGLBoolean eglStreamConsumerGLTextureExternalAttribsNV( 70 EGLDisplay dpy, 71 EGLStreamKHR stream, 72 const EGLAttrib *attrib_list) 73 74New Tokens 75 76 Accepted as attribute name in <attrib_list> by 77 eglStreamConsumerGLTextureExternalAttribsNV: 78 79 EGL_YUV_PLANE0_TEXTURE_UNIT_NV 0x332C 80 EGL_YUV_PLANE1_TEXTURE_UNIT_NV 0x332D 81 EGL_YUV_PLANE2_TEXTURE_UNIT_NV 0x332E 82 83Reused Tokens From EGL_EXT_yuv_surface 84 85 Accepted as attribute name in <attrib_list> by 86 eglStreamConsumerGLTextureExternalAttribsNV: 87 88 EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311 89 90 Accepted as value for EGL_COLOR_BUFFER_TYPE attribute in 91 <attrib_list> by eglStreamConsumerGLTextureExternalAttribsNV: 92 93 EGL_YUV_BUFFER_EXT 0x3300 94 95Replace entire description of eglStreamConsumerGLTextureExternalKHR in 96section "3.10.2.1 GL Texture External consumer" of 97EGL_KHR_stream_consumer_gltexture extension. 98 99 Call 100 101 EGLBoolean eglStreamConsumerGLTextureExternalAttribsNV( 102 EGLDisplay dpy, 103 EGLStreamKHR stream, 104 const EGLAttrib *attrib_list) 105 106 to connect one or more texture objects in the OpenGL or OpenGL ES 107 context current to the calling thread as the consumer(s) of 108 <stream>. The identity and format of the texture objects used are 109 determined by <attrib_list> and the current context state. 110 111 <attrib_list> must either be NULL or point to an array of name/value 112 pairs terminated by EGL_NONE. Valid attribute names are 113 EGL_COLOR_BUFFER_TYPE, EGL_YUV_NUMBER_OF_PLANES_EXT, and 114 EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV. 115 116 If the value of EGL_COLOR_BUFFER_TYPE is EGL_RGB_BUFFER (the 117 default), then the stream will be connected to a single texture 118 whose contents are available to shaders as RGB values. If the value 119 of EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT the stream will be 120 connected to some number of planar textures, determined by the value 121 of EGL_YUV_NUMBER_OF_PLANES_EXT, whose contents are available to 122 shaders as YUV values. The mapping between YUV values and texture 123 contents is described in table 3.10.2.1. 124 125 If EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT, the default value of 126 EGL_YUV_NUMBER_OF_PLANES_EXT is 2. Otherwise it is 0. 127 128 PLANE0 PLANE1 PLANE2 129 # Planes Values Fields Values Fields Values Fields 130 -------------------------------------------------------------- 131 1 YUV XYZ unused unused 132 2 Y X UV XY unused 133 3 Y X U X V X 134 135 Table 3.10.2.1 YUV Planar Texture Mappings 136 137 If EGL_COLOR_BUFFER_TYPE is EGL_RGB_BUFFER, the stream is connected 138 to the texture object currently bound to the active texture unit's 139 GL_TEXTURE_EXTERNAL_OES texture target in the current context. 140 141 If EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT, attribute values 142 must be specified for EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV for all <n> 143 less than the number of planes. The value of each attribute must 144 either be a valid texture unit index or EGL_NONE. No two of these 145 attributes may specify the same valid texture unit index or 146 reference separate texture units bound to the same texture object. 147 Plane <n> of the stream contents will be connected to the texture 148 object currently bound to the indexed texture unit's 149 GL_TEXTURE_EXTERNAL_OES texture target in the current context, or 150 will be left unused if the index is EGL_NONE. 151 152 Once connected, the stream will remain associated with the initial 153 texture object(s) even if the texture units are bound to new 154 textures. 155 156 (Note: Before this can succeed a GL_TEXTURE_EXTERNAL_OES texture 157 must be bound to the appropriate texture units of the GL context 158 current to the calling thread. To create a GL_TEXTURE_EXTERNAL_OES 159 texture and bind it to the current context, call glBindTexture() 160 with <target> set to GL_TEXTURE_EXTERNAL_OES and <texture> set to 161 the name of the GL_TEXTURE_EXTERNAL_OES (which may or may not have 162 previously been created). This is described in the 163 GL_NV_EGL_stream_consumer_external extension.) 164 165 On failure EGL_FALSE is returned and an error is generated. 166 167 - EGL_BAD_DISPLAY is generated if <dpy> is not a valid, 168 EGLDisplay. 169 170 - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid 171 EGLStreamKHR created for <dpy>. 172 173 - EGL_BAD_STATE_KHR is generated if <stream> is not in state 174 EGL_STREAM_STATE_CREATED_KHR. 175 176 - EGL_BAD_ATTRIBUTE is generated if any attribute name in 177 <attrib_list> is not a valid attribute. 178 179 - EGL_BAD_PARAMETER is generated if the value of 180 EGL_COLOR_BUFFER_TYPE is not EGL_RGB_BUFFER or 181 EGL_YUV_BUFFER_EXT. 182 183 - EGL_BAD_MATCH is generated if EGL_COLOR_BUFFER_TYPE is 184 EGL_RGB_BUFFER and EGL_YUV_NUMBER_OF_PLANES_EXT is not 0, or 185 if EGL_COLOR_BUFFER_TYPE is EGL_YUV_BUFFER_EXT and 186 EGL_YUV_NUMBER_OF_PLANES_EXT is not 1, 2, or 3. 187 188 - EGL_BAD_MATCH is generated if any 189 EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV is not specified for any <n> 190 less than EGL_YUV_NUMBER_OF_PLANES_EXT, or if it is specified 191 for any <n> greater than or equal to 192 EGL_YUV_NUMBER_OF_PLANES_EXT. 193 194 - EGL_BAD_ACCESS is generated if any 195 EGL_YUV_PLANE<n>_TEXTURE_UNIT_NV is set to anything other than 196 a valid texture unit index or EGL_NONE. 197 198 - EGL_BAD_ACCESS is generated if there is no GL context 199 current to the calling thread. 200 201 - EGL_BAD_ACCESS is generated unless nonzero texture object 202 names are bound the GL_TEXTURE_EXTERNAL_OES texture target 203 of each of the appropriate texture units of the GL context 204 current to the calling thread. 205 206 - EGL_BAD_ACCESS is generated if more than one planar surface 207 would be bound to the same texture object. 208 209 - EGL_BAD_ACCESS is generated if the implementation cannot 210 support the requested planar arrangement. 211 212 On success the texture(s) are connected to the <stream>, <stream> 213 is placed in the EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE 214 is returned. 215 216 When a producer is later connected, if it cannot support the planar 217 arrangement of the GL texture connection, it will fail with an 218 EGL_BAD_ACCESS error. 219 220 If any texture is later deleted, connected to a different 221 EGLStream, or connected to an EGLImage, then <stream> will be 222 placed into the EGL_STREAM_STATE_DISCONNECTED_KHR state. 223 224 If the <stream> is later destroyed then the textures will be 225 "incomplete" until they are connected to a new EGLStream, connected 226 to a new EGLImage, or deleted. 227 228 The function 229 230 EGLBoolean eglStreamConsumerGLTextureExternalKHR( 231 EGLDisplay dpy, 232 EGLStreamKHR stream) 233 234 is equivalent to eglStreamConsumerGLTextureExternalAttribsNV with 235 <attrib_list> list set to NULL. 236 237In the remainder of section "3.10.2.1 GL Texture External consumer", 238replace all singular references to "texture" with "textures" and make 239appropriate grammatical modifications. 240 241Issues 242 243 1. This competes with GL_EXT_yuv_target as a means for specifying 244 how YUV values can be directly accessed by a texture shader 245 without conversion to RGB. However, that extension also requires 246 a means to render to YUV surfaces in addition to using them as 247 textures. Should we go with the approach used here or create a 248 GL extension which defines a subset GL_EXT_yuv_target? 249 250 RESOLVED: The extension as is serves immediate needs. Conflicts 251 and overlap with other extensions will be addressed if and when 252 there is a need to promote to EXT. 253 254 2. This also contradicts how previous extensions for EXTERNAL GL 255 textures bind multiplanar surfaces, using separate texture 256 objects rather than a single virtual texture object which 257 requires multiple texture units. This allows the application 258 greater control of the planar arrangement, and the ability to 259 leave planes unbound, which may reduce overhead for the 260 producer. But it makes applications less portabile if the 261 desired arrangement isn't supported. 262 263 RESOLVED: The extension as is serves immediate needs. Conflicts 264 and overlap with other extensions will be addressed if and when 265 there is a need to promote to EXT. 266 267Revision History 268 269 #4 (November 14, 2017) Mozilla Corporation 270 - Const-qualify attrib_list. 271 272 #3 (August 19, 2015) NVIDIA Corporation 273 - Added enum values. 274 - Cleaned up and added contact info for publication. 275 276 #2 (May 6, 2015) NVIDIA Corporation 277 - Consolidated error codes to make GL interaction simpler. 278 279 #1 (April 15, 2015) NVIDIA Corporation 280 - Initial draft 281