blob: c49835ec50a48580936132dd76eeed54de616d54 [file] [log] [blame]
Name
EXT_clip_cull_distance
Name Strings
GL_EXT_clip_cull_distance
Contact
Maurice Ribble, Qualcomm Technologies Inc. (mribble 'at' qti.qualcomm.com)
Contributors
Kulin Seth, Qualcomm Technologies Inc.
Sam Holmes, Qualcomm Technologies Inc.
Jeff Leger, Qualcomm Technologies Inc.
Daniel Koch, NVIDIA
Jan-Harald Fredriksen, ARM
Bill Licea-Kane, Qualcomm Technologies Inc.
Status
Complete
Version
Last Modified Date: March 9, 2016
Revision: 3
Number
OpenGL ES Extension #257
Dependencies
This specification is written against the OpenGL ES 3.2 Specification
(August 10, 2015), and the OpenGL ES 3.2 Shading Language Specification
(August 6, 2015) but can apply to prior specifications.
OpenGL ES 3.0 is required.
This extension interacts with OpenGL ES 3.2.
This extension interacts with OES_tessellation_shader and
EXT_tessellation_shader.
This extension trivially interacts with OES_tessellation_point_size
and EXT_tessellation_point_size.
This extension interacts with OES_geometry_shader and
EXT_geometry_shader.
Overview
This extension adds support for hardware clip planes and cull
distances to OpenGL ES. The language for this extension is based
on the OpenGL 4.5 API Specification (May 28, 2015) and
ARB_clip_distance.
New Procedures and Functions
None
New Tokens
Accepted by the <pname> parameters of GetBooleanv, GetIntegerv,
GetInteger64v, and GetFloatv:
MAX_CLIP_DISTANCES_EXT 0x0D32
MAX_CULL_DISTANCES_EXT 0x82F9
MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT 0x82FA
Accepted by the <pname> parameters of Enable, Disable and IsEnabled:
CLIP_DISTANCE0_EXT 0x3000
CLIP_DISTANCE1_EXT 0x3001
CLIP_DISTANCE2_EXT 0x3002
CLIP_DISTANCE3_EXT 0x3003
CLIP_DISTANCE4_EXT 0x3004
CLIP_DISTANCE5_EXT 0x3005
CLIP_DISTANCE6_EXT 0x3006
CLIP_DISTANCE7_EXT 0x3007
Additions to Chapter 7 of the OpenGL ES 3.2 Specification (Programs and
Shaders)
Modify Section 7.4.1 "Shader Interface Matching" (p. 97),
adding the following to the end of the third paragraph (beginning with
"For program objects containing mutliple shaders,..."):
"If either shader redeclares the built-in arrays gl_CullDistance[] or
gl_ClipDistance[] the array must have the same size in both shaders."
Additions to Chapter 11 of the OpenGL ES 3.2 Specification (Programmable
Vertex Processing)
Modify Section 11.1.3.10, "Shader Outputs" (p. 300),
adding the following as a new paragraph after the description of
gl_Position:
"The built-in output variables gl_ClipDistance and gl_CullDistance
respectively hold the the clip distance and cull distance used in the
clipping stage, as described in section 12.4. If clipping is enabled,
gl_ClipDistance should be written."
Modify Section 11.2.1.2.2, "Tessellation Control Shader Inputs" (p. 307),
replacing the last sentence of the first paragraph as follows:
"The members of each element of the gl_in array are gl_Position,
gl_CullDistance, and gl_ClipDistance
[[ If OES_tessellation_point_size or EXT_tessellation_point_size
are supported: ]]
and gl_PointSize."
Modify Section 11.2.1.2.3, "Tessellation Control Shader Outputs" (p. 308),
replacing the last two sentences of the first paragraph as follows:
"The members of each element of the gl_out array are gl_Position,
gl_ClipDistance and gl_CullDistance
[[ If OES_tessellation_point_size or EXT_tessellation_point_size
are supported: ]]
and gl_PointSize,
and behave identically to equivalently named vertex shader outputs
(see section 11.1.3)."
Modify Section 11.2.3.3 "Tessellation Evaluation Shader Inputs" (p. 321),
replacing the last sentence of the first paragraph as follows:
"The members of each element of the gl_in array are gl_Position,
gl_CullDistance, and gl_ClipDistance
[[ If OES_tessellation_point_size or EXT_tessellation_point_size
are supported: ]]
and gl_PointSize."
Modify Section 11.2.3.4, "Tessellation Evaluation Shader Outputs" (p. 322),
replacing the first two sentences of the first paragraph as follows:
"Tessellation evalution shaders have a number of built-in output variables
used to pass values to equivalent built-in input variagles read by
subsequent shader stages or to subsequent fixed functionality vertex
processing pipeline stages. These variables are gl_Position,
gl_ClipDistance and gl_CullDistance
[[ If OES_tessellation_point_size or EXT_tessellation_point_size
are supported: ]]
and gl_PointSize,
and all behave identically to equivalently named vertex shader outputs
(see section 11.1.3)."
Modify Section 11.3.4.3, "Geometry Shader Inputs" (p. 327) by adding the
following two bullet points to the description of the elements of gl_in[]:
"* Structure member gl_ClipDistance[] holds the per-vertex array of clip
distances, as written by the upstream shader to the built-in output variable
gl_ClipDistance[].
* Structure member gl_CullDistance[] holds the per-vertex array of cull
distances, as written by the upstream shader to the built-in output variable
gl_CullDistance[]."
Modify Section 11.3.4.4 "Geometry Shader Outputs" (p. 329), adding the
following paragraph after the description of gl_Position:
"The built-in outputs gl_ClipDistance and gl_CullDistance hold the clip
distance and cull distance, respectively, used in the clipping stage, as
described in Section 12.4."
Additions to Chapter 12 of the OpenGL ES 3.2 Specification (Fixed-Function
Vertex Post-Processing)
Modify Section 12.4, "Primitive Clipping" (p. 341),
replacing the first four paragraphs with the following:
"Primitives are culled against the cull volume and then clipped to the
clip volume. In clip coordinates, the view volume is defined by
-wc <= xc <= wc
-wc <= yc <= wc
-zmin <= zc <= wc.
where zmin is -wc.
This view volume may be further restricted by as many as <n>
client-defined halfspaces. <n> is an implementation-dependent maximum that
must be at least 8, and may be determined by calling GetIntegerv with
pname MAX_COMBINED_CLIP_AND_CULL_DISTANCES_EXT.
The cull volume is the intersection of up to the value of
MAX_CULL_DISTANCES_EXT client-defined half-spaces (if no client-defined
cull half-spaces are enabled, culling against the cull volume is skipped).
The number of enabled cull half-spaces is determined by the explicit or
implicit size of the built-in array gl_CullDistance in the last shader
stage before rasterization which has an active program.
A shader may write a single cull distance for each enabled cull half-space
to elements of the gl_CullDistance[] array. If the cull distance for any
enabled cull half-space is negative for all of the vertices of the
primitive under consideration, the primitive is discarded. Otherwise the
primitive is clipped against the clip volume as defined below.
The clip volume is the intersection of up to the value of
MAX_CLIP_DISTANCES_EXT client-defined half-spaces with the view volume
(if no client-defined clip half-spaces are enabled, the clip volume is
the view volume).
A vertex shader may write a single clip distance for each enabled clip
halfspace to elements of the gl_ClipDistance[] array. Clip half-space
<i> is then given by the set of points satisfying the inequality
ci(P) >= 0,
where ci(P) is the value of clip distance <i> at point P. For point
primitives, ci(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 13.6 (Line Segments) and 13.7
(Polygons).
Client-defined clip half-spaces are enabled or disabled by calling
Enable or Disable with target CLIP_DISTANCE<i>_EXT, where <i> is an
integer between 0 and <n> - 1; specifying a value of <i> enables or
disables the client-defined clip half-space with index <i>. The
constants obey CLIP_DISTANCE<i>_EXT = CLIP_DISTANCE0_EXT + <i>.
If the primitive under consideration is a point, then clipping passes it
unchanged if it lies withing the clip volume; otherwise it is discarded.
If the primitive is a line segment, then clipping does nothing to it if
it lies entirely withing the clip volume, and discards it if it lies
entirely outside the volume.
If part of the line segment lies in the volume and part of it lies
outside, then the line segment is clipped and new vertex coordinates
are computed for one or both vertices. A clipped line segment endpoint
lies on both the original line segment and the boundary of the clip
volume.
This clipping produces..."
Add the following text to the end of Section 12.4:
"Primitives rendered with user-defined half-spaces must satisfy a
complimentary criterion. Suppose a series of primitives is drawn where
each vertex <i> has a single specified clip distance <di> (or a number
of similarly specified clip distances, if multiple half-spaces are
enabled). Next, suppose that the same series of primitives are drawn
again with each such clip distance replaced by -<di> (and the GL is
otherwise in the same state). In this case, primitives must not be
missing any pixels, nor may any pixels be drawn twice in regions where
those primitives are cut by the clip planes.
The state required for clipping is MAX_CLIP_DISTANCES_EXT bits indicating
which of the client-defined half-spaces are enabled. In the initial state,
all half-spaces are disabled."
Additions to OpenGL ES Shading Language 3.20 Specification
Including the following line in a shader can be used to control
the language features described in this extension:
#extension GL_EXT_clip_cull_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_EXT_clip_cull_distance 1
Additions to Chapter 7 of the OpenGL ES Shading Language 3.20 Specification
(Built-in Variables)
Modify Section 7.1, Vertex Shader Special Variables (p. 119)
out gl_PerVertex
{
...
highp float gl_ClipDistance[];
highp float gl_CullDistance[];
};
Similar changes in Geometry, Tessellation Control, Tessellation Evaluation
language "in gl_PerVertex" and "out gl_PerVertex" structures.
Modify Section 7.1.5 "Fragment Shader Special Variables" (p. 123)
in highp float gl_ClipDistance[];
in highp float gl_CullDistance[];
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
explicitly sized by the shader either redeclaring it with a size
or implicitly sized by 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 components (see gl_MaxVaryingComponents) consumed
by gl_ClipDistance will match the size of the array, no matter
how many planes are enabled. The shader must also set all values in
gl_ClipDistance that have been enabled via the OpenGL ES API,
or results are undefined. Values written into gl_ClipDistance
for planes that are not enabled have no effect.
As an output variable, gl_ClipDistance provides the place for the
shader to write these distances. As an input in all but the fragment
language, it reads the values written in the previous shader stage.
In the fragment language, gl_ClipDistance array contains linearly
interpolated values for the vertex values written by a shader to
the gl_ClipDistance vertex output variable. Only elements in this
array that have clipping enabled will have defined values.
The variable gl_CullDistance provides a mechanism for controlling
user culling. The element gl_CullDistance[i] specifies a cull
distance for plane <i>. A distance of 0 means the vertex is on the
plane, a positive distance means the vertex is inside the cull
volume, and a negative distance means the point is outside the
cull volume. Primitives whose vertices all have a negative clip
distance for plane <i> will be discarded.
The gl_CullDistance 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. The size determines
the number and set of enabled cull distances and can be at most
gl_MaxCullDistances. The number of varying components
(see gl_MaxVaryingComponents) consumed by gl_CullDistance will
match the size of the array. Shaders writing gl_CullDistance must
write all enabled distances, or culling results are undefined.
As an output variable, gl_CullDistance provides the place for
the shader to write these distances. As an input in all but the
fragment language, it reads the values written in the previous
shader stage. In the fragment language, gl_CullDistance array
contains linearly interpolated values for the vertex values
written by a shader to the gl_CullDistance vertex output variable.
It is a compile-time or link-time error for the set of shaders
forming a program to have the sum of the sizes of the
gl_ClipDistance and gl_CullDistance arrays to be larger than
gl_MaxCombinedClipAndCullDistances.
Modify Section 7.2, "Built-In Constants" (p. 126)
const mediump int gl_MaxClipDistances = 8;
const mediump int gl_MaxCullDistances = 8;
const mediump int gl_MaxCombinedClipAndCullDistances = 8;
Additions to the AGL/EGL/GLX/WGL Specifications
None
Dependencies on OpenGL ES 3.2
If OpenGL ES 3.2 is not supported, ignore all references
to geometry and tessellation shaders (unless one of the
following extensions is supported).
Dependencies on OES_tessellation_shader and EXT_tessellation_shader
If neither OES_tessellation_shader nor EXT_tessellation_shader
are supported, ignore all references to tessellation shaders.
Dependencies on OES_tessellation_point_size and EXT_tessellation_point_size
If neither OES_tessellation_point_size nor EXT_tessellation_point_size
are supported, ignore all references to gl_PointSize as inputs
or outputs to the tessellation stages.
Dependencies on OES_geometry_shader and EXT_geometry_shader
If neither OES_geometry_shader nor EXT_geometry_shader
are supported, ignore all references to geometry shaders.
Errors
none
New State
Add the following to Table 21.6 (Transformation State), p447:
Initial
Get Value Type Get Command Value Description Sec.
------------------ ------ ----------- -------- ----------------- ----
CLIP_DISTANCEi_EXT 8* x B IsEnabled FALSE ith user clipping 12.4
plane enabled
New Implementation Dependent State
Add the following to Table 21.40 (Implementation Dependent Values), p481:
Minimum
Get Value Type Get Command Value Description Sec.
---------------------- ---- ----------- -------- ----------------- ----
MAX_CLIP_DISTANCES_EXT Z+ GetIntegerv 8 Max. no. of user 12.4
clipping planes
MAX_CULL_DISTANCE_EXT Z+ GetIntegerv 8 Max. no. of user 12.4
cull distances
MAX_COMBINED_CLIP_AND- Z+ GetIntegerv 8 Max. combined no. 12.4
_CULL_DISTANCES_EXT of user clipping
Conformance Tests
Unspecified at this time.
Issues
For historical issues see ARB_clip_distance
(1) If the vertex shader stages write to clip/cull distance, do further
vertex processing stages need to pass it through?
RESOLVED: Yes. This is how it works in OpenGL.
(2) Should we have two separate GLSL behavior:
#extension GL_EXT_clip_distance : <behavior>
#extension GL_EXT_cull_distance : <behavior>
or single behavior for both:
#extension GL_EXT_clip_cull_distance : <behavior>
RESOLVED: Single behavior for both the clip/cull functionality:
#extension GL_EXT_clip_cull_distance : <behavior>
Revision History
Rev. Date Author Changes
---- -------- ------ ---------------------------------
3 03/09/16 mribble Clean up QTI names and emails.
2 03/08/16 dkoch Language consistency and cleanup pass.
Added a bunch of missing language.
1 kseth Initial draft