1Name 2 3 OES_EGL_image_external 4 5Name Strings 6 7 GL_OES_EGL_image_external 8 9Contributors 10 11 Acorn Pooley 12 David Garcia 13 Bruce Merry 14 Aske Simon Christensen 15 Mark Callow 16 Tom Olson 17 Jon Leech 18 Maurice Ribble 19 20Contacts 21 22 Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) 23 24Notice 25 26 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 27 http://www.khronos.org/registry/speccopyright.html 28 29Specification Update Policy 30 31 Khronos-approved extension specifications are updated in response to 32 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 33 extensions which have been promoted to a core Specification, fixes will 34 first appear in the latest version of that core Specification, and will 35 eventually be backported to the extension document. This policy is 36 described in more detail at 37 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 38 39Status 40 41 Ratified by Khronos Promoters, 10 December 2010 42 Approved by the OpenGL ES Working Group, 15 September 2010 43 44Version 45 46 April 6, 2018 (version 25) 47 48Number 49 50 OpenGL ES Extension #87 51 52Dependencies 53 54 Requires OpenGL ES 1.1 or OpenGL ES 2.0. 55 56 Requires EGL 1.2 57 58 Requires either the EGL_KHR_image_base or the EGL_KHR_image extension 59 60 This extension is written based on the wording of the OpenGL ES 2.0 61 specification, the OpenGL ES Shading Language version 1.0, and the 62 EGL_KHR_image_base extension. On an OpenGL ES 2.0 implementation, ignore 63 sections which are added only to the OpenGL ES 1.1 specification. 64 65 This extension is also written based on the wording of the OpenGL ES 1.1 66 specification. On an OpenGL ES 1.X implementation, ignore sections which 67 are added only to the OpenGL ES 2.0 or OpenGL ES Shading Language 68 specification. Also ignore all mention of MAX_VERTEX_TEXTURE_IMAGE_UNITS, 69 and MAX_COMBINED_TEXTURE_IMAGE_UNITS. 70 71 This extension borrows concepts and function names from the 72 GL_OES_EGL_image extension. This extension is compatible with, but does 73 not require, the GL_OES_EGL_image extension. 74 75Overview 76 77 This extension provides a mechanism for creating EGLImage texture targets 78 from EGLImages. This extension defines a new texture target, 79 TEXTURE_EXTERNAL_OES. This texture target can only be specified using an 80 EGLImage. There is no support for most of the functions that manipulate 81 other texture targets (e.g. you cannot use gl*Tex*Image*() functions with 82 TEXTURE_EXTERNAL_OES). Also, TEXTURE_EXTERNAL_OES targets never have more 83 than a single LOD level. Because of these restrictions, it is possible to 84 bind EGLImages which have internal formats not otherwise supported by 85 OpenGL ES. For example some implementations may allow EGLImages with 86 planar or interleaved YUV data to be GLES texture target siblings. It is 87 up to the implementation exactly what formats are accepted. 88 89Glossary 90 91 Please see the EGL_OES_image_base specification for a list of terms 92 used by this specification. 93 94New Types 95 96 /* 97 * GLeglImageOES is an opaque handle to an EGLImage 98 * Note: GLeglImageOES is also defined in GL_OES_EGL_image 99 */ 100 typedef void* GLeglImageOES; 101 102 /* (OpenGL ES 2.x only) 103 * New sampler type allowed by the OpenGL ES Shading Language when 104 * #extension GL_OES_EGL_image_external 105 * is used. 106 */ 107 samplerExternalOES 108 109New Procedures and Functions 110 111 /* Note: EGLImageTargetTexture2DOES is also defined in GL_OES_EGL_image */ 112 void EGLImageTargetTexture2DOES(enum target, eglImageOES image) 113 114New Tokens 115 116 Accepted as a target in the <target> parameter of BindTexture and 117 EGLImageTargetTexture2DOES: 118 119 TEXTURE_EXTERNAL_OES 0x8D65 120 121 (OpenGL ES 2.x only) Returned in the <type> parameter of GetActiveUniform: 122 SAMPLER_EXTERNAL_OES 0x8D66 123 124 Accepted as the <pname> parameter of GetBooleanv, GetIntegerv, 125 GetFloatv, and GetFixedv: 126 TEXTURE_BINDING_EXTERNAL_OES 0x8D67 127 128 Accepted as <value> in GetTexParameter*() queries: 129 REQUIRED_TEXTURE_IMAGE_UNITS_OES 0x8D68 130 131 132Additions to Chapter 3 of the OpenGL 1.1 or OpenGL 2.0 Specification 133 134 - For OpenGL ES 2.0 add a new section: "3.7.14 External Textures," which 135 follows section "3.7.13 Texture Objects." For OpenGL ES 1.1 add a new 136 section after section "3.7.11 Texture Objects." 137 138 "3.7.14 External Textures 139 140 External textures cannot be used with TexImage2D, TexSubImage2D, 141 CompressedTexImage2D, CompressedTexSubImage2D, CopyTexImage2D, or 142 CopyTexSubImage2D, and an INVALID_ENUM error will be generated if this 143 is attempted. Their default min filter is LINEAR. It is an 144 INVALID_ENUM error to set the min filter value to anything other than 145 LINEAR or NEAREST. The default s and t wrap modes are CLAMP_TO_EDGE 146 and it is an INVALID_ENUM error to set the wrap mode to any other 147 value. (For OpenGL ES 1.x only: The texture parameter GENERATE_MIPMAP 148 is always FALSE, and setting it to any other value generates an 149 INVALID_ENUM error. (For OpenGL ES 2.x only: Calling GenerateMipmaps 150 with <target> set to TEXTURE_EXTERNAL_OES results in an INVALID_ENUM.) 151 152 The command 153 154 void EGLImageTargetTexture2DOES(enum target, eglImageOES image); 155 156 with <target> set to TEXTURE_EXTERNAL_OES defines the currently bound 157 external texture object to be a target sibling of <image>. The width, 158 height, format, type, internalformat, border, and image data are all 159 determined based on the specified eglImageOES <image>. Any sibling 160 previously associated with this external texture object is deleted. 161 162 A EGLImageTargetTexture2DOES() call with <target> set to 163 TEXTURE_EXTERNAL_OES will not modify the pixel data values in the 164 EGLImage. 165 166 <image> must be the handle of a valid EGLImage resource, cast into the 167 type eglImageOES. 168 169 Assuming no errors are generated in EGLImageTargetTexture2DOES, the 170 newly specified texture object will be an EGLImage target of the 171 specified eglImageOES. 172 173 If the GL is unable to specify a texture object using the supplied 174 eglImageOES <image> (if, for example, <image> refers to a multisampled 175 eglImageOES), the error INVALID_OPERATION is generated. 176 177 If <target> is not TEXTURE_EXTERNAL_OES, the error INVALID_ENUM is 178 generated. (Note: if GL_OES_EGL_image is supported then <target> may 179 also be TEXTURE_2D). 180 181 Sampling an external texture which is not associated with any EGLImage 182 sibling will return a sample value of (0,0,0,1). 183 184 Each TEXTURE_EXTERNAL_OES texture object may require up to 3 texture 185 image units for each texture unit to which it is bound. The number of 186 texture image units required by a bound texture object can be queried 187 using GetTexParameteriv() with <target> set to the texture target in 188 question, <value> set to REQUIRED_TEXTURE_IMAGE_UNITS_OES, and 189 ActiveTexture set to the texture unit to which the texture object is 190 bound. When <target> is set to TEXTURE_EXTERNAL_OES this value will 191 be between 1 and 3 (inclusive). For other valid texture targets this 192 value will always be 1. Note that, when a TEXTURE_EXTERNAL_OES 193 texture object is bound, the number of texture image units required by 194 a single texture unit may be 1, 2, or 3, while for other texture 195 objects each texture unit requires exactly 1 texture image unit. 196 197 (For OpenGL ES 1.x only) DrawArrays and DrawElements will fail and 198 generate an INVALID_OPERATION error if the number of texture image 199 units required is greater than the number available. The number of 200 required texture image units is equal to the sum of the requirements 201 for each enabled texture unit. For each texture unit the requirement 202 is the value returned by GetTexParameteriv() when <value> is set to 203 REQUIRED_TEXTURE_IMAGE_UNITS_OES, <target> is set to the target which 204 is enabled, and ActiveTexture has been set to the texture unit in 205 question. 206 207 (For OpenGL ES 2.x only) DrawArrays and DrawElements will fail and 208 generate an INVALID_OPERATION error if the number of texture image 209 units required is greater than the number available. The number of 210 required texture image units for each stage (fragment or vertex) is 211 equal to the sum of the requirements for each sampler referenced by 212 the stage. A sampler is considered referenced if its location 213 (returned by GetUniformLocation) is not -1. For each referenced 214 sampler the requirement is the value returned by GetTexParameteriv() 215 when <value> is set to REQUIRED_TEXTURE_IMAGE_UNITS_OES, <target> is 216 set to the target corresponding to the sampler type, and ActiveTexture 217 has been set to the texture unit corresponding to the value of the 218 sampler uniform. The condition can be detected by calling Validate. 219 220 (For OpenGL ES 2.x only) A shader that uses external texture samplers 221 may require some number of hidden uniform variables to implement the 222 conversion from YUV to RGB, and this may reduce the amount of space 223 available for uniforms defined by the shader program. This may cause 224 a shader program which was working to stop working when a different 225 external texture is used (i.e. when Uniform1i or BindTexture is 226 called). If there are not enough uniforms available then calls to 227 DrawArrays or DrawElements will fail and generate an INVALID_OPERATION 228 error. This condition can be detected by calling ValidateProgram. 229 230 Sampling an external texture which has been modified since it was 231 bound will return samples which may correspond to image values either 232 before, during, or after the modification. Binding (or re-binding if 233 already bound) an external texture by calling BindTexture after all 234 modifications are complete guarantees that sampling done in future 235 draw calls will return values corresponding to the values in the 236 buffer at or after the time that BindTexture is called. (Note that 237 calling BindTexture after calling commands that modify the EGLImage 238 may not be sufficient to ensure that the modifications are complete; 239 additional synchronization (for example eglWaitAPI, eglWaitNative, 240 glFinish, vgFinish, or eglWaitSyncKHR, etc) may be required following 241 the call initiating modifications, to ensure they have taken effect on 242 the texture, before the call to BindTexture is made.) 243 244 Sampling an external texture will return an RGBA vector in the same 245 colorspace as the source image. If the source image is stored in YUV 246 (or some other basis) then the YUV values will be transformed to RGB 247 values. (But these RGB values will be in the same colorspace as the 248 original image. Colorspace here includes the linear or non-linear 249 encoding of the samples. For example, if the original image is in the 250 sRGB color space then the RGB value returned by the sampler will also 251 be sRGB, and if the original image is stored in ITU-R Rec. 601 YV12 252 then the RGB value returned by the sampler will be an RGB value in the 253 ITU-R Rec. 601 colorspace.) The parameters of the transformation 254 from one basis (e.g. YUV) to RGB (color conversion matrix, sampling 255 offsets, etc) are taken from the EGLImage which is associated with the 256 external texture. The implementation may choose to do this 257 transformation when the external texture is sampled, when the external 258 texture is bound, or any other time so long as the effect is the same. 259 It is undefined whether texture filtering occurs before or after the 260 transformation to RGB. 261 262 If the EGLImage associated with the external texture contains alpha 263 values then the value of the alpha component returned is taken from 264 the image; otherwise the alpha component is 1.0. 265 266Changes to section "2.10.4 Shader Variables" of the OpenGL ES 2.0 267specification (ignore for OpenGL ES 1.x) 268 269 - In the subsection "Uniform Variables" paragraph 13, last sentence, add 270 271 "SAMPLER_EXTERNAL_OES" 272 to the list of types that can be returned. 273 274Changes to section "2.10.5 Shader Execution" of the OpenGL ES 2.0 275specification (ignore for OpenGL ES 1.x) 276 277 - In the subsection "Validation", add to the bullet points in the second 278 paragraph: 279 280 "- the number of texture image units required is greater than 281 the number available (see REQUIRED_TEXTURE_IMAGE_UNITS_OES, 282 MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, 283 and MAX_TEXTURE_IMAGE_UNITS). 284 285 - the number of uniforms required to implement the shader program is 286 greater than the number available." 287 288Changes to section "3.7.5 Texture Parameters" of the OpenGL ES 1.1 specification 289 290 - Add to the end of the section a new paragraph: 291 292 "When <target> is TEXTURE_EXTERNAL_OES only NEAREST and LINEAR are 293 accepted as TEXTURE_MIN_FILTER, only CLAMP_TO_EDGE is accepted as 294 TEXTURE_WRAP_S and TEXTURE_WRAP_T, and only FALSE is accepted as 295 GENERATE_MIPMAP. Attempting to set other values for 296 TEXTURE_MIN_FILTER, TEXTURE_WRAP_S, TEXTURE_WRAP_T, or GENERATE_MIPMAP 297 will result in an INVALID_ENUM error. 298 299Changes to section "3.7.4 Texture Parameters" of the OpenGL ES 2.0 Specification 300 301 - Add to the end of the section a new paragraph: 302 303 "When <target> is TEXTURE_EXTERNAL_OES only NEAREST and LINEAR are 304 accepted as TEXTURE_MIN_FILTER and only CLAMP_TO_EDGE is accepted as 305 TEXTURE_WRAP_S and TEXTURE_WRAP_T. Attempting to set other values for 306 TEXTURE_MIN_FILTER, TEXTURE_WRAP_S, or TEXTURE_WRAP_T will result in 307 an INVALID_ENUM error. 308 309Changes to section "3.7.10 Texture State" of the OpenGL ES 1.1 Specification 310and section "3.7.12 Texture State" of the OpenGL ES 2.0 Specification 311 312 - Add an additional sentence at the end of the section: 313 314 "In the initial state of a TEXTURE_EXTERNAL_OES texture object, 315 the value assigned to TEXTURE_MIN_FILTER and TEXTURE_MAG_FILTER is 316 LINEAR, and the s and t wrap modes are both set to 317 CLAMP_TO_EDGE." 318 319Changes to section "3.7.11 Mipmap Generation" of the OpenGL ES 2.0 Specification 320(ignore for OpenGL ES 1.x) 321 322 - Add two additional paragraphs to the end of the section: 323 324 "When <target> is set to TEXTURE_EXTERNAL_OES, GenerateMipmap 325 always fails and generates an INVALID_ENUM error." 326 327Changes to section "3.7.11 Texture Objects" of the OpenGL ES 1.1 specification 328(ignore for OpenGL ES 2.x) 329 330 - Modify this section as follows: (changed lines marked with *, and added 331 lines are marked with +) 332 333* "In addition to the default textures TEXTURE_2D and 334* TEXTURE_EXTERNAL_OES, named two-dimensional and external texture 335 objects can be created and operated upon. The name space for texture 336 objects is the unsigned integers, with zero reserved by the GL. 337 338 A texture object is created by binding an unused name to 339* TEXTURE_2D or TEXTURE_EXTERNAL_OES. The binding is effected by calling 340 void BindTexture( enum target, uint texture ); 341* with target set to the desired texture target and texture set to the 342 unused name. The resulting texture object is a new state vector, 343 comprising all the state values listed in section 3.7.10, set to the 344+ same initial values. If the new texture object is bound to TEXTURE_2D 345+ or TEXTURE_EXTERNAL_OES it is and remains a two-dimensional or 346+ external texture respectively until it is deleted. 347 348 BindTexture may also be used to bind an existing texture object to 349* TEXTURE_2D or TEXTURE_EXTERNAL_OES. If the bind is successful no 350 change is made to the state of the bound texture object, and any 351 previous binding to target is broken. 352 353 While a texture object is bound, GL operations on the target to 354 which it is bound affect the bound object, and queries of the target 355 to which it is bound return state from the bound object. If texture 356 mapping is enabled, the state of the bound texture object directs the 357 texturing operation. 358 359* In the initial state, TEXTURE_2D and TEXTURE_EXTERNAL_OES have 360* two-dimensional and external texture state vectors respectively 361* associated with them. In order that access to these initial textures 362* not be lost, they are treated as texture objects all of whose names 363* are 0. The initial two-dimensional and external texture are therefore 364* operated upon, queried, and applied as TEXTURE_2D or 365* TEXTURE_EXTERNAL_OES respectively while 0 is bound to the 366* corresponding targets. 367 368 Texture objects are deleted by calling 369 void DeleteTextures( sizei n, uint *textures ); 370 textures contains n names of texture objects to be deleted. After a 371 texture object is deleted, it has no contents, and its name is again 372 unused. If a texture that is currently bound to the target TEXTURE_2D 373* or TEXTURE_EXTERNAL_OES is deleted, it is as though BindTexture had 374 been executed with the same target and texture zero. Unused names in 375 textures are silently ignored, as is the value zero. 376 377 The command 378 void GenTextures( sizei n, uint *textures ); 379 returns n previously unused texture object names in textures. These 380 names are marked as used, for the purposes of GenTextures only, but 381 they acquire texture state only when they are first bound, just as if 382 they were unused. 383 384 The texture object name space, including the initial texture 385 object, is shared among all texture units. A texture object may be 386 bound to more than one texture unit simultaneously. After a texture 387 object is bound, any GL operations on that target object affect any 388 other texture units to which the same texture object is bound. 389 390 Texture binding is affected by the setting of the state 391 ACTIVE_TEXTURE. 392 393 If a texture object is deleted, it is as if all texture units which 394 are bound to that texture object are rebound to texture object zero. 395 396Changes to section "3.7.13 Texture Objects" of the OpenGL ES 2.0 specification 397(ignore for OpenGL ES 1.x) 398 399 - Modify this section as follows: (changed lines marked with *, and added 400 lines are marked with +) 401 402* "In addition to the default textures TEXTURE_2D, TEXTURE_CUBE_MAP, 403* and TEXTURE_EXTERNAL_OES, named two-dimensional, cube map, and 404 external texture objects can be created and operated upon. The name 405 space for texture objects is the unsigned integers, with zero reserved 406 by the GL. 407 408 A texture object is created by binding an unused name to 409* TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES. The binding is 410 effected by calling 411 void BindTexture( enum target, uint texture ); 412 with target set to the desired texture target and texture set to the 413 unused name. The resulting texture object is a new state vector, 414 comprising all the state values listed in section 3.7.12, set to the 415 same initial values. If the new texture object is bound to TEXTURE_2D, 416* TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES it is and remains a 417* two-dimensional, cube map, or external texture respectively until it 418 is deleted. 419 420 BindTexture may also be used to bind an existing texture object to 421* either TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES. The error 422 INVALID_OPERATION is generated if an attempt is made to bind a texture 423* object of different target than the specified target. If the bind is 424 successful no change is made to the state of the bound texture object, 425 and any previous binding to target is broken. 426 427 While a texture object is bound, GL operations on the target to 428 which it is bound affect the bound object, and queries of the target to 429 which it is bound return state from the bound object. If texture 430 mapping is enabled, the state of the bound texture object directs the 431 texturing operation. 432 433* In the initial state, TEXTURE_2D, TEXTURE_CUBE_MAP, and 434* TEXTURE_EXTERNAL_OES have two-dimensional, cube map, and external 435 texture state vectors respectively associated with them. In order 436 that access to these initial textures not be lost, they are treated as 437 texture objects all of whose names are 0. The initial two-dimensional, 438* cube map, and external texture are therefore operated upon, queried, 439* and applied as TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES 440 respectively while 0 is bound to the corresponding targets. 441 442 Texture objects are deleted by calling 443 void DeleteTextures( sizei n, uint *textures ); 444 textures contains n names of texture objects to be deleted. After a 445 texture object is deleted, it has no contents or dimensionality, and 446 its name is again unused. If a texture that is currently bound to one 447* of the targets TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES 448 is deleted, it is as though BindTexture had been executed with the 449 same target and texture zero. Unused names in textures are silently 450 ignored, as is the value zero. 451 452 The command 453 void GenTextures( sizei n, uint *textures ); 454 returns n previously unused texture object names in textures. These 455 names are marked as used, for the purposes of GenTextures only, but 456 they acquire texture state only when they are first bound, just as if 457 they were unused. 458 459 The texture object name space, including the initial texture 460 object, is shared among all texture units. A texture object may be 461 bound to more than one texture unit simultaneously. After a texture 462 object is bound, any GL operations on that target object affect any 463 other texture units to which the same texture object is bound. 464 465 Texture binding is affected by the setting of the state 466 ACTIVE_TEXTURE. 467 468 If a texture object is deleted, it is as if all texture units which 469 are bound to that texture object are rebound to texture object zero. 470 471Changes to section "3.7.13 Texture Application" of the OpenGL ES 1.1 472specification (ignore for OpenGL ES 2.x) 473 474 - Replace the first sentence of the first paragraph with: 475 476 "Texturing is enabled or disabled using the generic Enable and 477 Disable commands, with the symbolic constant TEXTURE_2D or 478 TEXTURE_EXTERNAL_OES to enable or disable texturing with the 479 TEXTURE_2D or TEXTURE_EXTERNAL_OES texture target, respectively. If 480 TEXTURE_EXTERNAL_OES is enabled it takes precedence over TEXTURE_2D, 481 TEXTURE_CUBE_MAP_OES, TEXTURE_RECTANGLE_ARB, and 482 TEXTURE_RECTANGLE_NV." 483 484Changes to section "3.8.2 Shader Execution" of the OpenGL ES 2.0 485specification (ignore for OpenGL ES 1.x) 486 487 - Add to the end of the last paragraph of the subsection "Texture Access" 488 489 "The REQUIRED_TEXTURE_IMAGE_UNITS_OES parameter can change based on the 490 number of external textures which are currently bound (see section 491 3.7.14)." 492 493Changes to section "6.1.3 Enumerated Queries" of the OpenGL ES 1.1 specification 494 495 - Change: 496 "...TEXTURE_2D..." 497 to 498 "...TEXTURE_2D or TEXTURE_EXTERNAL..." 499 in the last paragraph. 500 501Changes to section "6.1.3 Enumerated Queries" of the OpenGL ES 2.0 specification 502 503 - Change: 504 "...TEXTURE_2D or TEXTURE_CUBE_MAP..." 505 to 506 "...TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL..." 507 in the second paragraph. 508 509 510Changes to section "6.2 State Tables" of the OpenGL ES 1.1 specification 511 512 - Add to "Table 6.13 Textures (state per texture unit and binding point)" 513 514 +-------------------+-------+-------------+-------+------------------+ 515 | TEXTURE_BINDING_- | 8*xZ+ | GetIntegerv | 0 | Texture object | 516 | EXTERNAL_OES | | | | bound to | 517 | | | | | TEXTURE_- | 518 | | | | | EXTERNAL_OES | 519 +-------------------+-------+-------------+-------+------------------+ 520 | TEXTURE_- | 2*xB | IsEnabled | False | True if external | 521 | EXTERNAL_OES | | | | texturing is | 522 | | | | | enabled | 523 +-------------------+-------+-------------+---+----------------------+ 524 525 - Add to "Table 6.14 Textures (state per texture object)" 526 527 +--------------------+-------+-----------------+---+----------------+ 528 | REQUIRED_TEXTURE_- | n*xZ3 | GetTexParameter | 1 | Number of | 529 | IMAGE_UNITS_OES | | | | texture image | 530 | | | | | units required | 531 | | | | | by texture | 532 +--------------------+-------+-----------------+---+----------------+ 533 534Changes to section "6.2 State Tables" of the OpenGL ES 2.0 specification 535 536 - Add to "Table 6.7 Textures (state per texture unit and binding point)" 537 538 +-------------------+-------+-------------+-------+------------------+ 539 | TEXTURE_BINDING_- | 8*xZ+ | GetIntegerv | 0 | Texture object | 540 | EXTERNAL_OES | | | | bound to | 541 | | | | | TEXTURE_- | 542 | | | | | EXTERNAL_OES | 543 +-------------------+-------+-------------+-------+------------------+ 544 545 - Add to "Table 6.8 Textures (state per texture object)" 546 547 +--------------------+-------+-----------------+---+----------------+ 548 | REQUIRED_TEXTURE_- | n*xZ3 | GetTexParameter | 1 | Number of | 549 | IMAGE_UNITS_OES | | | | texture image | 550 | | | | | units required | 551 | | | | | by texture | 552 +--------------------+-------+-----------------+---+----------------+ 553 554Changes to section 3.7 of the OpenGL ES Shading Language specification 555 556 - Add to the list of keywords: 557 558 "samplerExternalOES" 559 560Changes to section 4.1 of the OpenGL ES Shading Language specification 561 562 - Add to the list of basic types: 563 564 "samplerExternalOES a handle for accessing an external texture" 565 566Changes to section 4.5.3 of the OpenGL ES Shading Language specification 567 568 - Add to the list of "vertex language has the following predeclared 569 globally scoped default precision statements:" 570 571 "precision lowp samplerExternalOES;" 572 573 - Add to the list of "fragment language has the following predeclared 574 globally scoped default precision statements:" 575 576 "precision lowp samplerExternalOES;" 577 578Changes to section 8.7 of the OpenGL ES Shading Language specification 579 580 - Add to the table the following sampler functions: 581 582 "vec4 texture2D( 583 samplerExternalOES sampler, 584 vec2 coord) 585 vec4 texture2DProj( 586 samplerExternalOES sampler, 587 vec3 coord) 588 vec4 texture2DProj( 589 samplerExternalOES sampler, 590 vec4 coord)" 591 592 593Changes to section 9 of the OpenGL ES Shading Language specification 594 595 - Add to token list: 596 597 "SAMPLEREXTERNAL" 598 599 - Add following "type_specifier_no_prec:" 600 601 "SAMPLEREXTERNAL" 602 603Changes to section "A.7 Counting of Varyings and Uniforms" of the OpenGL ES 604Shading Language specification 605 606 - Change the first sentence of the last paragraph to 607 608 "Part of the storage may be reserved by an implementation for its own 609 use e.g. for computation of transcendental functions or conversion of 610 external textures." 611 612 613Issues 614 615 1. What happens when GenerateMipmaps() is called with <target> set to 616 TEXTURE_EXTERNAL_OES? 617 618 Possible options: 619 620 A) Fail (INVALID_ENUM) 621 B) Generate the mipmaps and copy them into the TEXTURE_2D target. 622 623 Option B could be useful and should not be difficult to implement. 624 What happens when the texture is NPOT and GenerateMipmaps() is called? 625 626 Ben Bowman and David Garcia have indicated they prefer A. No other 627 strong opinions yet. 628 629 RESOLVED: A (fail) 630 631 2. Should the wrap mode of an external texture be allowed to be anything 632 other than CLAMP_TO_EDGE? 633 634 RESOLVED: no 635 636 3. What about portability problems introduced by allowing implementation- 637 dependent failures? 638 639 This is the same issue described in Issue 14 of the 640 EGL_OES_image specification. Like the resolution for that issue, 641 this specification should include some minimum requirements, but 642 leave the larger portability problem unresolved at the moment. 643 644 RESOLVED: This and other (EGL_KHR_image_uses and EGL_KHR_il_image) 645 extensions attempt to minimize this problem by allowing EGL to pick 646 EGLImage attributes which will work in various situations. However it 647 is not possible to guarantee that every usecase will work on every 648 platform. 649 650 4. Should EGLImageTargetTexture2DOES result in undefined pixel data, 651 as with calls to eglCreateImageOES? 652 653 See also issue 4 of GL_OES_EGL_image 654 655 Comment from Aske: 656 In the description for EGLImageTargetTexture2DOES, it says: "As a 657 result of this operation all pixel data in <image> will become 658 undefined." Why is this? I would imagine one would want to take an 659 existing EGL image containing image data and bind it as an external 660 texture, possibly multiple times, to use it for rendering. I have read 661 through issue 4 of OES_EGL_image, and it seems the concern here is 662 what happens when the image is (potentially) modified from OpenGL ES. 663 Since external images cannot be modified from OpenGL ES, I would guess 664 the same issues do not apply here. 665 666 Comment from Acorn: 667 Another potential issue is that the memory for the EGLImage may 668 have to be reallocated in order to be compatible with GLES (e.g. GLES 669 may have more strict alignment or other requirements). However, the 670 implementation can fail (or do a copy) if this is the case. If the 671 EGL_KHR_image_uses extension is used to specify that the EGLImage will 672 be used as a GLES external texture then this should not be an issue 673 because EGL will be able to allocate the memory correctly in the first 674 place. 675 676 RESOLVED: pixel data will not become undefined when 677 EGLImageTargetTexture2DOES() is used with an external texture target. 678 679 5. What happens if the texture is bound while the associated EGLImage is 680 being modified. 681 682 Some implementations may need to color convert the data 683 after it has been generated. A solution to this is to state that the 684 texels become undefined if the external texture is bound while the 685 underlying texels are modified. This way any color conversion can be 686 done (e.g. to a second buffer) when the texture is bound. 687 688 Options: 689 A) require the texture be unbound while the EGLImage is being modified 690 B) Require the texture to be bound (or re-bound if already bound) 691 between modification and use (i.e. after modification and before 692 used as a texture). 693 C) No requirement. 694 695 RESOLVED: B 696 697 6. How can current generation hardware support planar YUV EGLImage formats? 698 699 GLES 2.0 hardware can perform color conversion by inserting 700 extra instructions into the shader program. However, planar textures 701 require 2 or 3 surfaces to be read in order to sample a single texture. 702 One solution is to increase the number of texture image units required 703 by a texture object which is associated with such an EGLImage. 704 705 RESOLVED: allow the implementation to set the number of texture 706 image units required by each texture object. Allow the app to query 707 this with REQUIRED_TEXTURE_IMAGE_UNITS_OES. Have drawing commands 708 fail (INVALID_OPERATION) when the number of texture image units 709 required by all enabled/referenced texture units exceeds the 710 implementation limit (which can be queried with 711 MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, and 712 MAX_TEXTURE_IMAGE_UNITS) 713 714 See also issue 10. 715 716 7. Should there be new texture sampling functions for samplerExternalOES 717 or is it OK to use the existing 2D sampler functions. 718 719 RESOLVED: Use existing 2D sampler functions. 720 721 8. If an EGLImage associated with an external texture does not contain an 722 alpha channel, should the alpha be 1 or undefined. 723 724 From an app point of view, 1 probably makes more sense. 725 However, if the texture is in a RGBA format and there is garbage in 726 the A channel, it may be difficult for implementations to return 1. 727 An implementation may have to recompile the shader to force the alpha 728 channel to 1. 729 730 RESOLVED: alpha is defined to be 1 in this case. 731 732 9. How should the color conversion be described. 733 734 Options: 735 736 A) State that the color values are transformed to a linear colorspace 737 and represented as RGB values in that space. This may be difficult 738 for implementations since it may require nonlinear transformations 739 (e.g. gamma decoding). It is also problematic because usually many 740 more bits are required to represent a value in a linear colorspace 741 than in a gamma encoded colorspace. 742 743 B) State that the color is transformed to RGB but in the same 744 colorspace as the source image (i.e. no gamma encode or decode). 745 746 RESOLVED: Option B. 747 748 10. How does the implementation indicate which texture samplers and/or 749 texture units are not available when one or more external textures are 750 bound. 751 752 See discussion on GLES email list around Feb 23 with 753 subject "RE: [OpenGL-ES] IL/ES interaction: YUV texture extension 754 proposal" 755 756 Proposals: 757 758 A) The MAX_COMBINED_TEXTURE_IMAGE_UNITS, 759 MAX_VERTEX_TEXTURE_IMAGE_UNITS, and MAX_TEXTURE_IMAGE_UNITS parameters 760 change to reflect the current state. 761 762 B) New queries AVAILABLE_COMBINED_TEXTURE_IMAGE_UNITS, 763 AVAILABLE_VERTEX_TEXTURE_IMAGE_UNITS, and 764 AVAILABLE_TEXTURE_IMAGE_UNITS indicate current state, while 765 MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, and 766 MAX_TEXTURE_IMAGE_UNITS remain constant and indicate the state when no 767 external textures are bound. 768 769 C) Query for number of required texture image units per texture 770 object. Draw calls fail with INVALID_OPERATION if the current 771 requirements for texture image units exceeds the number available. 772 773 RESOLVED: C 774 775 11. What happens when glUniform1i() sets a sampler to a value that is 776 larger than the number of available texture units? 777 778 NOTE: This issue no longer affects this extension. See issue 10 for 779 different issue related to texture *image* units. 780 781 This is really a GLES2 spec issue. See 782 khronos bug 3702 783 https://cvs.khronos.org/bugzilla/show_bug.cgi?id=3702 784 http://www.khronos.org/members/login/list_archives/arb-glsl/ 785 0705/msg00010.html 786 http://www.khronos.org/members/login/list_archives/opengl_es/ 787 0902/msg00148.html 788 789 RESOLVED: The issue is not resolved, but it no longer applies 790 directly to this extension. Further discussion should be in bug 3702. 791 792 12. What happens at draw time when the current state requires more texture 793 units than the implementation can support? 794 795 RESOLVED: The precedent, from (desktop) OpenGL, is to fail in 796 glValidate, and to fail in any draw call with an INVALID_OPERATION 797 error. Behavior described in this extension will match that 798 precedent. 799 800 13. How can this be conformance tested? 801 802 In the native code, add a function which takes as a 803 parameter an array of pixels. The function returns an EGLImage which 804 contains the pixels in some unspecified format. A test can call this 805 function, call glEGLImageTargetTexture2DOES() to associate it with an 806 external texture, and render using this texture, and read back the 807 framebuffer to confirm that the result is the expected result. 808 809 Note1: since the format is unknown and unknowable, possibly only the 810 high bit of each component (RGB) should be tested. It may be 811 sufficient to pass a single pixel (or single bit for each of R, G, an 812 B) and then create the EGLImage with every pixel in the image set to 813 that same value. 814 815 Note2: It might be a good idea to have an extra parameter, int index, 816 which allows the function to be implemented several different ways. 817 The test could be run several times, with index set to 0, 1, 2, ... 818 until the function returns EGL_NO_IMAGE. This way the function could 819 generate EGLImages with various formats. For example when index is 0 820 it could call OMX IL to generate a YUV planar EGLImage, when index is 821 1 it could call OMX AL to generate a YUV interleaved EGLImage, and 822 when index is 2 it could call into VG to generate an RGB EGLImage. 823 The meaning of each index would be up to the implementation. A simple 824 implementation might return an EGLImage when index=0 and return 825 EGL_NO_IMAGE otherwise. 826 827 Additional suggestion from Jon Leech: 828 The suggested conformance test in issue 13 is intentionally so vague 829 on precision (1 bit/component) that the conversion language seems even 830 less meaningful. The RGB bits that come out of texture sampling would 831 need have almost no relationship to what went in. ISTM the supplier of 832 the EGLImage knows the precision of it, and that information could be 833 provided to the test to put on tighter constraints. 834 835 RESOLVED: As described above. 836 837 14. Can the number of uniforms required by a shader change when switching 838 from one external texture to another, and therefore cause the shader 839 to fail? For example, imagine a program does this: 840 glLinkProgram(prog); // successful link 841 sampler = glGetUniformLocation(prog, "myExtSampler"); 842 glUniform1i(sampler, 1); 843 glActiveTexture(GL_TEXTURE1); 844 glBindTexture(GL_TEXTURE_EXTERNAL, myTex1_rgb); 845 glDrawArrays(); // draw successfully 846 847 glBindTexture(GL_TEXTURE_EXTERNAL, myTex2_yuv); 848 glDrawArrays(); // Can this fail??? 849 Is it acceptable for an implementation to fail the second 850 glDrawArrays() call because myTex2_yuv is a yuv image and requires 851 more uniforms to implement a color conversion matrix than myTex1_rgb 852 which is an rgb image and does not require any conversion matrix? 853 854 Note that this situation will only occur on implementation which will 855 recompile the shader based on the color conversion required. 856 857 Options: 858 859 A) No, the implementation is not allowed to fail. When the program is 860 linked the implementation must verify that there are enough uniforms 861 to implement the program for any flavor of external texture. If the 862 implementation does not provide enough uniforms for the program to 863 work with any external texture that the implementation supports, then 864 the implementation must fail at link time. 865 866 B) Yes, the implementation may fail in glDrawArrays or glDrawElements 867 if the number of uniforms required by the program exceeds those 868 available. This means that a call to glUniform1i() or glBindTexture() 869 can cause a shader program that used to work to stop working. (Note 870 that this is possible anyway since the new external texture may use 871 more texture image units than the old external texture (independent of 872 the number of uniforms). But that can be detected by the application 873 by querying REQUIRED_TEXTURE_IMAGE_UNITS_OES) 874 875 RESOLVED: choice B. 876 877 15. How should filtering of non-RGB formats be specified. 878 879 Options: 880 881 A) filtering occurs before transformation to RGB. 882 B) filtering occurs after transformation to RGB. 883 C) undefined (up to the implementation) 884 885 RESOLVED: C 886 887Dependencies on EGL_OES_image_base and EGL 1.1 888 889 If either EGL 1.1 or the EGL_OES_image extension is not supported, all 890 discussion of EGLImages should be ignored, and any calls to 891 EGLImageTargetTexture2DOES should generate the error INVALID_OPERATION. 892 893Dependencies on GL_OES_EGL_image 894 895 If GL_OES_EGL_image is supported then change the text in both extensions 896 to allow either TEXTURE_2D or TEXTURE_EXTERNAL_OES to be passed as the 897 <target> parameter to EGLImageTargetTexture2DOES(). When <target> is 898 TEXTURE_2D, behavior of EGLImageTargetTexture2DOES() is as described in 899 the GL_OES_EGL_image spec. When <target> is TEXTURE_EXTERNAL_OES, 900 behavior of EGLImageTargetTexture2DOES() is as described in this spec. 901 902Revision History 903 904 #25 - (April 6, 2018) H1Gdev 905 Fix typo. 906 #24 - (April 23, 2015) Jon Leech) 907 - Fix typo EGLImageTargetTexImage2DOES -> EGLImageTargetTexture2DOES 908 (Bug 8114). Improve description of supported queries for new 909 tokens (Bug 8118). 910 #23 - (July 19, 2012) Acorn Pooley 911 - fix extension name from OES_EGL_image_external to 912 GL_OES_EGL_image_external 913 #22 - (Dec 17, 2010) Acorn Pooley 914 status to ratified. 915 #21 - (Sept. 29, 2010) Maurice Ribble 916 Update token numbers and updated status to approved. 917 #20 - (April 2, 2009) Acorn Pooley 918 Rename GL_OES_egl_image_external to GL_OES_EGL_image_external to be 919 consistant with GL_OES_EGL_image. 920 #19 - (March 31, 2009) Acorn Pooley 921 Minor fixes 922 #18 - (March 30, 2009) Acorn Pooley 923 Fix inconsistancy 924 #17 - (March 25, 2009) Acorn Pooley 925 Resolved issue 4 (and some others) 926 #16 - (March 16, 2009) Acorn Pooley 927 Augment issue 13 928 #15 - (March 13, 2009) Acorn Pooley 929 fix dependancy section 930 resolve issue 14 and fix text 931 #14 - (March 9, 2009) Acorn Pooley 932 Fix colorspace comments. Issue 9 is resolved. 933 #13 - (March 6, 2009) Acorn Pooley 934 Mark issue 6, 10, and 11 resolved. 935 Add issue 15. 936 #12 - (March 4, 2009) Acorn Pooley 937 Fix wording of uniform stuff. 938 #11 - (March 4, 2009) Acorn Pooley 939 Add issues 13, 14. 940 Add comments about extra uniforms required by external texture 941 samplers. 942 Allow external textures to work with default object 0. 943 Correct colorspace language. 944 #10 - (March 3, 2009) Acorn Pooley 945 Remove stale reference to MAX_TEXTURE_IMAGE_UNITS. Add fix to OpenGL 946 ES 2.0 section 2.10.5 (from bruce). Add contributors. Clarify 947 "texture unit" vs "texture image unit". Fix typos. 948 #9 - (February 26, 2009) Acorn Pooley 949 Clarify sync further. Add issue 12. Change "too many texture units" 950 behavior. 951 #8 - (February 26, 2009) Acorn Pooley 952 Clarify sync requirements (i.e. that EGLImage does not do sync) 953 #7 - (February 25, 2009) Acorn Pooley 954 Relax binding requirement - see issue 5 955 #6 - (February 25, 2009) Acorn Pooley 956 Add TEXTURE_BINDING_EXTERNAL_OES. Add texture state notes. Modify 957 colorspace conversion to be a linear function. 958 #5 - (February 24, 2009) Acorn Pooley 959 Disable GenerateMipmaps. Add issues 10 & 11. 960 #4 - (February 23, 2009) Acorn Pooley 961 Modify the "Texture Parameters" section in ES 1 and 2 specs 962 #3 - (February 20, 2009) Acorn Pooley 963 Clarify the reduction in number of texture units. 964 #2 - (February 20, 2009) Acorn Pooley 965 Fix some errors. replace textureExternal* sampler functions with 966 existing sampler2D* functions. Add issue 7,8,9. Fix spelling. 967 #1 - (February 9, 2009) Original draft 968