Name

    EXT_clip_cull_distance

Name Strings

    GL_EXT_clip_cull_distance

Contact

    Maurice Ribble, Qualcomm Technologies Inc. (mribble 'at' qti.qualcomm.com)

Contributors
    Kulin Seth, Qualcomm Technologies Inc.
    Sam Holmes, Qualcomm Technologies Inc.
    Jeff Leger, Qualcomm Technologies Inc.
    Daniel Koch, NVIDIA
    Jan-Harald Fredriksen, ARM
    Bill Licea-Kane, Qualcomm Technologies Inc.

Status

    Complete

Version

    Last Modified Date: March 9, 2016
    Revision: 3

Number

    OpenGL ES Extension #257

Dependencies

    This specification is written against the OpenGL ES 3.2 Specification
    (August 10, 2015), and the OpenGL ES 3.2 Shading Language Specification
    (August 6, 2015) but can apply to prior specifications.

    OpenGL ES 3.0 is required.

    This extension interacts with OpenGL ES 3.2.

    This extension interacts with OES_tessellation_shader and
    EXT_tessellation_shader.

    This extension trivially interacts with OES_tessellation_point_size
    and EXT_tessellation_point_size.

    This extension interacts with OES_geometry_shader and
    EXT_geometry_shader.

Overview

    This extension adds support for hardware clip planes and cull
    distances to OpenGL ES. The language for this extension is based
    on the OpenGL 4.5 API Specification (May 28, 2015) and
    ARB_clip_distance.

New Procedures and Functions

    None

New Tokens

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

        MAX_CLIP_DISTANCES_EXT                          0x0D32
        MAX_CULL_DISTANCES_EXT                          0x82F9
        MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT        0x82FA

    Accepted by the <pname> parameters of Enable, Disable and IsEnabled:

        CLIP_DISTANCE0_EXT           0x3000
        CLIP_DISTANCE1_EXT           0x3001
        CLIP_DISTANCE2_EXT           0x3002
        CLIP_DISTANCE3_EXT           0x3003
        CLIP_DISTANCE4_EXT           0x3004
        CLIP_DISTANCE5_EXT           0x3005
        CLIP_DISTANCE6_EXT           0x3006
        CLIP_DISTANCE7_EXT           0x3007

Additions to Chapter 7 of the OpenGL ES 3.2 Specification (Programs and
Shaders)

    Modify Section 7.4.1 "Shader Interface Matching" (p. 97),
    adding the following to the end of the third paragraph (beginning with
    "For program objects containing mutliple shaders,..."):

    "If either shader redeclares the built-in arrays gl_CullDistance[] or
    gl_ClipDistance[] the array must have the same size in both shaders."

