xref: /third_party/openGLES/extensions/ARB/ARB_ES3_2_compatibility.txt

Name

    ARB_ES3_2_compatibility

Name Strings

    GL_ARB_ES3_2_compatibility

Contact

    Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)

Contributors

    Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com)

    and contributors to the OpenGL ES 3.2 specification

Notice

    Copyright (c) 2015 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 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

    Complete. Approved by the ARB on June 26, 2015.
    Ratified by the Khronos Board of Promoters on August 7, 2015.

Version

    Last Modified Date:         June 25, 2015
    Revision:                   8

Number

    ARB Extension #177

Dependencies

    OpenGL 4.5, ARB_ES2_compatibility, ARB_ES3_compatibility and
    ARB_ES3_1_compatibility are required.

    KHR_blend_equation_advanced and KHR_texture_compression_astc_ldr are
    recommended to support the full OpenGL ES 3.2 feature set, but not
    required for this extension.

    This extension is written against The OpenGL 4.5 (Compatibility Profile)
    specification.

Overview

    This extension adds support for features of OpenGL ES 3.2 that are
    missing from OpenGL 4.5. Enabling these features will ease the process
    of porting applications from OpenGL ES 3.2 to OpenGL.

    In particular this adds the following features:

    - Bounding box used to optimization tessellation processing
      (OES_primitive_bounding_box)
    - query for MULTISAMPLE_LINE_WIDTH_RANGE_ARB
    - support for the OpenGL ES 3.20 shading language

    For full OpenGL ES 3.2 compatibility the implementation must support
    KHR_blend_equation_advanced and KHR_texture_compression_astc_ldr. Those
    features are not defined in this extension spec since they are already
    defined at the KHR level.

New Procedures and Functions

    void PrimitiveBoundingBoxARB(float minX, float minY, float minZ, float minW,
                                 float maxX, float maxY, float maxZ, float maxW);

New Tokens

    Accepted by the <pname> parameter of GetBooleanv, GetFloatv, GetIntegerv,
    and GetInteger64v:

        PRIMITIVE_BOUNDING_BOX_ARB                          0x92BE
        MULTISAMPLE_LINE_WIDTH_RANGE_ARB                    0x9381
        MULTISAMPLE_LINE_WIDTH_GRANULARITY_ARB              0x9382

Additions to Chapter 11 of the 4.5 Specification (Programmable Vertex
Processing)

