blob: 13593b3b6fa90a0bc6ce91dd80a3373c6bec30bc [file] [log] [blame]
Name
OES_EGL_image_external_essl3
Name Strings
GL_OES_EGL_image_external_essl3
Contributors
Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com)
James Helferty, NVIDIA (jhelferty 'at' nvidia.com)
Mark Callow, ArtSpark Holdings Inc (callow.mark 'a' artspark.co.jp)
Contributors to GL_OES_EGL_image_external.
Contacts
Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com)
Notice
Copyright (c) 2014-2015 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the OpenGL ES Working Group.
Ratified by the Khronos Board of Promoters on January 23, 2015.
Version
January 29, 2016 (version 10)
Number
OpenGL ES Extension #220
Dependencies
Requires OpenGL ES 3.0 and ESSL 3.0.
Requires EGL 1.2
Requires either the EGL_KHR_image_base or the EGL_KHR_image extension.
Requires OES_EGL_image_external.
This extension is written based on the wording of the OpenGL ES 3.0.3
specification, the OpenGL ES Shading Language version 3.0 rev4, and the
OES_EGL_image_external extension.
This extension interacts with OpenGL ES 3.1.
This extension interacts with GL_EXT_gpu_shader5 and GL_OES_gpu_shader5.
This extension borrows concepts and function names from the
GL_OES_EGL_image and OES_EGL_image_external extensions. This extension
is compatible with GL_OES_EGL_image but does not require it.
Overview
OES_EGL_image_external provides a mechanism for creating EGLImage texture
targets from EGLImages, but only specified language interactions for the
OpenGL ES Shading Language version 1.0. This extension adds support for
versions 3.x of the OpenGL ES Shading Language.
Glossary
Please see the EGL_OES_image_base specification for a list of terms
used by this specification.
New Types
* New sampler type allowed by the OpenGL ES Shading Language when
* #extension GL_OES_EGL_image_external_essl3
* is used.
*/
samplerExternalOES
New Procedures and Functions
None.
New Tokens
None.
Changes to section 3.8.2 ("Sampler Objects") of the OpenGL ES 3.0.3 specification
- Add to the description BindSampler:
"If state is present in a sampler object bound to a texture unit that
would have been rejected by a call to TexParameter* for the texture
bound to that unit, the behavior of the implementation is as if the
texture were incomplete. For example, if TEXTURE_WRAP_S or
TEXTURE_WRAP_T is set to anything but CLAMP_TO_EDGE on the sampler
object bound to a texture unit and the texture bound to that unit is
an external texture, the texture will be considered incomplete.
Sampler object state which does not affect sampling for the type of
texture bound to a texture unit, such as TEXTURE_WRAP_R for an external
texture, does not affect completeness."
Changes to section 3.7.14 ("External Textures") of the OES_EGL_image_external
specification
"It is an INVALID_OPERATION error to set the TEXTURE_BASE_LEVEL
to a value other than zero."
[[Only if OpenGL ES 3.1 is supported]]
Changes to section 8.22 ("Texture Image Loads and Stores") of the
OpenGL ES 3.1 specification
On p. 196 in the errors section for BindImageTexture, replace the
last error with the following:
"An INVALID_OPERATION error is generated if <texture> is neither the
name of an immutable texture object, nor the name of an external
texture object.
Add to table 8.26 "Mapping of image load, store..."
Texture target face/
i j k layer
-------------------------- -- -- -- -----
TEXTURE_EXTERNAL_OES x y - -
Changes to section 3.7 ("Keywords") of the OpenGL ES Shading Language
specification
- Add to the list of keywords:
"samplerExternalOES"
Changes to section 4.1 ("Basic Types") of the OpenGL ES Shading Language
specification
- Add to the list of Floating Point Sampler Types (opaque):
"samplerExternalOES a handle for accessing an external 2D texture"
- Add a paragraph at the end of the section:
"The samplerExternalOES type is optional and must be enabled by
#extension GL_OES_EGL_image_external_essl3 : enable"
Changes to section 4.5.4 ("Default Precision Qualifiers") of the OpenGL ES
Shading Language specification
- Add the following paragraph:
"All languages have the following predeclared globally scoped default
precision statements:
precision lowp samplerExternalOES;"
Changes to section 8.8 ("Texture Lookup Functions") of the OpenGL ES Shading
Language specification
- Add to the table the following sampler functions:
"highp ivec2 textureSize(samplerExternalOES sampler, int lod)
vec4 texture(samplerExternalOES sampler, vec2 P [, float bias] )
vec4 textureProj(samplerExternalOES sampler, vec3 P [, float bias] )
vec4 textureProj(samplerExternalOES sampler, vec4 P [, float bias])
vec4 texelFetch(samplerExternalOES sampler, ivec2 P, int lod)"
Changes to section 9 ("Shading Language Grammar") of the OpenGL ES Shading
Language specification
- Add to token list:
"SAMPLEREXTERNAL"
- Add following "type_specifier_no_array:"
"SAMPLEREXTERNAL"
Changes to section 11 ("Counting of Inputs and Outputs") of the OpenGL ES
Shading Language specification
- Add a paragraph at the end
"Part of the storage may be reserved by an implementation for its own
use e.g. for conversion of external textures. This reduces the number
of uniforms available to the shader. The size of this reduction is
undefined but should be minimized.
Dependencies on OpenGL ES 3.1 and ESSL 3.10
All texture built-in functions added in ESSL 3.10 are excluded from this
extension per Issue 4. This extension is expected to work without
modification for ESSL 3.10.
If OpenGL ES 3.1 is not supported, ignore changes to section 8.22 since
image load store is not supported.
Interactions with EXT_gpu_shader5 and OES_gpu_shader5
If either of these extensions is supported, add the following paragraph
to the end of section 4.1.7.1 ("Samplers") of the ESSL 3.10 specification:
"When aggregated into arrays within a shader, external samplers can
only be indexed with a constant integral expression. All other sampler
types can only be indexed with a dynamically uniform integral
expression, otherwise results are undefined."
Issues
1. Why is this functionality not added as an interaction to the
OES_EGL_image_external extension as in interaction with ESSL 3.x?
RESOLVED.
Since the built-in texture functions in ESSL were modified going from
ESSL 1.0 to 3.x, the original extension does not trivially apply to
ESSL 3.x.
There are also many shipping implementations of OES_EGL_image_external
extension that have chosen to not extend support to ESSL 3.x. If we
were to amend the original extension, there would be no way for
applications to determine whether a particular implementation supported
the language extension for ESSL 3.x or not.
2. Should this extension require OES_EGL_image_external?
RESOLVED: Yes.
This extension currently depends on OES_EGL_image_external to define the
API extensions. This also implies that an implementation cannot choose
to support this extension for ESSL 3.x only.
3. What should this extension be called?
RESOLVED: OES_EGL_image_external_essl3
4. Should built-in functions beyond ESSL1 compatibility be supported in
ESSL 3.x shaders?
RESOLVED: Yes.
It seems useful to add some of these. The ESSL 3.x built-ins that are
only useful for mipmapped textures are excluded since external textures
cannot be mipmapped. The ESSL 3.x built-ins that require offsets are
excluded since it is not clear how these should work with sub-sampled
YUV formats.
Required for ESSL1 feature compatibility:
- texture
- textureProj (two versions)
Also included in this extension:
- textureSize
- texelFetch
Excluded from this extension:
- textureLod
- textureLodOffset
- textureProjLod
- textureProjLodOffset
- textureGrad
- textureGradOffset
- textureProjGrad
- textureProjGradOffset
- textureOffset
- texelFetchOffset
- textureProjOffset
- textureGather [for ESSL 3.10]
- textureGatherOffset [for ESSL 3.10]
5. Should external integer textures be supported in ESSL 3.x shaders?
RESOLVED: No.
The built-in functions added for ESSL1 always return floating point
values, but that's in part because OpenGL ES 2.0 did not support
integer textures. For ESSL 3.x, we could allow the same return values
for external textures as for regular 2D textures. This would require
adding new sampler types, such as samplerExternaliOES and
samplerExternaluOES. Since there is no obvious use-case for external
integer textures these are not added by this extension.
6. What token should be used to enable this extension in ESSL 3.x?
RESOLVED: GL_OES_EGL_image_external_essl3
The alternatives are a) reuse the GL_OES_image_external token (this
should not cause problems since the original extension did not apply
to ESSL 3.x), b) use the name of this extension. Option b) is chosen
since there is no clear benefit to reusing the old name.
7. What is the interaction with separate sampler objects?
RESOLVED: The texture is incomplete if the sampler object state is
not compatible with the sampler state.
The OES_EGL_image_external specifies that the only supported min filter
modes for external textures is LINEAR or NEAREST and that the only
valid s and t wrap mode is CLAMP_TO_EDGE. TexParameter* will generate
errors if these are called while an external texture is bound. In ES3.x
it is possible to attach a sampler object that has any wrap mode and
min filter. In this case, the external texture will be treated as
incomplete if the sampler object state is incompatible with such
textures.
Sampler state that affects completeness of external textures:
- TEXTURE_MIN_FILTER
- TEXTURE_WRAP_S
- TEXTURE_WRAP_T
Sampler state that has no additional constraints for external textures:
- TEXTURE_MAG_FILTER
Sampler state that does not affect external textures, and thus have
no impact on completeness or behavior:
- TEXTURE_WRAP_R (3D or 2Darray for external textures)
- TEXTURE_COMPARE_MODE (no shadow sampler for external textures)
- TEXTURE_COMPARE_FUNC (no shadow sampler for external textures)
- TEXTURE_MIN_LOD (no mipmapping for external textures)
- TEXTURE_MAX_LOD (no mipmapping for external textures)
8. What is the interaction with the texture base level?
RESOLVED: The base level must be zero for external textures.
External textures do not support mipmap filtering. It is consistent
with the behavior for 2D multisampled textures in ES3.1 to make it an
error to specify a base level other than zero for external textures.
This error is not specified in GL_OES_EGL_image_external so adding an
error may break existing applications using that extension (in ESSL 1.x)
in combination with OpenGL ES 3.x if they set the base level to any
other value.
9. What formats are supported?
This is implementation defined. GL_OES_EGL_image_external does not
require any specific formats, and this extension does not change
that. On a given implementation, it is expected that the same set
of formats is supported in all shader stages.
10. Should image / load store be supported? And, if so, how?
RESOLVED: Yes, in a limited form.
Allowing image / load store on external textures enables compute
shaders to write to these textures.
A limited set of use-cases is enabled by making glBindImageTexture
accept external textures. Shaders can access such external textures
using the existing <image2D> sampler type.
Since the image format must be specified by the shader, no additional
format conversion is done for external textures accessed via image
load/store. This implies that the shader author must know the format of
the external texture in order to do useful work. Also, only the image
formats already supported by image load store are available (i.e, there
is no automatic conversion to, for example, YUV formats.)
Revision History
#10 - (Jan 29, 2016) Fixed typo in issue 10.
#9 - (Apr 10, 2015) Clarified issue 10. Specified default precision for
samplerExternalOES as lowp for all shader stages.
#8 - (Feb 6, 2015) Fixed typo in return value of textureSize (vec2->ivec2)
#7 - (Oct 15, 2014) Resolved issue 10. Added interaction with EXT_gpu_shader5.
#6 - (Oct 10, 2014) Added issue 10 and its tentative resolution.
#5 - (Sep 25, 2014) Updated resolution of issue 7.
Added issues 8 and 9.
Converted to OES.
#4 - (Sep 24, 2014) Added issue 7 with proposed resolution.
#3 - (Jul 30, 2014) Excluded textureGather from this extension.
#2 - (Jul 30, 2014) Updated based feedback. Tentatively resolved issues.
Added issue 6.
#1 - (Jul 15, 2014) Original draft.