| Name |
| |
| APPLE_clip_distance |
| |
| Name Strings |
| |
| GL_APPLE_clip_distance |
| |
| Contact |
| |
| Eric Sunalp, Apple (esunalp 'at' apple.com) |
| |
| Contributors |
| |
| Keith Bauer |
| Alex Eddy |
| Benj Lipchak |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Last Modified Date: December 9, 2013 |
| Revision: 1 |
| |
| Number |
| |
| OpenGL ES Extension #193 |
| |
| Dependencies |
| |
| 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). |
| |
| Overview |
| |
| 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. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Tokens |
| |
| 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 |
| |
| Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) |
| [ES2] or |
| Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL Operation) |
| [ES3] |
| |
| Modify Section 2.13, Primitive Clipping (p. 46) [ES2] or |
| Modify Section 2.17, Primitive Clipping (p. 91) [ES3] |
| |
| 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. |
| |
| Additions to OpenGL ES Shading Language 1.00 Specification [ES2] or |
| Additions to OpenGL ES Shading Language 3.00 Specification [ES3] |
| |
| 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 |
| |
| Additions to Chapter 7 of the OpenGL ES Shading Language 1.00 Specification |
| (Built-in Variables) [ES2] or |
| Additions to Chapter 7 of the OpenGL ES Shading Language 3.00 Specification |
| (Built-in Variables) [ES3] |
| |
| Modify Section 7.1, Vertex Shader Special Variables (p. 59) [ES2] |
| |
| varying highp float gl_ClipDistance[]; |
| |
| Modify Section 7.1, Vertex Shader Special Variables (p. 77) [ES3] |
| |
| out highp float gl_ClipDistance[]; |
| |
| Modify Section 7.1, Vertex Shader Special Variables (p. 59) [ES2] or |
| Modify Section 7.1, Vertex Shader Special Variables (p. 77) [ES3] |
| |
| 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. |
| |
| Modify Section 7.4, Built-in Constants (p. 61) [ES2] or |
| Modify Section 7.3, Built-In Constants (p. 78) [ES3] |
| |
| const mediump int gl_MaxClipDistances = 8; |
| |
| Additions to the AGL/EGL/GLX/WGL Specifications |
| |
| None |
| |
| Errors |
| |
| none |
| |
| New State |
| |
| 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] |
| |
| |
| New Implementation Dependent State |
| |
| 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 |
| |
| Conformance Tests |
| |
| Unspecified at this time. |
| |
| Issues |
| |
| (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 History |
| |
| Revision 1, 2013/12/13 |
| - |