-- OpenGL: Section 11.2, Tessellation

    Modify section 11.2.1.2.3, "Tessellation Control Shader Outputs":

    In the second paragraph, add gl_BoundingBox[] to the list of built-in
    per-patch output arrays:

    Tessellation shaders additionally have three built-in per-patch output
    arrays, gl_TessLevelOuter[], gl_TessLevelInner[], and gl_BoundingBox[].
    These arrays ... as discussed in the following section. gl_BoundingBox[]
    is an array of two vec4 values that should be used instead of the value of
    PRIMITIVE_BOUNDING_BOX_ARB as the primitive bounding box (see Section
    14.1pbb) for primitives generated from the output patch.

    Modify the sixth paragraph of the section to state that gl_BoundingBox[]
    counts against the per-patch limit:

    ... The built-in outputs gl_TessLevelOuter[] and gl_TessLevelInner[] are not
    counted against the per-patch limit. The built-in output
    gl_BoundingBox[], if statically assigned by the shader, is counted
    against the per-patch limit. The total number of components...


    Modify section 11.2.3.3, "Tessellation Evaluation Shader Inputs":

    Insert a new paragraph after the list of special input variables in
    paragraph 2:

    The special tessellation control shader output gl_BoundingBox[] is
    consumed by the tessellation primitive generator, and is not available as an
    input to the tessellation evaluation shader.


    Add new section 14.1pbb following section 14.1, "Discarding Primitives
    Before Rasterization" on p. 525:

    14.1pbb, Primitive Bounding Box

    Implementations may be able to optimize performance if the application
    provides bounds of primitives that will be generated by the tessellation
    primitive generator or the geometry shader prior to executing those stages.
    If the provided bounds are incorrect and primitives extend beyond them, the
    rasterizer may or may not generate fragments for the portions of primitives
    outside the bounds.

    The primitive bounding box is specified using

        void PrimitiveBoundingBoxARB(float minX, float minY, float minZ, float minW,
                                     float maxX, float maxY, float maxZ, float maxW);

    where <minX>, <minY>, <minZ>, and <minW> specify the minimum clip space
    coordinate of the bounding box and <maxX>, <maxY>, <maxZ>, and <maxW>
    specify the maximum coordinate.

    If tessellation is active, each invocation of the tessellation control
    shader may re-specify the bounding box by writing to the built-in
    gl_BoundingBox[] variable. If the shader statically assigns a value to
    any part of this variable, then gl_BoundingBox[0] is used instead of
    <minX>, <minY>, <minZ>, <minW>, and gl_BoundingBox[1] is used instead of
    <maxX>, <maxY>, <maxZ>, <maxW>.  If the shader contains a static assignment
    to gl_BoundingBox[] and there is an execution path through the shader
    that does not write all components of gl_BoundingBox[], the value of
    unwritten components and corresponding bounding box coordinates is undefined
    for executions of the shader that take that path.

    If the tessellation control shader re-specifies the bounding box, the re-
    specified value is used for primitives generated from the output patch by
    the primitive generator, any primitives emitted by the geometry shader
    invocations for those generated primitives, and any primitives further
    introduced during clipping.

    The bounding box in clip space is composed of 16 vertices formed by all
    combinations of the minimum and maximum values for each dimension. This
    bounding box is clipped against w_c > 0, and projected to three dimensions
    by dividing x_c, y_c, and z_c by w_c for each vertex. The viewport transform
    is then applied to each vertex to produce a three-dimensional bounding
    volume in window coordinates.

    The window space bounding volume is expanded in the X and Y dimensions to
    accomodate the rasterization rules for the primitive type, and to fall on
    fragment boundaries:
        min_wc' = floor(min_wc - size/2.0)
        max_wc' = ceil(max_wc + size/2.0)
    where the min_wc rule is used for x and y window coordinates of bounding
    volume vertices formed from minX and minY respectively, and the max_wc rule
    is used for x and y window coordinates of bounding volume vertices formed
    from maxX and maxY respectively. For point primitives, size is the per-
    primitive point size after clamping to the implementation-defined maximum
    point size as described in section 13.3. For line primitives, size is the
    line width, after rounding and clamping as described in section 13.4.2.1.
    For triangle primitives, size is zero.

    During rasterization, the rasterizer will generate fragments with
    window coordinates inside the windows space bounding volume, but may or may
    not generate fragments with window coordinates outside the bounding volume.


    Modify section 14.5.4, "Line Multisample Rasterization":

    Replace the last paragraph with:

    Line width range and number of gradations are equivalent to those supported
    for antialiased lines. The supported [min, max] range of multisampled line
    widths, and the width of evenly-space graduations within that range are
    implementation-dependent and may be queried as
    MULTISAMPLE_LINE_WIDTH_RANGE_ARB and MULTISAMPLE_LINE_WIDTH_GRANULARITY_ARB
    respectively, as described in table 23.54. If, for instance the width range
    is from 0.1 to 2.0 and the gradation width is 0.1 then the widths 0.1, 0.2,
    ..., 1.9, 2.0 are supported.  Additional line widths may also be supported;
    there is no requirement that these widths be evenly space. If an
    unsupported width is requested, the nearest supported width is used
    instead.

Additions to the OpenGL Shading Language

    Including the following line in a shader can be used to control the
    language features described in this extension:

        #extension GL_ARB_ES3_2_compatibility : <behavior>

    where <behavior> is as specified in section 3.3.

    New preprocessor #defines are added to the OpenGL Shading Language:

        #define GL_ARB_ES3_2_compatibility 1