Additions to Chapter 11 of the OpenGL ES 3.2 Specification (Programmable
Vertex Processing)

    Modify Section 11.1.3.10, "Shader Outputs" (p. 300),
    adding the following as a new paragraph after the description of
    gl_Position:

    "The built-in output variables gl_ClipDistance and gl_CullDistance
    respectively hold the the clip distance and cull distance used in the
    clipping stage, as described in section 12.4. If clipping is enabled,
    gl_ClipDistance should be written."

    Modify Section 11.2.1.2.2, "Tessellation Control Shader Inputs" (p. 307),
    replacing the last sentence of the first paragraph as follows:

    "The members of each element of the gl_in array are gl_Position,
    gl_CullDistance, and gl_ClipDistance
        [[ If OES_tessellation_point_size or EXT_tessellation_point_size
           are supported: ]]
        and gl_PointSize."

    Modify Section 11.2.1.2.3, "Tessellation Control Shader Outputs" (p. 308),
    replacing the last two sentences of the first paragraph as follows:

    "The members of each element of the gl_out array are gl_Position,
    gl_ClipDistance and gl_CullDistance
        [[ If OES_tessellation_point_size or EXT_tessellation_point_size
           are supported: ]]
        and gl_PointSize,
    and behave identically to equivalently named vertex shader outputs
    (see section 11.1.3)."

    Modify Section 11.2.3.3 "Tessellation Evaluation Shader Inputs" (p. 321),
    replacing the last sentence of the first paragraph as follows:

    "The members of each element of the gl_in array are gl_Position,
    gl_CullDistance, and gl_ClipDistance
        [[ If OES_tessellation_point_size or EXT_tessellation_point_size
           are supported: ]]
        and gl_PointSize."

    Modify Section 11.2.3.4, "Tessellation Evaluation Shader Outputs" (p. 322),
    replacing the first two sentences of the first paragraph as follows:

    "Tessellation evalution shaders have a number of built-in output variables
    used to pass values to equivalent built-in input variagles read by
    subsequent shader stages or to subsequent fixed functionality vertex
    processing pipeline stages.  These variables are gl_Position,
    gl_ClipDistance and gl_CullDistance
        [[ If OES_tessellation_point_size or EXT_tessellation_point_size
           are supported: ]]
        and gl_PointSize,
    and all behave identically to equivalently named vertex shader outputs
    (see section 11.1.3)."

    Modify Section 11.3.4.3, "Geometry Shader Inputs" (p. 327) by adding the
    following two bullet points to the description of the elements of gl_in[]:

    "*  Structure member gl_ClipDistance[] holds the per-vertex array of clip
    distances, as written by the upstream shader to the built-in output variable
    gl_ClipDistance[].

     *  Structure member gl_CullDistance[] holds the per-vertex array of cull
    distances, as written by the upstream shader to the built-in output variable
    gl_CullDistance[]."

    Modify Section 11.3.4.4 "Geometry Shader Outputs" (p. 329), adding the
    following paragraph after the description of gl_Position:

    "The built-in outputs gl_ClipDistance and gl_CullDistance hold the clip
    distance and cull distance, respectively, used in the clipping stage, as
    described in Section 12.4."

Additions to Chapter 12 of the OpenGL ES 3.2 Specification (Fixed-Function
Vertex Post-Processing)

    Modify Section 12.4, "Primitive Clipping" (p. 341),
    replacing the first four paragraphs with the following:

    "Primitives are culled against the cull volume and then clipped to the
    clip volume. In clip coordinates, the view volume is defined by
                        -wc <= xc <= wc
                        -wc <= yc <= wc
                        -zmin <= zc <= wc.

    where zmin is -wc.

    This view volume may be further restricted by as many as <n>
    client-defined halfspaces. <n> is an implementation-dependent maximum that
    must be at least 8, and may be determined by calling GetIntegerv with
    pname MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT.

    The cull volume is the intersection of up to the value of
    MAX_CULL_DISTANCES_EXT client-defined half-spaces (if no client-defined
    cull half-spaces are enabled, culling against the cull volume is skipped).
    The number of enabled cull half-spaces is determined by the explicit or
    implicit size of the built-in array gl_CullDistance in the last shader
    stage before rasterization which has an active program.

    A shader may write a single cull distance for each enabled cull half-space
    to elements of the gl_CullDistance[] array. If the cull distance for any
    enabled cull half-space is negative for all of the vertices of the
    primitive under consideration, the primitive is discarded. Otherwise the
    primitive is clipped against the clip volume as defined below.

    The clip volume is the intersection of up to the value of
    MAX_CLIP_DISTANCES_EXT client-defined half-spaces with the view volume
    (if no client-defined clip half-spaces are enabled, the clip volume is
    the view volume).

    A vertex shader may write a single clip distance for each enabled clip
    halfspace to elements of the gl_ClipDistance[] array. Clip half-space
    <i> is then given by the set of points satisfying the inequality
                    ci(P) >= 0,
    where ci(P) is the value of clip distance <i> at point P. For point
    primitives, ci(P) is simply the clip distance for the vertex in question.
    For line and triangle primitives, per-vertex clip distances are
    interpolated using a weighted mean, with weights derived according to the
    algorithms described in sections 13.6 (Line Segments) and 13.7
    (Polygons).

    Client-defined clip half-spaces are enabled or disabled by calling
    Enable or Disable with target CLIP_DISTANCE<i>_EXT, where <i> is an
    integer between 0 and <n> - 1; specifying a value of <i> enables or
    disables the client-defined clip half-space with index <i>. The
    constants obey CLIP_DISTANCE<i>_EXT = CLIP_DISTANCE0_EXT + <i>.

    If the primitive under consideration is a point, then clipping passes it
    unchanged if it lies withing the clip volume; otherwise it is discarded.

    If the primitive is a line segment, then clipping does nothing to it if
    it lies entirely withing the clip volume, and discards it if it lies
    entirely outside the volume.

    If part of the line segment lies in the volume and part of it lies
    outside, then the line segment is clipped and new vertex coordinates
    are computed for one or both vertices. A clipped line segment endpoint
    lies on both the original line segment and the boundary of the clip
    volume.

    This clipping produces..."

    Add the following text to the end of Section 12.4:

    "Primitives rendered with user-defined half-spaces must satisfy a
    complimentary criterion. Suppose a series of primitives is drawn where
    each vertex <i> has a single specified clip distance <di> (or a number
    of similarly specified clip distances, if multiple half-spaces are
    enabled). Next, suppose that the same series of primitives are drawn
    again with each such clip distance replaced by -<di> (and the GL is
    otherwise in the same state). In this case, primitives must not be
    missing any pixels, nor may any pixels be drawn twice in regions where
    those primitives are cut by the clip planes.

    The state required for clipping is MAX_CLIP_DISTANCES_EXT bits indicating
    which of the client-defined half-spaces are enabled. In the initial state,
    all half-spaces are disabled."

