OES_EGL_image_external_essl3

GL_OES_EGL_image_external_essl3

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.

Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com)

Copyright (c) 2014-2015 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

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

Complete.
Approved by the OpenGL ES Working Group.
Ratified by the Khronos Board of Promoters on January 23, 2015.

January 29, 2016 (version 10)

OpenGL ES Extension #220

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.

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.

Please see the EGL_OES_image_base specification for a list of terms
used by this specification.

 * New sampler type allowed by the OpenGL ES Shading Language when
 *      #extension GL_OES_EGL_image_external_essl3
 * is used.
 */
samplerExternalOES

None.

None.

- 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."

    "It is an INVALID_OPERATION error to set the TEXTURE_BASE_LEVEL
     to a value other than zero."

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  -  -

- Add to the list of keywords:

    "samplerExternalOES"

- 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"

- Add the following paragraph:

  "All languages have the following predeclared globally scoped default
   precision statements:

    precision lowp samplerExternalOES;"

- 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)"

- Add to token list:

    "SAMPLEREXTERNAL"

- Add following "type_specifier_no_array:"

    "SAMPLEREXTERNAL"

- 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.

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.

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."

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.)

#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.