blob: 8f899b9b21e8cc35f0213945caa5ed5bbf4e72d3 [file] [log] [blame]
Name
ARB_cull_distance
Name Strings
GL_ARB_cull_distance
Contact
Brian Paul, VMware Inc. (brianp 'at' vmware.com)
Contributors
Brian Paul, VMware
Daniel Rakos, AMD
Pat Brown, NVIDIA
Piers Daniell, NVIDIA
Notice
Copyright (c) 2014 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the ARB on June 26, 2014.
Ratified by the Khronos Board of Promoters on August 7, 2014.
Version
Date: June 17, 2014
Revision: 9
Number
ARB Extension #162
Dependencies
OpenGL 3.0 is required.
The extension is written against the OpenGL 4.4 Specification, Core
Profile, March 19, 2014.
The extension is written against the OpenGL Shading Language 4.40
Specification, January 22, 2014.
Overview
This extension adds a new GLSL gl_CullDistance shader output, similar
to gl_ClipDistance, but used for whole primitive culling.
This new stage in the pipeline is added as part of the primitive clipping
stage.
IP Status
No known IP claims.
New Procedures and Functions
None
New Types
None
New Tokens
Accepted by the <pname> parameter of GetBooeleanv, GetDoublev, GetFloatv
GetIntegerv, and GetInteger64v:
MAX_CULL_DISTANCES 0x82F9
MAX_COMBINED_CLIP_AND_CULL_DISTANCES 0x82FA
Additions to Chapter 7 of the OpenGL 4.4 (Core Profile) Specification (Programs and Shaders)
Modify Section 7.4.1, Shader Interface Matching
(modify last sentence of third paragraph on p. 112)
If either shader redeclares the built-in array gl_CullDistance[] or
gl_ClipDistance[], the array must have the same size in both shaders.
Additions to Chapter 11 of the OpenGL 4.4 (Core Profile) Specification (Programmable Vertex Processing)
Modify Section 11.1.3.10, Shader Outputs
(replace the first sentence of the third paragraph on p. 358)
The built-in output variables gl_ClipDistance and glCullDistance hold the
clip distance(s) and cull distance(s), respectively, used in the culling
stage, as described in section 13.5.
Modify Section 11.2.1.2.2, Tessellation Control Shader Inputs
(modify last sentence of first paragraph on p. 365)
The members of each element of the gl_in array are gl_Position,
gl_PointSize, gl_ClipDistance, gl_CullDistance, and gl_ClipVertex.
Modify Section 11.2.1.2.3, Tessellation Control Shader Outputs
(modify last sentence of first paragraph on p. 366)
The members of each element of the gl_out array are gl_Position,
gl_PointSize, gl_ClipDistance, and gl_CullDistance, and behave identically
to equivalently named vertex shader outputs (section 11.1.3).
Modify Section 11.2.3.3, Tessellation Evaluation Shader Inputs
(modify last sentence of first paragraph on p. 380)
The members of each element of the gl_in array are gl_Position,
gl_PointSize, gl_ClipDistance, and gl_CullDistance.
Modify Section 11.2.3.4, Tessellation Evaluation Shader Ouputs
(modify last sentence of first paragraph on p. 381)
These variables are gl_Position, gl_PointSize, gl_ClipDistance, and
gl_CullDistance, and all behave identically to equivalently named vertex
shader outputs (see section 11.1.3).
Modify Section 11.3.4.4, Geometry Shader Inputs
(add after first bullet in first paragraph on p. 387)
* Structure member gl_CullDistance[] holds the per-vertex array of cull
distances, as written by the vertex shader to its built-in output
variable gl_CullDistance[].
Modify Section 11.3.4.5, Geometry Shader Outputs
(replace second paragraph on p. 389)
The built-in outputs gl_ClipDistance and gl_CullDistance hold the clip
distance(s) and cull distance(s), respectively, used in the clipping
stage, as described in section 13.5.
Additions to Chapter 13 of the OpenGL 4.4 (Core Profile) Specification (Fixed-Function Vertex Post-Processing)
Modify Section 13.5, Primitive Clipping
(replace first sentence of first paragraph on p. 404)
Primitives are culled against the cull volume and then clipped against the
clip volume.
(replace the second, third, and fourth paragraph on p. 404)
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, and maybe determined by calling GetIntegerv with the
symbolic constant MAX_COMBINED_CLIP_AND_CULL_DISTANCES.
The cull volume is the intersection of up to MAX_CULL_DISTANCES 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 that
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 MAX_CLIP_DISTANCES client-
defined half-spaces with the view volume (if no client-defined clip half-
spaces are enabled, the clip volume is the view volume). Client-defined
clip half-spaces are enabled or disabled by calling Enable or Disable with
<target> CLIP_DISTANCE<i>, 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> =
CLIP_DISTANCE0 + <i>.
A shader may write a single clip distance for each enabled clip half-space
to elements of the gl_ClipDistance[] array. Clip half-space <i> is then
given by the set of points satisfying the inequality
c[i](P) >= 0,
where c[i](P) is the value of clip distance <i> at point P. For point
primitives, c[i](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 14.5 and 14.6.
Depth clamping ...
Additions to the OpenGL Shading Language
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_ARB_cull_distance : <behavior>
where <behavior> is as specified in section 3.3.
New preprocessor #define is added to the OpenGL Shading Language:
#define GL_ARB_cull_distance 1
Additions to Chapter 7 of the OpenGL Shading Language 4.40 Specification (Built-in Variables)
Modify Section 7.1, Built-In Language Variables
(add a new field to the end of the declaration of "gl_PerVertex" for
all language input and output blocks on p. 120-122)
float gl_CullDistance[];
(add new declaration to the built-in variables available in the fragment
language on p. 122)
in float gl_CullDistance[];
(add after second paragraph on p. 124)
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.1.1, Compatibility Profile Built-In Language Variables
(modify last sentence on p. 128)
It is a compile-time or link-time error for the set of shaders forming
a program to statically read or write both gl_ClipVertex and
either gl_ClipDistance or gl_CullDistance.
Modify Section 7.3, Built-In Constants
(add to the list of implementation-dependent constants after
gl_MaxClipDistances on p. 132)
const int gl_MaxCullDistances = 8;
const int gl_MaxCombinedClipAndCullDistances = 8;
Additions to the AGL/EGL/GLX/WGL Specifications
None
Errors
None
New State
None.
New Implementation Dependent State
(add to table 23.53, Implementation Dependent Values)
Get Value Type Get Command Minimum value Description Sec.
------------------------------------ ---- ----------- ------------- --------------------------------- ----
MAX_CULL_DISTANCES Z+ GetIntegerv 8 Max no. of user culling planes 13.5
MAX_COMBINED_CLIP_AND_CULL_DISTANCES Z+ GetIntegerv 8 Max combined no. of user clipping 13.5
and culling planes
Issues
(1) Why is this extension necessary?
RESOLVED: This feature is supported by a competing graphics API. One
could implement some of this functionality with a geometry shader but
that doesn't work well in all circumstances, or is very difficult.
(2) Should there be enable flags for cull distances as there are for
clip distances?
RESOLVED: The clip plane enables still exist for OpenGL 4.4 core
profile, but they are mostly there because of backwards compatibility
reasons. The proposal is to not have separate enables for cull
distances, instead usage in the shader should determine this.
(3) How many cull distances are supported?
RESOLVED: Eight. But as resources used by cull distances and clip
distances may be aliased on some implementations we also introduce a
combined resource limit of eight.
(4) How do we determine the number of enabled cull distances?
RESOLVED: Redeclaring the gl_CullDistance array with a size of <n>
automatically enables the first <n> cull distances.
(5) Which shader stage determines the number of enabled cull distances in
case multiple shader stages redeclare gl_CullDistance?
RESOLVED: The implicit or explicit size of gl_CullDistance in the
very last shader stage before rasterization determines the number
of enabled cull distances.
(6) How should we validate that we don't go over resource limits?
RESOLVED: There is an implicit or explicit size for both
gl_ClipDistance and gl_CullDistance in the shader. If the sum of the
sizes of the two arrays is over MAX_COMBINED_CLIP_AND_CULL_DISTANCES
it results in a compile-time or link-time error.
(7) Should there be a built-in gl_CullDistance in the fragment language?
RESOLVED: Yes, just like gl_ClipDistance is available in the fragment
language.
Revision History
Revision 9, 2014/06/17 (Daniel Rakos)
- Added missing tokens.
Revision 8, 2014/06/06 (Daniel Rakos)
- Resolved issues (5) and (7).
- Clarified language describing the number of enabled cull distances.
Revision 7, 2014/05/30 (Daniel Rakos)
- Resolved issues (2), (3), (4), and (6).
Revision 6, 2014/05/22 (Daniel Rakos)
- Minor language cleanup.
Revision 5, 2014/05/19 (Daniel Rakos)
- Added language to explicitly disallow the use of gl_ClipVertex and
gl_CullDistance at the same time.
Revision 4, 2014/05/16 (Daniel Rakos)
- Added missing language about #extension and #define for the feature.
Revision 3, 2014/04/25 (Daniel Rakos)
- Renamed to ARB_cull_distance.
- Added implementation-dependent states MAX_CULL_DISTANCES and
MAX_COMBINED_CLIP_AND_CULL_DISTANCES.
- Rewrote language based on discussion.
- Added issues (3) to (7).
Revision 2, 2014/04/10 (Brian Paul)
- Fleshed out edits to chapter 13 of the spec.
- Added issue (2).
Revision 1, 2014/02/03 (Brian Paul)
- Initial revision.