1Name 2 3 EXT_clip_cull_distance 4 5Name Strings 6 7 GL_EXT_clip_cull_distance 8 9Contact 10 11 Maurice Ribble, Qualcomm Technologies Inc. (mribble 'at' qti.qualcomm.com) 12 13Contributors 14 Kulin Seth, Qualcomm Technologies Inc. 15 Sam Holmes, Qualcomm Technologies Inc. 16 Jeff Leger, Qualcomm Technologies Inc. 17 Daniel Koch, NVIDIA 18 Jan-Harald Fredriksen, ARM 19 Bill Licea-Kane, Qualcomm Technologies Inc. 20 21Status 22 23 Complete 24 25Version 26 27 Last Modified Date: March 9, 2016 28 Revision: 3 29 30Number 31 32 OpenGL ES Extension #257 33 34Dependencies 35 36 This specification is written against the OpenGL ES 3.2 Specification 37 (August 10, 2015), and the OpenGL ES 3.2 Shading Language Specification 38 (August 6, 2015) but can apply to prior specifications. 39 40 OpenGL ES 3.0 is required. 41 42 This extension interacts with OpenGL ES 3.2. 43 44 This extension interacts with OES_tessellation_shader and 45 EXT_tessellation_shader. 46 47 This extension trivially interacts with OES_tessellation_point_size 48 and EXT_tessellation_point_size. 49 50 This extension interacts with OES_geometry_shader and 51 EXT_geometry_shader. 52 53Overview 54 55 This extension adds support for hardware clip planes and cull 56 distances to OpenGL ES. The language for this extension is based 57 on the OpenGL 4.5 API Specification (May 28, 2015) and 58 ARB_clip_distance. 59 60New Procedures and Functions 61 62 None 63 64New Tokens 65 66 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 67 GetInteger64v, and GetFloatv: 68 69 MAX_CLIP_DISTANCES_EXT 0x0D32 70 MAX_CULL_DISTANCES_EXT 0x82F9 71 MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT 0x82FA 72 73 Accepted by the <pname> parameters of Enable, Disable and IsEnabled: 74 75 CLIP_DISTANCE0_EXT 0x3000 76 CLIP_DISTANCE1_EXT 0x3001 77 CLIP_DISTANCE2_EXT 0x3002 78 CLIP_DISTANCE3_EXT 0x3003 79 CLIP_DISTANCE4_EXT 0x3004 80 CLIP_DISTANCE5_EXT 0x3005 81 CLIP_DISTANCE6_EXT 0x3006 82 CLIP_DISTANCE7_EXT 0x3007 83 84Additions to Chapter 7 of the OpenGL ES 3.2 Specification (Programs and 85Shaders) 86 87 Modify Section 7.4.1 "Shader Interface Matching" (p. 97), 88 adding the following to the end of the third paragraph (beginning with 89 "For program objects containing mutliple shaders,..."): 90 91 "If either shader redeclares the built-in arrays gl_CullDistance[] or 92 gl_ClipDistance[] the array must have the same size in both shaders." 93 94Additions to Chapter 11 of the OpenGL ES 3.2 Specification (Programmable 95Vertex Processing) 96 97 Modify Section 11.1.3.10, "Shader Outputs" (p. 300), 98 adding the following as a new paragraph after the description of 99 gl_Position: 100 101 "The built-in output variables gl_ClipDistance and gl_CullDistance 102 respectively hold the the clip distance and cull distance used in the 103 clipping stage, as described in section 12.4. If clipping is enabled, 104 gl_ClipDistance should be written." 105 106 Modify Section 11.2.1.2.2, "Tessellation Control Shader Inputs" (p. 307), 107 replacing the last sentence of the first paragraph as follows: 108 109 "The members of each element of the gl_in array are gl_Position, 110 gl_CullDistance, and gl_ClipDistance 111 [[ If OES_tessellation_point_size or EXT_tessellation_point_size 112 are supported: ]] 113 and gl_PointSize." 114 115 Modify Section 11.2.1.2.3, "Tessellation Control Shader Outputs" (p. 308), 116 replacing the last two sentences of the first paragraph as follows: 117 118 "The members of each element of the gl_out array are gl_Position, 119 gl_ClipDistance and gl_CullDistance 120 [[ If OES_tessellation_point_size or EXT_tessellation_point_size 121 are supported: ]] 122 and gl_PointSize, 123 and behave identically to equivalently named vertex shader outputs 124 (see section 11.1.3)." 125 126 Modify Section 11.2.3.3 "Tessellation Evaluation Shader Inputs" (p. 321), 127 replacing the last sentence of the first paragraph as follows: 128 129 "The members of each element of the gl_in array are gl_Position, 130 gl_CullDistance, and gl_ClipDistance 131 [[ If OES_tessellation_point_size or EXT_tessellation_point_size 132 are supported: ]] 133 and gl_PointSize." 134 135 Modify Section 11.2.3.4, "Tessellation Evaluation Shader Outputs" (p. 322), 136 replacing the first two sentences of the first paragraph as follows: 137 138 "Tessellation evalution shaders have a number of built-in output variables 139 used to pass values to equivalent built-in input variagles read by 140 subsequent shader stages or to subsequent fixed functionality vertex 141 processing pipeline stages. These variables are gl_Position, 142 gl_ClipDistance and gl_CullDistance 143 [[ If OES_tessellation_point_size or EXT_tessellation_point_size 144 are supported: ]] 145 and gl_PointSize, 146 and all behave identically to equivalently named vertex shader outputs 147 (see section 11.1.3)." 148 149 Modify Section 11.3.4.3, "Geometry Shader Inputs" (p. 327) by adding the 150 following two bullet points to the description of the elements of gl_in[]: 151 152 "* Structure member gl_ClipDistance[] holds the per-vertex array of clip 153 distances, as written by the upstream shader to the built-in output variable 154 gl_ClipDistance[]. 155 156 * Structure member gl_CullDistance[] holds the per-vertex array of cull 157 distances, as written by the upstream shader to the built-in output variable 158 gl_CullDistance[]." 159 160 Modify Section 11.3.4.4 "Geometry Shader Outputs" (p. 329), adding the 161 following paragraph after the description of gl_Position: 162 163 "The built-in outputs gl_ClipDistance and gl_CullDistance hold the clip 164 distance and cull distance, respectively, used in the clipping stage, as 165 described in Section 12.4." 166 167Additions to Chapter 12 of the OpenGL ES 3.2 Specification (Fixed-Function 168Vertex Post-Processing) 169 170 Modify Section 12.4, "Primitive Clipping" (p. 341), 171 replacing the first four paragraphs with the following: 172 173 "Primitives are culled against the cull volume and then clipped to the 174 clip volume. In clip coordinates, the view volume is defined by 175 -wc <= xc <= wc 176 -wc <= yc <= wc 177 -zmin <= zc <= wc. 178 179 where zmin is -wc. 180 181 This view volume may be further restricted by as many as <n> 182 client-defined halfspaces. <n> is an implementation-dependent maximum that 183 must be at least 8, and may be determined by calling GetIntegerv with 184 pname MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT. 185 186 The cull volume is the intersection of up to the value of 187 MAX_CULL_DISTANCES_EXT client-defined half-spaces (if no client-defined 188 cull half-spaces are enabled, culling against the cull volume is skipped). 189 The number of enabled cull half-spaces is determined by the explicit or 190 implicit size of the built-in array gl_CullDistance in the last shader 191 stage before rasterization which has an active program. 192 193 A shader may write a single cull distance for each enabled cull half-space 194 to elements of the gl_CullDistance[] array. If the cull distance for any 195 enabled cull half-space is negative for all of the vertices of the 196 primitive under consideration, the primitive is discarded. Otherwise the 197 primitive is clipped against the clip volume as defined below. 198 199 The clip volume is the intersection of up to the value of 200 MAX_CLIP_DISTANCES_EXT client-defined half-spaces with the view volume 201 (if no client-defined clip half-spaces are enabled, the clip volume is 202 the view volume). 203 204 A vertex shader may write a single clip distance for each enabled clip 205 halfspace to elements of the gl_ClipDistance[] array. Clip half-space 206 <i> is then given by the set of points satisfying the inequality 207 ci(P) >= 0, 208 where ci(P) is the value of clip distance <i> at point P. For point 209 primitives, ci(P) is simply the clip distance for the vertex in question. 210 For line and triangle primitives, per-vertex clip distances are 211 interpolated using a weighted mean, with weights derived according to the 212 algorithms described in sections 13.6 (Line Segments) and 13.7 213 (Polygons). 214 215 Client-defined clip half-spaces are enabled or disabled by calling 216 Enable or Disable with target CLIP_DISTANCE<i>_EXT, where <i> is an 217 integer between 0 and <n> - 1; specifying a value of <i> enables or 218 disables the client-defined clip half-space with index <i>. The 219 constants obey CLIP_DISTANCE<i>_EXT = CLIP_DISTANCE0_EXT + <i>. 220 221 If the primitive under consideration is a point, then clipping passes it 222 unchanged if it lies withing the clip volume; otherwise it is discarded. 223 224 If the primitive is a line segment, then clipping does nothing to it if 225 it lies entirely withing the clip volume, and discards it if it lies 226 entirely outside the volume. 227 228 If part of the line segment lies in the volume and part of it lies 229 outside, then the line segment is clipped and new vertex coordinates 230 are computed for one or both vertices. A clipped line segment endpoint 231 lies on both the original line segment and the boundary of the clip 232 volume. 233 234 This clipping produces..." 235 236 Add the following text to the end of Section 12.4: 237 238 "Primitives rendered with user-defined half-spaces must satisfy a 239 complimentary criterion. Suppose a series of primitives is drawn where 240 each vertex <i> has a single specified clip distance <di> (or a number 241 of similarly specified clip distances, if multiple half-spaces are 242 enabled). Next, suppose that the same series of primitives are drawn 243 again with each such clip distance replaced by -<di> (and the GL is 244 otherwise in the same state). In this case, primitives must not be 245 missing any pixels, nor may any pixels be drawn twice in regions where 246 those primitives are cut by the clip planes. 247 248 The state required for clipping is MAX_CLIP_DISTANCES_EXT bits indicating 249 which of the client-defined half-spaces are enabled. In the initial state, 250 all half-spaces are disabled." 251 252Additions to OpenGL ES Shading Language 3.20 Specification 253 254 Including the following line in a shader can be used to control 255 the language features described in this extension: 256 257 #extension GL_EXT_clip_cull_distance : <behavior> 258 259 where <behavior> is as described in section 3.4. 260 261 A new preprocessor #define is added to the OpenGL ES Shading Language: 262 263 #define GL_EXT_clip_cull_distance 1 264 265Additions to Chapter 7 of the OpenGL ES Shading Language 3.20 Specification 266(Built-in Variables) 267 268 Modify Section 7.1, Vertex Shader Special Variables (p. 119) 269 out gl_PerVertex 270 { 271 ... 272 highp float gl_ClipDistance[]; 273 highp float gl_CullDistance[]; 274 275 }; 276 277 Similar changes in Geometry, Tessellation Control, Tessellation Evaluation 278 language "in gl_PerVertex" and "out gl_PerVertex" structures. 279 280 Modify Section 7.1.5 "Fragment Shader Special Variables" (p. 123) 281 282 in highp float gl_ClipDistance[]; 283 in highp float gl_CullDistance[]; 284 285 The variable gl_ClipDistance provides the mechanism for controlling 286 user clipping. The element gl_ClipDistance[i] specifies a clip 287 distance for each plane <i>. A distance of 0 means the vertex is on 288 the plane, a positive distance means the vertex is inside the clip 289 plane, and a negative distance means the point is outside the clip 290 plane. The clip distances will be linearly interpolated across the 291 primitive and the portion of the primitive with interpolated 292 distances less than 0 will be clipped. 293 294 The gl_ClipDistance array is predeclared as unsized and must be 295 explicitly sized by the shader either redeclaring it with a size 296 or implicitly sized by indexing it only with integral constant 297 expressions. This needs to size the array to include all the clip 298 planes that are enabled via the OpenGL ES API; 299 if the size does not include all enabled planes, results are 300 undefined. The size can be at most gl_MaxClipDistances. The 301 number of varying components (see gl_MaxVaryingComponents) consumed 302 by gl_ClipDistance will match the size of the array, no matter 303 how many planes are enabled. The shader must also set all values in 304 gl_ClipDistance that have been enabled via the OpenGL ES API, 305 or results are undefined. Values written into gl_ClipDistance 306 for planes that are not enabled have no effect. 307 308 As an output variable, gl_ClipDistance provides the place for the 309 shader to write these distances. As an input in all but the fragment 310 language, it reads the values written in the previous shader stage. 311 In the fragment language, gl_ClipDistance array contains linearly 312 interpolated values for the vertex values written by a shader to 313 the gl_ClipDistance vertex output variable. Only elements in this 314 array that have clipping enabled will have defined values. 315 316 The variable gl_CullDistance provides a mechanism for controlling 317 user culling. The element gl_CullDistance[i] specifies a cull 318 distance for plane <i>. A distance of 0 means the vertex is on the 319 plane, a positive distance means the vertex is inside the cull 320 volume, and a negative distance means the point is outside the 321 cull volume. Primitives whose vertices all have a negative clip 322 distance for plane <i> will be discarded. 323 324 The gl_CullDistance array is predeclared as unsized and must be 325 sized by the shader either redeclaring it with a size or indexing 326 it only with integral constant expressions. The size determines 327 the number and set of enabled cull distances and can be at most 328 gl_MaxCullDistances. The number of varying components 329 (see gl_MaxVaryingComponents) consumed by gl_CullDistance will 330 match the size of the array. Shaders writing gl_CullDistance must 331 write all enabled distances, or culling results are undefined. 332 333 As an output variable, gl_CullDistance provides the place for 334 the shader to write these distances. As an input in all but the 335 fragment language, it reads the values written in the previous 336 shader stage. In the fragment language, gl_CullDistance array 337 contains linearly interpolated values for the vertex values 338 written by a shader to the gl_CullDistance vertex output variable. 339 340 It is a compile-time or link-time error for the set of shaders 341 forming a program to have the sum of the sizes of the 342 gl_ClipDistance and gl_CullDistance arrays to be larger than 343 gl_MaxCombinedClipAndCullDistances. 344 345 Modify Section 7.2, "Built-In Constants" (p. 126) 346 347 const mediump int gl_MaxClipDistances = 8; 348 const mediump int gl_MaxCullDistances = 8; 349 const mediump int gl_MaxCombinedClipAndCullDistances = 8; 350 351Additions to the AGL/EGL/GLX/WGL Specifications 352 353 None 354 355 356Dependencies on OpenGL ES 3.2 357 358 If OpenGL ES 3.2 is not supported, ignore all references 359 to geometry and tessellation shaders (unless one of the 360 following extensions is supported). 361 362Dependencies on OES_tessellation_shader and EXT_tessellation_shader 363 364 If neither OES_tessellation_shader nor EXT_tessellation_shader 365 are supported, ignore all references to tessellation shaders. 366 367Dependencies on OES_tessellation_point_size and EXT_tessellation_point_size 368 369 If neither OES_tessellation_point_size nor EXT_tessellation_point_size 370 are supported, ignore all references to gl_PointSize as inputs 371 or outputs to the tessellation stages. 372 373Dependencies on OES_geometry_shader and EXT_geometry_shader 374 375 If neither OES_geometry_shader nor EXT_geometry_shader 376 are supported, ignore all references to geometry shaders. 377 378Errors 379 380 none 381 382New State 383 384 Add the following to Table 21.6 (Transformation State), p447: 385 386 Initial 387 Get Value Type Get Command Value Description Sec. 388 ------------------ ------ ----------- -------- ----------------- ---- 389 CLIP_DISTANCEi_EXT 8* x B IsEnabled FALSE ith user clipping 12.4 390 plane enabled 391 392 393New Implementation Dependent State 394 395 Add the following to Table 21.40 (Implementation Dependent Values), p481: 396 397 Minimum 398 Get Value Type Get Command Value Description Sec. 399 ---------------------- ---- ----------- -------- ----------------- ---- 400 MAX_CLIP_DISTANCES_EXT Z+ GetIntegerv 8 Max. no. of user 12.4 401 clipping planes 402 MAX_CULL_DISTANCE_EXT Z+ GetIntegerv 8 Max. no. of user 12.4 403 cull distances 404 MAX_COMBINED_CLIP_AND- Z+ GetIntegerv 8 Max. combined no. 12.4 405 _CULL_DISTANCES_EXT of user clipping 406 407Conformance Tests 408 409 Unspecified at this time. 410 411Issues 412 413 For historical issues see ARB_clip_distance 414 415 (1) If the vertex shader stages write to clip/cull distance, do further 416 vertex processing stages need to pass it through? 417 418 RESOLVED: Yes. This is how it works in OpenGL. 419 420 (2) Should we have two separate GLSL behavior: 421 422 #extension GL_EXT_clip_distance : <behavior> 423 #extension GL_EXT_cull_distance : <behavior> 424 425 or single behavior for both: 426 427 #extension GL_EXT_clip_cull_distance : <behavior> 428 429 RESOLVED: Single behavior for both the clip/cull functionality: 430 431 #extension GL_EXT_clip_cull_distance : <behavior> 432 433Revision History 434 435 Rev. Date Author Changes 436 ---- -------- ------ --------------------------------- 437 3 03/09/16 mribble Clean up QTI names and emails. 438 439 2 03/08/16 dkoch Language consistency and cleanup pass. 440 Added a bunch of missing language. 441 442 1 kseth Initial draft 443