Additions to OpenGL ES Shading Language 3.20 Specification

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

        #extension GL_EXT_clip_cull_distance : <behavior>

    where <behavior> is as described in section 3.4.

    A new preprocessor #define is added to the OpenGL ES Shading Language:

        #define GL_EXT_clip_cull_distance 1

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

    Modify Section 7.1, Vertex Shader Special Variables (p. 119)
    out gl_PerVertex
    {
        ...
        highp float gl_ClipDistance[];
        highp float gl_CullDistance[];

    };

    Similar changes in Geometry, Tessellation Control, Tessellation Evaluation
    language "in gl_PerVertex" and "out gl_PerVertex" structures.

    Modify Section 7.1.5 "Fragment Shader Special Variables" (p. 123)

    in highp float gl_ClipDistance[];
    in highp float gl_CullDistance[];

    The variable gl_ClipDistance provides the mechanism for controlling
    user clipping. The element gl_ClipDistance[i] specifies a clip
    distance for each plane <i>. A distance of 0 means the vertex is on
    the plane, a positive distance means the vertex is inside the clip
    plane, and a negative distance means the point is outside the clip
    plane. The clip distances will be linearly interpolated across the
    primitive and the portion of the primitive with interpolated
    distances less than 0 will be clipped.

    The gl_ClipDistance array is predeclared as unsized and must be
    explicitly sized by the shader either redeclaring it with a size
    or implicitly sized by indexing it only with integral constant
    expressions. This needs to size the array to include all the clip
    planes that are enabled via the OpenGL ES API;
    if the size does not include all enabled planes, results are
    undefined. The size can be at most gl_MaxClipDistances. The
    number of varying components (see gl_MaxVaryingComponents) consumed
    by gl_ClipDistance will match the size of the array, no matter
    how many planes are enabled. The shader must also set all values in
    gl_ClipDistance that have been enabled via the OpenGL ES API,
    or results are undefined. Values written into gl_ClipDistance
    for planes that are not enabled have no effect.

    As an output variable, gl_ClipDistance provides the place for the
    shader to write these distances. As an input in all but the fragment
    language, it reads the values written in the previous shader stage.
    In the fragment language, gl_ClipDistance array contains linearly
    interpolated values for the vertex values written by a shader to
    the gl_ClipDistance vertex output variable. Only elements in this
    array that have clipping enabled will have defined values.

    The variable gl_CullDistance provides a mechanism for controlling
    user culling. The element gl_CullDistance[i] specifies a cull
    distance for plane <i>. A distance of 0 means the vertex is on the
    plane, a positive distance means the vertex is inside the cull
    volume, and a negative distance means the point is outside the
    cull volume. Primitives whose vertices all have a negative clip
    distance for plane <i> will be discarded.

    The gl_CullDistance array is predeclared as unsized and must be
    sized by the shader either redeclaring it with a size or indexing
    it only with integral constant expressions. The size determines
    the number and set of enabled cull distances and can be at most
    gl_MaxCullDistances. The number of varying components
    (see gl_MaxVaryingComponents) consumed by gl_CullDistance will
    match the size of the array. Shaders writing gl_CullDistance must
    write all enabled distances, or culling results are undefined.

    As an output variable, gl_CullDistance provides the place for
    the shader to write these distances. As an input in all but the
    fragment language, it reads the values written in the previous
    shader stage. In the fragment language, gl_CullDistance array
    contains linearly interpolated values for the vertex values
    written by a shader to the gl_CullDistance vertex output variable.

    It is a compile-time or link-time error for the set of shaders
    forming a program to have the sum of the sizes of the
    gl_ClipDistance and gl_CullDistance arrays to be larger than
    gl_MaxCombinedClipAndCullDistances.

    Modify Section 7.2, "Built-In Constants" (p. 126)

    const mediump int gl_MaxClipDistances = 8;
    const mediump int gl_MaxCullDistances = 8;
    const mediump int gl_MaxCombinedClipAndCullDistances = 8;