Additions to Chapter 3 of the OpenGL Shading Language 4.50.5 Specification
(Basics)

    Modify the paragraph at the bottom of page 16 in Section 3.3
    (Preprocessor) as follows:

    "... Shaders that specify #version 100 will be treated as targeting
    version 1.00 of the OpenGL ES Shading Language. Shaders that specify
    #version 300 will be treated as targeting version 3.00 of the OpenGL
    ES Shading Language. Shaders that specify #version 310 will be treated
    as targeting version 3.10 of the OpenGL ES Shading Language. Shaders
    that specify #version 320 will be treated as targeting version 3.20
    of the OpenGL ES Shading Language...."

    Modify the 3rd paragraph at the top of p16 as follows:

    A <profile> argument ...
    If version 300, 310 or 320 is specified, the profile argument is not
    optional and must be "es", or a compile-time error results. The Language
    Specification ...


Additions to Chapter 7 of the OpenGL Shading Language 4.50.5 Specification
(Built-in Variables)

    Add a new built-in variable intrinsic declaration after the
    gl_TessLevelOuter and gl_TessLevelInner declarations:

      patch out highp vec4 gl_BoundingBox[2];


Additions to the AGL/GLX/WGL Specifications

    None

Errors

    TBD

New State

    Add to state values in Table 23.10, Transformation State:

                                                  Default
    Get Value                  Type  Get Command  Value        Description       Sec.
    -------------------------- ----  -----------  ------------ ----------------- --------
    PRIMITIVE_BOUNDING_BOX_ARB 8xR   GetFloatv    -1,-1,-1, 1, Default primitive 14.1pbb
                                                   1, 1, 1, 1  bounding box

    Add to state values in Table 23.54, Implementation Dependent Values:

                                                        Minimum
    Get Value                              Type  Get Command  Value    Description            Sec.
    --------------------------------       ----  -----------  -------  -------------------    --------
    MULTISAMPLE_LINE_WIDTH_RANGE_ARB       2xR+  GetFloatv    1,1      Range (lo to hi) of    14.5.4
                                                                       multisampled line widths
    MULTISAMPLE_LINE_WIDTH_GRANULARITY_ARB R+    GetFloatv    -        Multisampled line      14.5.4
                                                                       width granularity


Issues

    1) With this extension, is OpenGL 4.5 a complete superset of OpenGL ES 3.2?

    RESOLVED: No. This extension does not include KHR_blend_equation_advanced or
    KHR_texture_compression_astc_ldr even though these are part of OpenGL ES 3.2.
    These continue to be optional extensions for OpenGL. Otherwise OpenGL 4.5
    plus this extension is a superset of OpenGL ES 3.2.

Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------------

    1     04/19/15  pdaniell  Initial draft with incomplete text.

    2     04/29/15  pdaniell  Remove EXT_texture_sRGB_decode which is no longer
                              in OpenGL ES 3.2.

    3     05/07/15  dkoch     Add MULTISAMPLED_LINE_WIDTH_RANGE_ARB query
                              (Bug 13828).
                              Remove ASTC interaction with SRGB_DECODE.

    4     05/07/15  Jon Leech Assign enum for MULTISAMPLED_LINE_WIDTH_RANGE_ARB.

    5     05/21/15  pdaniell  Allow KHR_blend_equation_advanced and
                              KHR_texture_compression_astc_ldr to be optional
                              for this extension.

    6     06/18/15  pdaniell  Fix resolution of issue (1).

    7     06/24/15  Jon Leech Correct MULTISAMPLE_LINE_WIDTH_RANGE_ARB
                              spelling (drop 'D')

    8     06/25/15  dkoch     Add MULTISAMPLE_LINE_WIDTH_GRANULARITY_ARB
                              query per bug 13828.