| Name |
| |
| OES_EGL_image_external |
| |
| Name Strings |
| |
| GL_OES_EGL_image_external |
| |
| Contributors |
| |
| Acorn Pooley |
| David Garcia |
| Bruce Merry |
| Aske Simon Christensen |
| Mark Callow |
| Tom Olson |
| Jon Leech |
| Maurice Ribble |
| |
| Contacts |
| |
| Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) |
| |
| Notice |
| |
| Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Specification Update Policy |
| |
| Khronos-approved extension specifications are updated in response to |
| issues and bugs prioritized by the Khronos OpenGL ES Working Group. For |
| extensions which have been promoted to a core Specification, fixes will |
| first appear in the latest version of that core Specification, and will |
| eventually be backported to the extension document. This policy is |
| described in more detail at |
| https://www.khronos.org/registry/OpenGL/docs/update_policy.php |
| |
| Status |
| |
| Ratified by Khronos Promoters, 10 December 2010 |
| Approved by the OpenGL ES Working Group, 15 September 2010 |
| |
| Version |
| |
| April 6, 2018 (version 25) |
| |
| Number |
| |
| OpenGL ES Extension #87 |
| |
| Dependencies |
| |
| Requires OpenGL ES 1.1 or OpenGL ES 2.0. |
| |
| Requires EGL 1.2 |
| |
| Requires either the EGL_KHR_image_base or the EGL_KHR_image extension |
| |
| This extension is written based on the wording of the OpenGL ES 2.0 |
| specification, the OpenGL ES Shading Language version 1.0, and the |
| EGL_KHR_image_base extension. On an OpenGL ES 2.0 implementation, ignore |
| sections which are added only to the OpenGL ES 1.1 specification. |
| |
| This extension is also written based on the wording of the OpenGL ES 1.1 |
| specification. On an OpenGL ES 1.X implementation, ignore sections which |
| are added only to the OpenGL ES 2.0 or OpenGL ES Shading Language |
| specification. Also ignore all mention of MAX_VERTEX_TEXTURE_IMAGE_UNITS, |
| and MAX_COMBINED_TEXTURE_IMAGE_UNITS. |
| |
| This extension borrows concepts and function names from the |
| GL_OES_EGL_image extension. This extension is compatible with, but does |
| not require, the GL_OES_EGL_image extension. |
| |
| Overview |
| |
| This extension provides a mechanism for creating EGLImage texture targets |
| from EGLImages. This extension defines a new texture target, |
| TEXTURE_EXTERNAL_OES. This texture target can only be specified using an |
| EGLImage. There is no support for most of the functions that manipulate |
| other texture targets (e.g. you cannot use gl*Tex*Image*() functions with |
| TEXTURE_EXTERNAL_OES). Also, TEXTURE_EXTERNAL_OES targets never have more |
| than a single LOD level. Because of these restrictions, it is possible to |
| bind EGLImages which have internal formats not otherwise supported by |
| OpenGL ES. For example some implementations may allow EGLImages with |
| planar or interleaved YUV data to be GLES texture target siblings. It is |
| up to the implementation exactly what formats are accepted. |
| |
| Glossary |
| |
| Please see the EGL_OES_image_base specification for a list of terms |
| used by this specification. |
| |
| New Types |
| |
| /* |
| * GLeglImageOES is an opaque handle to an EGLImage |
| * Note: GLeglImageOES is also defined in GL_OES_EGL_image |
| */ |
| typedef void* GLeglImageOES; |
| |
| /* (OpenGL ES 2.x only) |
| * New sampler type allowed by the OpenGL ES Shading Language when |
| * #extension GL_OES_EGL_image_external |
| * is used. |
| */ |
| samplerExternalOES |
| |
| New Procedures and Functions |
| |
| /* Note: EGLImageTargetTexture2DOES is also defined in GL_OES_EGL_image */ |
| void EGLImageTargetTexture2DOES(enum target, eglImageOES image) |
| |
| New Tokens |
| |
| Accepted as a target in the <target> parameter of BindTexture and |
| EGLImageTargetTexture2DOES: |
| |
| TEXTURE_EXTERNAL_OES 0x8D65 |
| |
| (OpenGL ES 2.x only) Returned in the <type> parameter of GetActiveUniform: |
| SAMPLER_EXTERNAL_OES 0x8D66 |
| |
| Accepted as the <pname> parameter of GetBooleanv, GetIntegerv, |
| GetFloatv, and GetFixedv: |
| TEXTURE_BINDING_EXTERNAL_OES 0x8D67 |
| |
| Accepted as <value> in GetTexParameter*() queries: |
| REQUIRED_TEXTURE_IMAGE_UNITS_OES 0x8D68 |
| |
| |
| Additions to Chapter 3 of the OpenGL 1.1 or OpenGL 2.0 Specification |
| |
| - For OpenGL ES 2.0 add a new section: "3.7.14 External Textures," which |
| follows section "3.7.13 Texture Objects." For OpenGL ES 1.1 add a new |
| section after section "3.7.11 Texture Objects." |
| |
| "3.7.14 External Textures |
| |
| External textures cannot be used with TexImage2D, TexSubImage2D, |
| CompressedTexImage2D, CompressedTexSubImage2D, CopyTexImage2D, or |
| CopyTexSubImage2D, and an INVALID_ENUM error will be generated if this |
| is attempted. Their default min filter is LINEAR. It is an |
| INVALID_ENUM error to set the min filter value to anything other than |
| LINEAR or NEAREST. The default s and t wrap modes are CLAMP_TO_EDGE |
| and it is an INVALID_ENUM error to set the wrap mode to any other |
| value. (For OpenGL ES 1.x only: The texture parameter GENERATE_MIPMAP |
| is always FALSE, and setting it to any other value generates an |
| INVALID_ENUM error. (For OpenGL ES 2.x only: Calling GenerateMipmaps |
| with <target> set to TEXTURE_EXTERNAL_OES results in an INVALID_ENUM.) |
| |
| The command |
| |
| void EGLImageTargetTexture2DOES(enum target, eglImageOES image); |
| |
| with <target> set to TEXTURE_EXTERNAL_OES defines the currently bound |
| external texture object to be a target sibling of <image>. The width, |
| height, format, type, internalformat, border, and image data are all |
| determined based on the specified eglImageOES <image>. Any sibling |
| previously associated with this external texture object is deleted. |
| |
| A EGLImageTargetTexture2DOES() call with <target> set to |
| TEXTURE_EXTERNAL_OES will not modify the pixel data values in the |
| EGLImage. |
| |
| <image> must be the handle of a valid EGLImage resource, cast into the |
| type eglImageOES. |
| |
| Assuming no errors are generated in EGLImageTargetTexture2DOES, the |
| newly specified texture object will be an EGLImage target of the |
| specified eglImageOES. |
| |
| If the GL is unable to specify a texture object using the supplied |
| eglImageOES <image> (if, for example, <image> refers to a multisampled |
| eglImageOES), the error INVALID_OPERATION is generated. |
| |
| If <target> is not TEXTURE_EXTERNAL_OES, the error INVALID_ENUM is |
| generated. (Note: if GL_OES_EGL_image is supported then <target> may |
| also be TEXTURE_2D). |
| |
| Sampling an external texture which is not associated with any EGLImage |
| sibling will return a sample value of (0,0,0,1). |
| |
| Each TEXTURE_EXTERNAL_OES texture object may require up to 3 texture |
| image units for each texture unit to which it is bound. The number of |
| texture image units required by a bound texture object can be queried |
| using GetTexParameteriv() with <target> set to the texture target in |
| question, <value> set to REQUIRED_TEXTURE_IMAGE_UNITS_OES, and |
| ActiveTexture set to the texture unit to which the texture object is |
| bound. When <target> is set to TEXTURE_EXTERNAL_OES this value will |
| be between 1 and 3 (inclusive). For other valid texture targets this |
| value will always be 1. Note that, when a TEXTURE_EXTERNAL_OES |
| texture object is bound, the number of texture image units required by |
| a single texture unit may be 1, 2, or 3, while for other texture |
| objects each texture unit requires exactly 1 texture image unit. |
| |
| (For OpenGL ES 1.x only) DrawArrays and DrawElements will fail and |
| generate an INVALID_OPERATION error if the number of texture image |
| units required is greater than the number available. The number of |
| required texture image units is equal to the sum of the requirements |
| for each enabled texture unit. For each texture unit the requirement |
| is the value returned by GetTexParameteriv() when <value> is set to |
| REQUIRED_TEXTURE_IMAGE_UNITS_OES, <target> is set to the target which |
| is enabled, and ActiveTexture has been set to the texture unit in |
| question. |
| |
| (For OpenGL ES 2.x only) DrawArrays and DrawElements will fail and |
| generate an INVALID_OPERATION error if the number of texture image |
| units required is greater than the number available. The number of |
| required texture image units for each stage (fragment or vertex) is |
| equal to the sum of the requirements for each sampler referenced by |
| the stage. A sampler is considered referenced if its location |
| (returned by GetUniformLocation) is not -1. For each referenced |
| sampler the requirement is the value returned by GetTexParameteriv() |
| when <value> is set to REQUIRED_TEXTURE_IMAGE_UNITS_OES, <target> is |
| set to the target corresponding to the sampler type, and ActiveTexture |
| has been set to the texture unit corresponding to the value of the |
| sampler uniform. The condition can be detected by calling Validate. |
| |
| (For OpenGL ES 2.x only) A shader that uses external texture samplers |
| may require some number of hidden uniform variables to implement the |
| conversion from YUV to RGB, and this may reduce the amount of space |
| available for uniforms defined by the shader program. This may cause |
| a shader program which was working to stop working when a different |
| external texture is used (i.e. when Uniform1i or BindTexture is |
| called). If there are not enough uniforms available then calls to |
| DrawArrays or DrawElements will fail and generate an INVALID_OPERATION |
| error. This condition can be detected by calling ValidateProgram. |
| |
| Sampling an external texture which has been modified since it was |
| bound will return samples which may correspond to image values either |
| before, during, or after the modification. Binding (or re-binding if |
| already bound) an external texture by calling BindTexture after all |
| modifications are complete guarantees that sampling done in future |
| draw calls will return values corresponding to the values in the |
| buffer at or after the time that BindTexture is called. (Note that |
| calling BindTexture after calling commands that modify the EGLImage |
| may not be sufficient to ensure that the modifications are complete; |
| additional synchronization (for example eglWaitAPI, eglWaitNative, |
| glFinish, vgFinish, or eglWaitSyncKHR, etc) may be required following |
| the call initiating modifications, to ensure they have taken effect on |
| the texture, before the call to BindTexture is made.) |
| |
| Sampling an external texture will return an RGBA vector in the same |
| colorspace as the source image. If the source image is stored in YUV |
| (or some other basis) then the YUV values will be transformed to RGB |
| values. (But these RGB values will be in the same colorspace as the |
| original image. Colorspace here includes the linear or non-linear |
| encoding of the samples. For example, if the original image is in the |
| sRGB color space then the RGB value returned by the sampler will also |
| be sRGB, and if the original image is stored in ITU-R Rec. 601 YV12 |
| then the RGB value returned by the sampler will be an RGB value in the |
| ITU-R Rec. 601 colorspace.) The parameters of the transformation |
| from one basis (e.g. YUV) to RGB (color conversion matrix, sampling |
| offsets, etc) are taken from the EGLImage which is associated with the |
| external texture. The implementation may choose to do this |
| transformation when the external texture is sampled, when the external |
| texture is bound, or any other time so long as the effect is the same. |
| It is undefined whether texture filtering occurs before or after the |
| transformation to RGB. |
| |
| If the EGLImage associated with the external texture contains alpha |
| values then the value of the alpha component returned is taken from |
| the image; otherwise the alpha component is 1.0. |
| |
| Changes to section "2.10.4 Shader Variables" of the OpenGL ES 2.0 |
| specification (ignore for OpenGL ES 1.x) |
| |
| - In the subsection "Uniform Variables" paragraph 13, last sentence, add |
| |
| "SAMPLER_EXTERNAL_OES" |
| to the list of types that can be returned. |
| |
| Changes to section "2.10.5 Shader Execution" of the OpenGL ES 2.0 |
| specification (ignore for OpenGL ES 1.x) |
| |
| - In the subsection "Validation", add to the bullet points in the second |
| paragraph: |
| |
| "- the number of texture image units required is greater than |
| the number available (see REQUIRED_TEXTURE_IMAGE_UNITS_OES, |
| MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, |
| and MAX_TEXTURE_IMAGE_UNITS). |
| |
| - the number of uniforms required to implement the shader program is |
| greater than the number available." |
| |
| Changes to section "3.7.5 Texture Parameters" of the OpenGL ES 1.1 specification |
| |
| - Add to the end of the section a new paragraph: |
| |
| "When <target> is TEXTURE_EXTERNAL_OES only NEAREST and LINEAR are |
| accepted as TEXTURE_MIN_FILTER, only CLAMP_TO_EDGE is accepted as |
| TEXTURE_WRAP_S and TEXTURE_WRAP_T, and only FALSE is accepted as |
| GENERATE_MIPMAP. Attempting to set other values for |
| TEXTURE_MIN_FILTER, TEXTURE_WRAP_S, TEXTURE_WRAP_T, or GENERATE_MIPMAP |
| will result in an INVALID_ENUM error. |
| |
| Changes to section "3.7.4 Texture Parameters" of the OpenGL ES 2.0 Specification |
| |
| - Add to the end of the section a new paragraph: |
| |
| "When <target> is TEXTURE_EXTERNAL_OES only NEAREST and LINEAR are |
| accepted as TEXTURE_MIN_FILTER and only CLAMP_TO_EDGE is accepted as |
| TEXTURE_WRAP_S and TEXTURE_WRAP_T. Attempting to set other values for |
| TEXTURE_MIN_FILTER, TEXTURE_WRAP_S, or TEXTURE_WRAP_T will result in |
| an INVALID_ENUM error. |
| |
| Changes to section "3.7.10 Texture State" of the OpenGL ES 1.1 Specification |
| and section "3.7.12 Texture State" of the OpenGL ES 2.0 Specification |
| |
| - Add an additional sentence at the end of the section: |
| |
| "In the initial state of a TEXTURE_EXTERNAL_OES texture object, |
| the value assigned to TEXTURE_MIN_FILTER and TEXTURE_MAG_FILTER is |
| LINEAR, and the s and t wrap modes are both set to |
| CLAMP_TO_EDGE." |
| |
| Changes to section "3.7.11 Mipmap Generation" of the OpenGL ES 2.0 Specification |
| (ignore for OpenGL ES 1.x) |
| |
| - Add two additional paragraphs to the end of the section: |
| |
| "When <target> is set to TEXTURE_EXTERNAL_OES, GenerateMipmap |
| always fails and generates an INVALID_ENUM error." |
| |
| Changes to section "3.7.11 Texture Objects" of the OpenGL ES 1.1 specification |
| (ignore for OpenGL ES 2.x) |
| |
| - Modify this section as follows: (changed lines marked with *, and added |
| lines are marked with +) |
| |
| * "In addition to the default textures TEXTURE_2D and |
| * TEXTURE_EXTERNAL_OES, named two-dimensional and external texture |
| objects can be created and operated upon. The name space for texture |
| objects is the unsigned integers, with zero reserved by the GL. |
| |
| A texture object is created by binding an unused name to |
| * TEXTURE_2D or TEXTURE_EXTERNAL_OES. The binding is effected by calling |
| void BindTexture( enum target, uint texture ); |
| * with target set to the desired texture target and texture set to the |
| unused name. The resulting texture object is a new state vector, |
| comprising all the state values listed in section 3.7.10, set to the |
| + same initial values. If the new texture object is bound to TEXTURE_2D |
| + or TEXTURE_EXTERNAL_OES it is and remains a two-dimensional or |
| + external texture respectively until it is deleted. |
| |
| BindTexture may also be used to bind an existing texture object to |
| * TEXTURE_2D or TEXTURE_EXTERNAL_OES. If the bind is successful no |
| change is made to the state of the bound texture object, and any |
| previous binding to target is broken. |
| |
| While a texture object is bound, GL operations on the target to |
| which it is bound affect the bound object, and queries of the target |
| to which it is bound return state from the bound object. If texture |
| mapping is enabled, the state of the bound texture object directs the |
| texturing operation. |
| |
| * In the initial state, TEXTURE_2D and TEXTURE_EXTERNAL_OES have |
| * two-dimensional and external texture state vectors respectively |
| * associated with them. In order that access to these initial textures |
| * not be lost, they are treated as texture objects all of whose names |
| * are 0. The initial two-dimensional and external texture are therefore |
| * operated upon, queried, and applied as TEXTURE_2D or |
| * TEXTURE_EXTERNAL_OES respectively while 0 is bound to the |
| * corresponding targets. |
| |
| Texture objects are deleted by calling |
| void DeleteTextures( sizei n, uint *textures ); |
| textures contains n names of texture objects to be deleted. After a |
| texture object is deleted, it has no contents, and its name is again |
| unused. If a texture that is currently bound to the target TEXTURE_2D |
| * or TEXTURE_EXTERNAL_OES is deleted, it is as though BindTexture had |
| been executed with the same target and texture zero. Unused names in |
| textures are silently ignored, as is the value zero. |
| |
| The command |
| void GenTextures( sizei n, uint *textures ); |
| returns n previously unused texture object names in textures. These |
| names are marked as used, for the purposes of GenTextures only, but |
| they acquire texture state only when they are first bound, just as if |
| they were unused. |
| |
| The texture object name space, including the initial texture |
| object, is shared among all texture units. A texture object may be |
| bound to more than one texture unit simultaneously. After a texture |
| object is bound, any GL operations on that target object affect any |
| other texture units to which the same texture object is bound. |
| |
| Texture binding is affected by the setting of the state |
| ACTIVE_TEXTURE. |
| |
| If a texture object is deleted, it is as if all texture units which |
| are bound to that texture object are rebound to texture object zero. |
| |
| Changes to section "3.7.13 Texture Objects" of the OpenGL ES 2.0 specification |
| (ignore for OpenGL ES 1.x) |
| |
| - Modify this section as follows: (changed lines marked with *, and added |
| lines are marked with +) |
| |
| * "In addition to the default textures TEXTURE_2D, TEXTURE_CUBE_MAP, |
| * and TEXTURE_EXTERNAL_OES, named two-dimensional, cube map, and |
| external texture objects can be created and operated upon. The name |
| space for texture objects is the unsigned integers, with zero reserved |
| by the GL. |
| |
| A texture object is created by binding an unused name to |
| * TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES. The binding is |
| effected by calling |
| void BindTexture( enum target, uint texture ); |
| with target set to the desired texture target and texture set to the |
| unused name. The resulting texture object is a new state vector, |
| comprising all the state values listed in section 3.7.12, set to the |
| same initial values. If the new texture object is bound to TEXTURE_2D, |
| * TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES it is and remains a |
| * two-dimensional, cube map, or external texture respectively until it |
| is deleted. |
| |
| BindTexture may also be used to bind an existing texture object to |
| * either TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES. The error |
| INVALID_OPERATION is generated if an attempt is made to bind a texture |
| * object of different target than the specified target. If the bind is |
| successful no change is made to the state of the bound texture object, |
| and any previous binding to target is broken. |
| |
| While a texture object is bound, GL operations on the target to |
| which it is bound affect the bound object, and queries of the target to |
| which it is bound return state from the bound object. If texture |
| mapping is enabled, the state of the bound texture object directs the |
| texturing operation. |
| |
| * In the initial state, TEXTURE_2D, TEXTURE_CUBE_MAP, and |
| * TEXTURE_EXTERNAL_OES have two-dimensional, cube map, and external |
| texture state vectors respectively associated with them. In order |
| that access to these initial textures not be lost, they are treated as |
| texture objects all of whose names are 0. The initial two-dimensional, |
| * cube map, and external texture are therefore operated upon, queried, |
| * and applied as TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES |
| respectively while 0 is bound to the corresponding targets. |
| |
| Texture objects are deleted by calling |
| void DeleteTextures( sizei n, uint *textures ); |
| textures contains n names of texture objects to be deleted. After a |
| texture object is deleted, it has no contents or dimensionality, and |
| its name is again unused. If a texture that is currently bound to one |
| * of the targets TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL_OES |
| is deleted, it is as though BindTexture had been executed with the |
| same target and texture zero. Unused names in textures are silently |
| ignored, as is the value zero. |
| |
| The command |
| void GenTextures( sizei n, uint *textures ); |
| returns n previously unused texture object names in textures. These |
| names are marked as used, for the purposes of GenTextures only, but |
| they acquire texture state only when they are first bound, just as if |
| they were unused. |
| |
| The texture object name space, including the initial texture |
| object, is shared among all texture units. A texture object may be |
| bound to more than one texture unit simultaneously. After a texture |
| object is bound, any GL operations on that target object affect any |
| other texture units to which the same texture object is bound. |
| |
| Texture binding is affected by the setting of the state |
| ACTIVE_TEXTURE. |
| |
| If a texture object is deleted, it is as if all texture units which |
| are bound to that texture object are rebound to texture object zero. |
| |
| Changes to section "3.7.13 Texture Application" of the OpenGL ES 1.1 |
| specification (ignore for OpenGL ES 2.x) |
| |
| - Replace the first sentence of the first paragraph with: |
| |
| "Texturing is enabled or disabled using the generic Enable and |
| Disable commands, with the symbolic constant TEXTURE_2D or |
| TEXTURE_EXTERNAL_OES to enable or disable texturing with the |
| TEXTURE_2D or TEXTURE_EXTERNAL_OES texture target, respectively. If |
| TEXTURE_EXTERNAL_OES is enabled it takes precedence over TEXTURE_2D, |
| TEXTURE_CUBE_MAP_OES, TEXTURE_RECTANGLE_ARB, and |
| TEXTURE_RECTANGLE_NV." |
| |
| Changes to section "3.8.2 Shader Execution" of the OpenGL ES 2.0 |
| specification (ignore for OpenGL ES 1.x) |
| |
| - Add to the end of the last paragraph of the subsection "Texture Access" |
| |
| "The REQUIRED_TEXTURE_IMAGE_UNITS_OES parameter can change based on the |
| number of external textures which are currently bound (see section |
| 3.7.14)." |
| |
| Changes to section "6.1.3 Enumerated Queries" of the OpenGL ES 1.1 specification |
| |
| - Change: |
| "...TEXTURE_2D..." |
| to |
| "...TEXTURE_2D or TEXTURE_EXTERNAL..." |
| in the last paragraph. |
| |
| Changes to section "6.1.3 Enumerated Queries" of the OpenGL ES 2.0 specification |
| |
| - Change: |
| "...TEXTURE_2D or TEXTURE_CUBE_MAP..." |
| to |
| "...TEXTURE_2D, TEXTURE_CUBE_MAP, or TEXTURE_EXTERNAL..." |
| in the second paragraph. |
| |
| |
| Changes to section "6.2 State Tables" of the OpenGL ES 1.1 specification |
| |
| - Add to "Table 6.13 Textures (state per texture unit and binding point)" |
| |
| +-------------------+-------+-------------+-------+------------------+ |
| | TEXTURE_BINDING_- | 8*xZ+ | GetIntegerv | 0 | Texture object | |
| | EXTERNAL_OES | | | | bound to | |
| | | | | | TEXTURE_- | |
| | | | | | EXTERNAL_OES | |
| +-------------------+-------+-------------+-------+------------------+ |
| | TEXTURE_- | 2*xB | IsEnabled | False | True if external | |
| | EXTERNAL_OES | | | | texturing is | |
| | | | | | enabled | |
| +-------------------+-------+-------------+---+----------------------+ |
| |
| - Add to "Table 6.14 Textures (state per texture object)" |
| |
| +--------------------+-------+-----------------+---+----------------+ |
| | REQUIRED_TEXTURE_- | n*xZ3 | GetTexParameter | 1 | Number of | |
| | IMAGE_UNITS_OES | | | | texture image | |
| | | | | | units required | |
| | | | | | by texture | |
| +--------------------+-------+-----------------+---+----------------+ |
| |
| Changes to section "6.2 State Tables" of the OpenGL ES 2.0 specification |
| |
| - Add to "Table 6.7 Textures (state per texture unit and binding point)" |
| |
| +-------------------+-------+-------------+-------+------------------+ |
| | TEXTURE_BINDING_- | 8*xZ+ | GetIntegerv | 0 | Texture object | |
| | EXTERNAL_OES | | | | bound to | |
| | | | | | TEXTURE_- | |
| | | | | | EXTERNAL_OES | |
| +-------------------+-------+-------------+-------+------------------+ |
| |
| - Add to "Table 6.8 Textures (state per texture object)" |
| |
| +--------------------+-------+-----------------+---+----------------+ |
| | REQUIRED_TEXTURE_- | n*xZ3 | GetTexParameter | 1 | Number of | |
| | IMAGE_UNITS_OES | | | | texture image | |
| | | | | | units required | |
| | | | | | by texture | |
| +--------------------+-------+-----------------+---+----------------+ |
| |
| Changes to section 3.7 of the OpenGL ES Shading Language specification |
| |
| - Add to the list of keywords: |
| |
| "samplerExternalOES" |
| |
| Changes to section 4.1 of the OpenGL ES Shading Language specification |
| |
| - Add to the list of basic types: |
| |
| "samplerExternalOES a handle for accessing an external texture" |
| |
| Changes to section 4.5.3 of the OpenGL ES Shading Language specification |
| |
| - Add to the list of "vertex language has the following predeclared |
| globally scoped default precision statements:" |
| |
| "precision lowp samplerExternalOES;" |
| |
| - Add to the list of "fragment language has the following predeclared |
| globally scoped default precision statements:" |
| |
| "precision lowp samplerExternalOES;" |
| |
| Changes to section 8.7 of the OpenGL ES Shading Language specification |
| |
| - Add to the table the following sampler functions: |
| |
| "vec4 texture2D( |
| samplerExternalOES sampler, |
| vec2 coord) |
| vec4 texture2DProj( |
| samplerExternalOES sampler, |
| vec3 coord) |
| vec4 texture2DProj( |
| samplerExternalOES sampler, |
| vec4 coord)" |
| |
| |
| Changes to section 9 of the OpenGL ES Shading Language specification |
| |
| - Add to token list: |
| |
| "SAMPLEREXTERNAL" |
| |
| - Add following "type_specifier_no_prec:" |
| |
| "SAMPLEREXTERNAL" |
| |
| Changes to section "A.7 Counting of Varyings and Uniforms" of the OpenGL ES |
| Shading Language specification |
| |
| - Change the first sentence of the last paragraph to |
| |
| "Part of the storage may be reserved by an implementation for its own |
| use e.g. for computation of transcendental functions or conversion of |
| external textures." |
| |
| |
| Issues |
| |
| 1. What happens when GenerateMipmaps() is called with <target> set to |
| TEXTURE_EXTERNAL_OES? |
| |
| Possible options: |
| |
| A) Fail (INVALID_ENUM) |
| B) Generate the mipmaps and copy them into the TEXTURE_2D target. |
| |
| Option B could be useful and should not be difficult to implement. |
| What happens when the texture is NPOT and GenerateMipmaps() is called? |
| |
| Ben Bowman and David Garcia have indicated they prefer A. No other |
| strong opinions yet. |
| |
| RESOLVED: A (fail) |
| |
| 2. Should the wrap mode of an external texture be allowed to be anything |
| other than CLAMP_TO_EDGE? |
| |
| RESOLVED: no |
| |
| 3. What about portability problems introduced by allowing implementation- |
| dependent failures? |
| |
| This is the same issue described in Issue 14 of the |
| EGL_OES_image specification. Like the resolution for that issue, |
| this specification should include some minimum requirements, but |
| leave the larger portability problem unresolved at the moment. |
| |
| RESOLVED: This and other (EGL_KHR_image_uses and EGL_KHR_il_image) |
| extensions attempt to minimize this problem by allowing EGL to pick |
| EGLImage attributes which will work in various situations. However it |
| is not possible to guarantee that every usecase will work on every |
| platform. |
| |
| 4. Should EGLImageTargetTexture2DOES result in undefined pixel data, |
| as with calls to eglCreateImageOES? |
| |
| See also issue 4 of GL_OES_EGL_image |
| |
| Comment from Aske: |
| In the description for EGLImageTargetTexture2DOES, it says: "As a |
| result of this operation all pixel data in <image> will become |
| undefined." Why is this? I would imagine one would want to take an |
| existing EGL image containing image data and bind it as an external |
| texture, possibly multiple times, to use it for rendering. I have read |
| through issue 4 of OES_EGL_image, and it seems the concern here is |
| what happens when the image is (potentially) modified from OpenGL ES. |
| Since external images cannot be modified from OpenGL ES, I would guess |
| the same issues do not apply here. |
| |
| Comment from Acorn: |
| Another potential issue is that the memory for the EGLImage may |
| have to be reallocated in order to be compatible with GLES (e.g. GLES |
| may have more strict alignment or other requirements). However, the |
| implementation can fail (or do a copy) if this is the case. If the |
| EGL_KHR_image_uses extension is used to specify that the EGLImage will |
| be used as a GLES external texture then this should not be an issue |
| because EGL will be able to allocate the memory correctly in the first |
| place. |
| |
| RESOLVED: pixel data will not become undefined when |
| EGLImageTargetTexture2DOES() is used with an external texture target. |
| |
| 5. What happens if the texture is bound while the associated EGLImage is |
| being modified. |
| |
| Some implementations may need to color convert the data |
| after it has been generated. A solution to this is to state that the |
| texels become undefined if the external texture is bound while the |
| underlying texels are modified. This way any color conversion can be |
| done (e.g. to a second buffer) when the texture is bound. |
| |
| Options: |
| A) require the texture be unbound while the EGLImage is being modified |
| B) Require the texture to be bound (or re-bound if already bound) |
| between modification and use (i.e. after modification and before |
| used as a texture). |
| C) No requirement. |
| |
| RESOLVED: B |
| |
| 6. How can current generation hardware support planar YUV EGLImage formats? |
| |
| GLES 2.0 hardware can perform color conversion by inserting |
| extra instructions into the shader program. However, planar textures |
| require 2 or 3 surfaces to be read in order to sample a single texture. |
| One solution is to increase the number of texture image units required |
| by a texture object which is associated with such an EGLImage. |
| |
| RESOLVED: allow the implementation to set the number of texture |
| image units required by each texture object. Allow the app to query |
| this with REQUIRED_TEXTURE_IMAGE_UNITS_OES. Have drawing commands |
| fail (INVALID_OPERATION) when the number of texture image units |
| required by all enabled/referenced texture units exceeds the |
| implementation limit (which can be queried with |
| MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, and |
| MAX_TEXTURE_IMAGE_UNITS) |
| |
| See also issue 10. |
| |
| 7. Should there be new texture sampling functions for samplerExternalOES |
| or is it OK to use the existing 2D sampler functions. |
| |
| RESOLVED: Use existing 2D sampler functions. |
| |
| 8. If an EGLImage associated with an external texture does not contain an |
| alpha channel, should the alpha be 1 or undefined. |
| |
| From an app point of view, 1 probably makes more sense. |
| However, if the texture is in a RGBA format and there is garbage in |
| the A channel, it may be difficult for implementations to return 1. |
| An implementation may have to recompile the shader to force the alpha |
| channel to 1. |
| |
| RESOLVED: alpha is defined to be 1 in this case. |
| |
| 9. How should the color conversion be described. |
| |
| Options: |
| |
| A) State that the color values are transformed to a linear colorspace |
| and represented as RGB values in that space. This may be difficult |
| for implementations since it may require nonlinear transformations |
| (e.g. gamma decoding). It is also problematic because usually many |
| more bits are required to represent a value in a linear colorspace |
| than in a gamma encoded colorspace. |
| |
| B) State that the color is transformed to RGB but in the same |
| colorspace as the source image (i.e. no gamma encode or decode). |
| |
| RESOLVED: Option B. |
| |
| 10. How does the implementation indicate which texture samplers and/or |
| texture units are not available when one or more external textures are |
| bound. |
| |
| See discussion on GLES email list around Feb 23 with |
| subject "RE: [OpenGL-ES] IL/ES interaction: YUV texture extension |
| proposal" |
| |
| Proposals: |
| |
| A) The MAX_COMBINED_TEXTURE_IMAGE_UNITS, |
| MAX_VERTEX_TEXTURE_IMAGE_UNITS, and MAX_TEXTURE_IMAGE_UNITS parameters |
| change to reflect the current state. |
| |
| B) New queries AVAILABLE_COMBINED_TEXTURE_IMAGE_UNITS, |
| AVAILABLE_VERTEX_TEXTURE_IMAGE_UNITS, and |
| AVAILABLE_TEXTURE_IMAGE_UNITS indicate current state, while |
| MAX_COMBINED_TEXTURE_IMAGE_UNITS, MAX_VERTEX_TEXTURE_IMAGE_UNITS, and |
| MAX_TEXTURE_IMAGE_UNITS remain constant and indicate the state when no |
| external textures are bound. |
| |
| C) Query for number of required texture image units per texture |
| object. Draw calls fail with INVALID_OPERATION if the current |
| requirements for texture image units exceeds the number available. |
| |
| RESOLVED: C |
| |
| 11. What happens when glUniform1i() sets a sampler to a value that is |
| larger than the number of available texture units? |
| |
| NOTE: This issue no longer affects this extension. See issue 10 for |
| different issue related to texture *image* units. |
| |
| This is really a GLES2 spec issue. See |
| khronos bug 3702 |
| https://cvs.khronos.org/bugzilla/show_bug.cgi?id=3702 |
| http://www.khronos.org/members/login/list_archives/arb-glsl/ |
| 0705/msg00010.html |
| http://www.khronos.org/members/login/list_archives/opengl_es/ |
| 0902/msg00148.html |
| |
| RESOLVED: The issue is not resolved, but it no longer applies |
| directly to this extension. Further discussion should be in bug 3702. |
| |
| 12. What happens at draw time when the current state requires more texture |
| units than the implementation can support? |
| |
| RESOLVED: The precedent, from (desktop) OpenGL, is to fail in |
| glValidate, and to fail in any draw call with an INVALID_OPERATION |
| error. Behavior described in this extension will match that |
| precedent. |
| |
| 13. How can this be conformance tested? |
| |
| In the native code, add a function which takes as a |
| parameter an array of pixels. The function returns an EGLImage which |
| contains the pixels in some unspecified format. A test can call this |
| function, call glEGLImageTargetTexture2DOES() to associate it with an |
| external texture, and render using this texture, and read back the |
| framebuffer to confirm that the result is the expected result. |
| |
| Note1: since the format is unknown and unknowable, possibly only the |
| high bit of each component (RGB) should be tested. It may be |
| sufficient to pass a single pixel (or single bit for each of R, G, an |
| B) and then create the EGLImage with every pixel in the image set to |
| that same value. |
| |
| Note2: It might be a good idea to have an extra parameter, int index, |
| which allows the function to be implemented several different ways. |
| The test could be run several times, with index set to 0, 1, 2, ... |
| until the function returns EGL_NO_IMAGE. This way the function could |
| generate EGLImages with various formats. For example when index is 0 |
| it could call OMX IL to generate a YUV planar EGLImage, when index is |
| 1 it could call OMX AL to generate a YUV interleaved EGLImage, and |
| when index is 2 it could call into VG to generate an RGB EGLImage. |
| The meaning of each index would be up to the implementation. A simple |
| implementation might return an EGLImage when index=0 and return |
| EGL_NO_IMAGE otherwise. |
| |
| Additional suggestion from Jon Leech: |
| The suggested conformance test in issue 13 is intentionally so vague |
| on precision (1 bit/component) that the conversion language seems even |
| less meaningful. The RGB bits that come out of texture sampling would |
| need have almost no relationship to what went in. ISTM the supplier of |
| the EGLImage knows the precision of it, and that information could be |
| provided to the test to put on tighter constraints. |
| |
| RESOLVED: As described above. |
| |
| 14. Can the number of uniforms required by a shader change when switching |
| from one external texture to another, and therefore cause the shader |
| to fail? For example, imagine a program does this: |
| glLinkProgram(prog); // successful link |
| sampler = glGetUniformLocation(prog, "myExtSampler"); |
| glUniform1i(sampler, 1); |
| glActiveTexture(GL_TEXTURE1); |
| glBindTexture(GL_TEXTURE_EXTERNAL, myTex1_rgb); |
| glDrawArrays(); // draw successfully |
| |
| glBindTexture(GL_TEXTURE_EXTERNAL, myTex2_yuv); |
| glDrawArrays(); // Can this fail??? |
| Is it acceptable for an implementation to fail the second |
| glDrawArrays() call because myTex2_yuv is a yuv image and requires |
| more uniforms to implement a color conversion matrix than myTex1_rgb |
| which is an rgb image and does not require any conversion matrix? |
| |
| Note that this situation will only occur on implementation which will |
| recompile the shader based on the color conversion required. |
| |
| Options: |
| |
| A) No, the implementation is not allowed to fail. When the program is |
| linked the implementation must verify that there are enough uniforms |
| to implement the program for any flavor of external texture. If the |
| implementation does not provide enough uniforms for the program to |
| work with any external texture that the implementation supports, then |
| the implementation must fail at link time. |
| |
| B) Yes, the implementation may fail in glDrawArrays or glDrawElements |
| if the number of uniforms required by the program exceeds those |
| available. This means that a call to glUniform1i() or glBindTexture() |
| can cause a shader program that used to work to stop working. (Note |
| that this is possible anyway since the new external texture may use |
| more texture image units than the old external texture (independent of |
| the number of uniforms). But that can be detected by the application |
| by querying REQUIRED_TEXTURE_IMAGE_UNITS_OES) |
| |
| RESOLVED: choice B. |
| |
| 15. How should filtering of non-RGB formats be specified. |
| |
| Options: |
| |
| A) filtering occurs before transformation to RGB. |
| B) filtering occurs after transformation to RGB. |
| C) undefined (up to the implementation) |
| |
| RESOLVED: C |
| |
| Dependencies on EGL_OES_image_base and EGL 1.1 |
| |
| If either EGL 1.1 or the EGL_OES_image extension is not supported, all |
| discussion of EGLImages should be ignored, and any calls to |
| EGLImageTargetTexture2DOES should generate the error INVALID_OPERATION. |
| |
| Dependencies on GL_OES_EGL_image |
| |
| If GL_OES_EGL_image is supported then change the text in both extensions |
| to allow either TEXTURE_2D or TEXTURE_EXTERNAL_OES to be passed as the |
| <target> parameter to EGLImageTargetTexture2DOES(). When <target> is |
| TEXTURE_2D, behavior of EGLImageTargetTexture2DOES() is as described in |
| the GL_OES_EGL_image spec. When <target> is TEXTURE_EXTERNAL_OES, |
| behavior of EGLImageTargetTexture2DOES() is as described in this spec. |
| |
| Revision History |
| |
| #25 - (April 6, 2018) H1Gdev |
| Fix typo. |
| #24 - (April 23, 2015) Jon Leech) |
| - Fix typo EGLImageTargetTexImage2DOES -> EGLImageTargetTexture2DOES |
| (Bug 8114). Improve description of supported queries for new |
| tokens (Bug 8118). |
| #23 - (July 19, 2012) Acorn Pooley |
| - fix extension name from OES_EGL_image_external to |
| GL_OES_EGL_image_external |
| #22 - (Dec 17, 2010) Acorn Pooley |
| status to ratified. |
| #21 - (Sept. 29, 2010) Maurice Ribble |
| Update token numbers and updated status to approved. |
| #20 - (April 2, 2009) Acorn Pooley |
| Rename GL_OES_egl_image_external to GL_OES_EGL_image_external to be |
| consistant with GL_OES_EGL_image. |
| #19 - (March 31, 2009) Acorn Pooley |
| Minor fixes |
| #18 - (March 30, 2009) Acorn Pooley |
| Fix inconsistancy |
| #17 - (March 25, 2009) Acorn Pooley |
| Resolved issue 4 (and some others) |
| #16 - (March 16, 2009) Acorn Pooley |
| Augment issue 13 |
| #15 - (March 13, 2009) Acorn Pooley |
| fix dependancy section |
| resolve issue 14 and fix text |
| #14 - (March 9, 2009) Acorn Pooley |
| Fix colorspace comments. Issue 9 is resolved. |
| #13 - (March 6, 2009) Acorn Pooley |
| Mark issue 6, 10, and 11 resolved. |
| Add issue 15. |
| #12 - (March 4, 2009) Acorn Pooley |
| Fix wording of uniform stuff. |
| #11 - (March 4, 2009) Acorn Pooley |
| Add issues 13, 14. |
| Add comments about extra uniforms required by external texture |
| samplers. |
| Allow external textures to work with default object 0. |
| Correct colorspace language. |
| #10 - (March 3, 2009) Acorn Pooley |
| Remove stale reference to MAX_TEXTURE_IMAGE_UNITS. Add fix to OpenGL |
| ES 2.0 section 2.10.5 (from bruce). Add contributors. Clarify |
| "texture unit" vs "texture image unit". Fix typos. |
| #9 - (February 26, 2009) Acorn Pooley |
| Clarify sync further. Add issue 12. Change "too many texture units" |
| behavior. |
| #8 - (February 26, 2009) Acorn Pooley |
| Clarify sync requirements (i.e. that EGLImage does not do sync) |
| #7 - (February 25, 2009) Acorn Pooley |
| Relax binding requirement - see issue 5 |
| #6 - (February 25, 2009) Acorn Pooley |
| Add TEXTURE_BINDING_EXTERNAL_OES. Add texture state notes. Modify |
| colorspace conversion to be a linear function. |
| #5 - (February 24, 2009) Acorn Pooley |
| Disable GenerateMipmaps. Add issues 10 & 11. |
| #4 - (February 23, 2009) Acorn Pooley |
| Modify the "Texture Parameters" section in ES 1 and 2 specs |
| #3 - (February 20, 2009) Acorn Pooley |
| Clarify the reduction in number of texture units. |
| #2 - (February 20, 2009) Acorn Pooley |
| Fix some errors. replace textureExternal* sampler functions with |
| existing sampler2D* functions. Add issue 7,8,9. Fix spelling. |
| #1 - (February 9, 2009) Original draft |