Additions to the AGL/EGL/GLX/WGL Specifications

    None


Dependencies on OpenGL ES 3.2

    If OpenGL ES 3.2 is not supported, ignore all references
    to geometry and tessellation shaders (unless one of the
    following extensions is supported).

Dependencies on OES_tessellation_shader and EXT_tessellation_shader

    If neither OES_tessellation_shader nor EXT_tessellation_shader
    are supported, ignore all references to tessellation shaders.

Dependencies on OES_tessellation_point_size and EXT_tessellation_point_size

    If neither OES_tessellation_point_size nor EXT_tessellation_point_size
    are supported, ignore all references to gl_PointSize as inputs
    or outputs to the tessellation stages.

Dependencies on OES_geometry_shader and EXT_geometry_shader

    If neither OES_geometry_shader nor EXT_geometry_shader
    are supported, ignore all references to geometry shaders.

Errors

    none

New State

    Add the following to Table 21.6 (Transformation State), p447:

                                      Initial
    Get Value          Type   Get Command Value    Description       Sec.
    ------------------ ------ ----------- -------- ----------------- ----
    CLIP_DISTANCEi_EXT 8* x B IsEnabled   FALSE    ith user clipping 12.4
                                                   plane enabled


New Implementation Dependent State

    Add the following to Table 21.40 (Implementation Dependent Values), p481:

                                            Minimum
    Get Value              Type Get Command Value    Description       Sec.
    ---------------------- ---- ----------- -------- ----------------- ----
    MAX_CLIP_DISTANCES_EXT Z+   GetIntegerv 8        Max. no. of user  12.4
                                                     clipping planes
    MAX_CULL_DISTANCE_EXT  Z+   GetIntegerv 8        Max. no. of user  12.4
                                                     cull distances
    MAX_COMBINED_CLIP_AND- Z+   GetIntegerv 8        Max. combined no. 12.4
    _CULL_DISTANCES_EXT                              of user clipping

Conformance Tests

    Unspecified at this time.

Issues

    For historical issues see ARB_clip_distance

    (1) If the vertex shader stages write to clip/cull distance, do further
        vertex processing stages need to pass it through?

    RESOLVED: Yes. This is how it works in OpenGL.

    (2) Should we have two separate GLSL behavior:

        #extension GL_EXT_clip_distance : <behavior>
        #extension GL_EXT_cull_distance : <behavior>

        or single behavior for both:

        #extension GL_EXT_clip_cull_distance : <behavior>

    RESOLVED: Single behavior for both the clip/cull functionality:

        #extension GL_EXT_clip_cull_distance : <behavior>

Revision History

    Rev.    Date    Author    Changes
    ----  --------  ------  ---------------------------------
     3    03/09/16  mribble Clean up QTI names and emails.

     2    03/08/16  dkoch   Language consistency and cleanup pass.
                            Added a bunch of missing language.

     1              kseth  Initial draft