1Name 2 3 APPLE_clip_distance 4 5Name Strings 6 7 GL_APPLE_clip_distance 8 9Contact 10 11 Eric Sunalp, Apple (esunalp 'at' apple.com) 12 13Contributors 14 15 Keith Bauer 16 Alex Eddy 17 Benj Lipchak 18 19Status 20 21 Complete 22 23Version 24 25 Last Modified Date: December 9, 2013 26 Revision: 1 27 28Number 29 30 OpenGL ES Extension #193 31 32Dependencies 33 34 OpenGL ES 2.0 or OpenGL ES 3.0 is required. 35 36 This extension is written against the OpenGL ES 2.0.25 Specification 37 (November 2, 2010) and the OpenGL ES 3.0.2 Specification (April 8, 2013). 38 39Overview 40 41 This extension adds support for hardware clip planes to OpenGL ES 2.0 42 and 3.0. These were present in OpenGL ES 1.1, but were removed to 43 better match certain hardware. Since they're useful for certain 44 applications, notable CAD, we return them here. 45 46IP Status 47 48 No known IP claims. 49 50New Tokens 51 52 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 53 GetInteger64v, and GetFloatv: 54 55 MAX_CLIP_DISTANCES_APPLE 0x0D32 56 57 Accepted by the <pname> parameters of Enable, Disable and IsEnabled: 58 59 CLIP_DISTANCE0_APPLE 0x3000 60 CLIP_DISTANCE1_APPLE 0x3001 61 CLIP_DISTANCE2_APPLE 0x3002 62 CLIP_DISTANCE3_APPLE 0x3003 63 CLIP_DISTANCE4_APPLE 0x3004 64 CLIP_DISTANCE5_APPLE 0x3005 65 CLIP_DISTANCE6_APPLE 0x3006 66 CLIP_DISTANCE7_APPLE 0x3007 67 68Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) 69[ES2] or 70Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL Operation) 71[ES3] 72 73Modify Section 2.13, Primitive Clipping (p. 46) [ES2] or 74Modify Section 2.17, Primitive Clipping (p. 91) [ES3] 75 76 This view volume may be further restricted by as many as n client- 77 defined half-spaces. (n is an implementation-dependent maximum that must 78 be at least 8.) 79 80 The clip volume is the intersection of all such half-spaces with the view 81 volume (if no client-defined half-spaces are enabled, the clip volume is 82 the view volume). 83 84 A vertex shader may write a single clip distance for each supported 85 half-space to elements of the gl_ClipDistance[] array. Half-space n is 86 then given by the set of points satisfying the inequality 87 88 c_n(P) >= 0, 89 90 where c_n(P) is the value of clip distance n at point P. For point 91 primitives, c_n(P) is simply the clip distance for the vertex in question. 92 For line and triangle primitives, per-vertex clip distances are 93 interpolated using a weighted mean, with weights derived according to the 94 algorithms described in sections 3.4 [ES2] or 3.5 [ES3] and 95 3.5 [ES2] or 3.6[ES3]. 96 97 Client-defined half-spaces are enabled with the generic Enable command 98 and disabled with the Disable command. The value of the argument to 99 either command is CLIP_DISTANCEi_APPLE, where i is an integer between 0 100 and n − 1; specifying a value of i enables or disables the plane equation 101 with index i. The constants obey CLIP_DISTANCEi_APPLE = 102 CLIP_DISTANCE0_APPLE + i. 103 104Additions to OpenGL ES Shading Language 1.00 Specification [ES2] or 105Additions to OpenGL ES Shading Language 3.00 Specification [ES3] 106 107 Including the following line in a shader can be used to control 108 the language features described in this extension: 109 110 #extension GL_APPLE_clip_distance : <behavior> 111 112 where <behavior> is as described in section 3.4. 113 114 A new preprocessor #define is added to the OpenGL ES Shading Language: 115 116 #define GL_APPLE_clip_distance 1 117 118Additions to Chapter 7 of the OpenGL ES Shading Language 1.00 Specification 119(Built-in Variables) [ES2] or 120Additions to Chapter 7 of the OpenGL ES Shading Language 3.00 Specification 121(Built-in Variables) [ES3] 122 123Modify Section 7.1, Vertex Shader Special Variables (p. 59) [ES2] 124 125 varying highp float gl_ClipDistance[]; 126 127Modify Section 7.1, Vertex Shader Special Variables (p. 77) [ES3] 128 129 out highp float gl_ClipDistance[]; 130 131Modify Section 7.1, Vertex Shader Special Variables (p. 59) [ES2] or 132Modify Section 7.1, Vertex Shader Special Variables (p. 77) [ES3] 133 134 The variable gl_ClipDistance provides the mechanism for controlling 135 user clipping. The element gl_ClipDistance[i] specifies a clip distance 136 for each plane i. A distance of 0 means the vertex is on the plane, a 137 positive distance means the vertex is inside the clip plane, and a 138 negative distance means the point is outside the clip plane. The clip 139 distances will be linearly interpolated across the primitive and the 140 portion of the primitive with interpolated distances less than 0 will 141 be clipped. 142 143 The gl_ClipDistance array is predeclared as unsized and must be sized by 144 the shader either redeclaring it with a size or indexing it only with 145 integral constant expressions. This needs to size the array to include 146 all the clip planes that are enabled via the OpenGL ES API; if the size 147 does not include all enabled planes, results are undefined. The size can 148 be at most gl_MaxClipDistances. The number of varying vectors (see 149 gl_MaxVaryingVectors) consumed by gl_ClipDistance will match the size 150 of the array divided by four, no matter how many planes are enabled. 151 The shader must also set all values in gl_ClipDistance that have been 152 enabled via the OpenGL API, or results are undefined. Values written 153 into gl_ClipDistance for planes that are not enabled have no effect. 154 155Modify Section 7.4, Built-in Constants (p. 61) [ES2] or 156Modify Section 7.3, Built-In Constants (p. 78) [ES3] 157 158 const mediump int gl_MaxClipDistances = 8; 159 160Additions to the AGL/EGL/GLX/WGL Specifications 161 162 None 163 164Errors 165 166 none 167 168New State 169 170 Initial 171 Get Value Type Get Command Value Description Sec. 172 -------------- ------ ----------- -------- ----------------- ---- 173 CLIP_DISTANCE- 8* x B IsEnabled FALSE ith user clipping 2.13 [ES2] or 174 iAPPLE plane enabled 2.17 [ES3] 175 176 177New Implementation Dependent State 178 179 Minimum 180 Get Value Type Get Command Value Description Sec. 181 -------------- ------ ----------- -------- ----------------- ---- 182 MAX_CLIP_DIST- Z+ GetIntegerv 8 Maximum number of 2.13 [ES2] or 183 ANCES_APPLE user clipping 2.17 [ES3] 184 planes 185 186Conformance Tests 187 188 Unspecified at this time. 189 190Issues 191 192 (1) GLSL 300 doesn't support unsized arrays, how should gl_ClipDistance 193 be sized? 194 195 RESOLVED: For maximal compatibility, it works like ES2/desktop, 196 remaining unsized until sized by direct access or explicitly 197 redeclared. Language describing this behavior must be added to the 198 extension specification since it's gone from the base language 199 specification. 200 201 (2) Should we specify gl_ClipDistance as input to the fragment shader? 202 203 RESOLVED: No. Although this departs from the desktop, we don't know 204 of anyone who needs or wants this behavior, and it complicates the 205 driver without adding any additional functionality (the user can 206 always pass clip distances to the fragment shader in user-defined 207 varyings if they wish). 208 209 (3) Should the GLSL built-in be named gl_ClipDistanceAPPLE? 210 211 RESOLVED: No. Very few GLSL extensions have adopted name suffixes, it 212 would hinder portability of shaders between OpenGL and OpenGL ES, and 213 if in the future gl_ClipDistance becomes part of some core ES shading 214 language there are no likely incompatibilities with this extension. 215 216Revision History 217 218 Revision 1, 2013/12/13 219 - 220