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 parameters of GetBooleanv, GetIntegerv, GetInteger64v, and GetFloatv: MAX_CLIP_DISTANCES_APPLE 0x0D32 Accepted by the 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 : where 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 -