APPLE_clip_distance

GL_APPLE_clip_distance

Eric Sunalp, Apple (esunalp 'at' apple.com)

Keith Bauer
Alex Eddy
Benj Lipchak

Complete

Last Modified Date: December 9, 2013
Revision: 1

OpenGL ES Extension #193

OpenGL ES 2.0 or OpenGL ES 3.0 is required.

This extension is written against the OpenGL ES 2.0.25 Specification
(November 2, 2010) and the OpenGL ES 3.0.2 Specification (April 8, 2013).

This extension adds support for hardware clip planes to OpenGL ES 2.0
and 3.0.  These were present in OpenGL ES 1.1, but were removed to
better match certain hardware.  Since they're useful for certain
applications, notable CAD, we return them here.

No known IP claims.

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

    MAX_CLIP_DISTANCES_APPLE       0x0D32

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

    CLIP_DISTANCE0_APPLE           0x3000
    CLIP_DISTANCE1_APPLE           0x3001
    CLIP_DISTANCE2_APPLE           0x3002
    CLIP_DISTANCE3_APPLE           0x3003
    CLIP_DISTANCE4_APPLE           0x3004
    CLIP_DISTANCE5_APPLE           0x3005
    CLIP_DISTANCE6_APPLE           0x3006
    CLIP_DISTANCE7_APPLE           0x3007

This view volume may be further restricted by as many as n client-
defined half-spaces. (n is an implementation-dependent maximum that must
be at least 8.)

The clip volume is the intersection of all such half-spaces with the view
volume (if no client-defined half-spaces are enabled, the clip volume is
the view volume).

A vertex shader may write a single clip distance for each supported
half-space to elements of the gl_ClipDistance[] array. Half-space n is
then given by the set of points satisfying the inequality

    c_n(P) >= 0,

where c_n(P) is the value of clip distance n at point P. For point
primitives, c_n(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 3.4 [ES2] or 3.5 [ES3] and
3.5 [ES2] or 3.6[ES3].

Client-defined half-spaces are enabled with the generic Enable command
and disabled with the Disable command. The value of the argument to
either command is CLIP_DISTANCEi_APPLE, where i is an integer between 0
and n − 1; specifying a value of i enables or disables the plane equation
with index i. The constants obey CLIP_DISTANCEi_APPLE =
CLIP_DISTANCE0_APPLE + i.

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

    #extension GL_APPLE_clip_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_APPLE_clip_distance 1

    varying highp float gl_ClipDistance[];

    out highp float gl_ClipDistance[];

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 sized by
the shader either redeclaring it with a size or 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 vectors (see
gl_MaxVaryingVectors) consumed by gl_ClipDistance will match the size
of the array divided by four, no matter how many planes are enabled.
The shader must also set all values in gl_ClipDistance that have been
enabled via the OpenGL API, or results are undefined.  Values written
into gl_ClipDistance for planes that are not enabled have no effect.

const mediump int gl_MaxClipDistances = 8;

None

none

                                  Initial
Get Value      Type   Get Command Value    Description       Sec.
-------------- ------ ----------- -------- ----------------- ----
CLIP_DISTANCE- 8* x B IsEnabled   FALSE    ith user clipping 2.13 [ES2] or
iAPPLE                                     plane enabled     2.17 [ES3]

                                  Minimum
Get Value      Type   Get Command Value    Description       Sec.
-------------- ------ ----------- -------- ----------------- ----
MAX_CLIP_DIST- Z+     GetIntegerv 8        Maximum number of 2.13 [ES2] or
ANCES_APPLE                                user clipping     2.17 [ES3]
                                           planes

Unspecified at this time.

(1) GLSL 300 doesn't support unsized arrays, how should gl_ClipDistance
be sized?

  RESOLVED: For maximal compatibility, it works like ES2/desktop,
  remaining unsized until sized by direct access or explicitly
  redeclared.  Language describing this behavior must be added to the
  extension specification since it's gone from the base language
  specification.

(2) Should we specify gl_ClipDistance as input to the fragment shader?

  RESOLVED: No.  Although this departs from the desktop, we don't know
  of anyone who needs or wants this behavior, and it complicates the
  driver without adding any additional functionality (the user can
  always pass clip distances to the fragment shader in user-defined
  varyings if they wish).

(3) Should the GLSL built-in be named gl_ClipDistanceAPPLE?

  RESOLVED: No.  Very few GLSL extensions have adopted name suffixes, it
  would hinder portability of shaders between OpenGL and OpenGL ES, and
  if in the future gl_ClipDistance becomes part of some core ES shading
  language there are no likely incompatibilities with this extension.

Revision 1, 2013/12/13
    -