1Name
2
3    EXT_polygon_offset_clamp
4
5Name Strings
6
7    GL_EXT_polygon_offset_clamp
8
9Contact
10
11    Eric Lengyel (lengyel 'at' terathon.com)
12
13Contributors
14
15    Eric Lengyel, Terathon Software
16    Tobias Hector, Imagination Technologies
17
18Status
19
20    Complete.
21
22Version
23
24    Last Modified Date: February 11, 2016
25    Revision: 4
26
27Number
28
29    OpenGL Extension #460
30    OpenGL ES Extension #252
31
32Dependencies
33
34    OpenGL 3.3 (either core or compatibility profiles), or OpenGL ES 1.0 is
35    required.
36
37    This extension is written against the OpenGL 3.3 (Core Profile)
38    Specification (March 11, 2010) and the OpenGL ES 3.1 Specification (October
39    29, 2014).
40
41Overview
42
43    This extension adds a new parameter to the polygon offset function
44    that clamps the calculated offset to a minimum or maximum value.
45    The clamping functionality is useful when polygons are nearly
46    parallel to the view direction because their high slopes can result
47    in arbitrarily large polygon offsets. In the particular case of
48    shadow mapping, the lack of clamping can produce the appearance of
49    unwanted holes when the shadow casting polygons are offset beyond
50    the shadow receiving polygons, and this problem can be alleviated by
51    enforcing a maximum offset value.
52
53IP Status
54
55    No known IP claims.
56
57New Procedures and Functions
58
59    void PolygonOffsetClampEXT(float factor, float units, float clamp);
60
61New Tokens
62
63    Accepted by the <pname> parameters of GetBooleanv, GetIntegerv,
64    GetInteger64v, GetFloatv, and GetDoublev:
65
66        POLYGON_OFFSET_CLAMP_EXT                0x8E1B
67
68Additions to Chapter 3 of the OpenGL 3.3 (Core Profile) Specification
69(Rasterization), and Chapter 13 of the OpenGL ES Specification (Polygons)
70
71 -- Modify Open GL section 3.6.4 and OpenGL ES section 13.5.2, "Depth Offset"
72
73    Replace the 1st paragraph...
74
75    "The depth values of all fragments generated by the rasterization of
76    a polygon may be offset by a single value that is computed for that
77    polygon. The function that determines this value is specified with
78    the commands
79
80     void PolygonOffsetClampEXT(float factor, float units, float clamp);
81     void PolygonOffset(float factor, float units);
82
83    <factor> scales the maximum depth slope of the polygon, and <units>
84    scales an implementation-dependent constant that relates to the
85    usable resolution of the depth buffer. The resulting values are
86    summed to produce the polygon offset value, which may then be
87    clamped to a minimum or maximum value specified by <clamp>. The
88    values <factor>, <units>, and <clamp> may each be positive,
89    negative, or zero. Calling the command PolygonOffset is equivalent
90    to calling the command PolygonOffsetClampEXT with <clamp> equal to
91    zero."
92
93    Replace the 5th paragraph...
94
95    "The offset value o for a polygon is
96          _
97         |   m x <factor> + r x <units>,          if <clamp> = 0 or NaN;
98         |
99    o = <    min(m x <factor> + r x <units>, <clamp>),   if <clamp> > 0;
100         |
101         |_  max(m x <factor> + r x <units>, <clamp>),   if <clamp> < 0.
102
103    m is computed as described above. If the depth buffer uses a fixed-
104    point representation, m is a function of depth values in the range
105    [0, 1], and o is applied to depth values in the same range."
106
107Additions to the AGL/EGL/GLX/WGL Specifications
108
109    None
110
111GLX Protocol
112
113    A new GL rendering command is added. The following command is sent
114    to the server as part of a glXRender request:
115
116        PolygonOffsetClampEXT
117            2           16              rendering command length
118            2           4225            rendering command opcode
119            4           FLOAT32         factor
120            4           FLOAT32         units
121            4           FLOAT32         clamp
122
123Errors
124
125    None
126
127New State (OpenGL)
128
129    Get Value                Type  Get Command  Initial Value  Description           Sec    Attrib
130    ------------------------ ----  -----------  -------------  --------------------  -----  -------
131    POLYGON_OFFSET_CLAMP_EXT  R    GetFloatv          0        Polygon offset clamp  3.6.4  polygon
132
133New State (OpenGL ES)
134
135    Add the following to Table 20.6: Rasterization
136
137    Get Value                Type  Get Command  Initial Value  Description           Sec
138    ------------------------ ----  -----------  -------------  --------------------  ------
139    POLYGON_OFFSET_CLAMP_EXT  R    GetFloatv          0        Polygon offset clamp  13.5.2
140
141New Implementation Dependent State
142
143    None
144
145Issues
146
147    1)  Should the PolygonOffsetClampEXT command specify only the <clamp>
148        parameter, or should it specify all three of the parameters
149        <factor>, <units>, and <clamp>?
150
151        Defining a new command that specifies new state in addition to
152        state that can be specified with an existing command has a
153        precedent in the BlendFuncSeparate command. The argument can be
154        made that an application would usually want to set the <factor>
155        and <units> values at the same time it sets the <clamp> value,
156        and making one GL call is better than making two GL calls.
157        Furthermore, requiring that a call to PolygonOffset sets
158        POLYGON_OFFSET_CLAMP_EXT to zero insulates applications unaware
159        of the new state from failures to restore it to its initial
160        value in separate libraries, and this cannot be done if an
161        orthogonal command specifying only the <clamp> value were to be
162        defined.
163
164        RESOLVED: This extension defines a new command that specifies
165        the <factor>, <units>, and <clamp> parameters.
166
167    2)  What happens if <clamp> is infinity or NaN?
168
169        As per Section 2.1, the result of providing an infinity or NaN
170        is unspecified. However, if <clamp> is positive or negative
171        infinity, then Equation (3.13), in the literal mathematical
172        sense, is effectively reduced to the case in which no clamping
173        occurs, and this should be the defined behavior.
174
175        If <clamp> is a floating-point NaN, then we could leave the
176        result undefined, but that could lead to application code
177        working correctly with one implementation and then inexplicably
178        failing with another. It would be better to define the behavior
179        such that no clamping occurs. If this is not the behavior
180        exhibited by the hardware, then the implementation can turn all
181        infinites and NaNs into zero using the following code:
182
183            int32_t clampBits = *(int32_t *) &clamp;
184            clampBits &= (((clampBits >> 23) & 0xFF) - 0xFF) >> 31;
185
186        This ANDs with all one bits if and only if the floating-point
187        exponent is less than 255. Otherwise, it ANDs with all zero
188        bits. (This assumes a well-defined right shift of negative
189        integers.)
190
191        RESOLVED: If <clamp> is infinity or NaN, then no clamping is
192        applied to the polygon offset.
193
194    3)  What happens if <clamp> is a denormalized floating-point value?
195
196        As per Section 2.1, the result of providing a denormalized value
197        must yield predictable results. However, some implementations
198        may treat denormalized values as equal to zero, and other
199        implementations may treat them as greater than or less than
200        zero. To ensure uniform behavior across all implementations, we
201        can require that denormalized values not be equal to zero. This
202        may necessitate that implementations convert denormalized values
203        to the smallest representable normalized value with the same
204        sign.
205
206        RESOLVED: Denormalized values are not considered equal to zero
207        in Equation (3.13).
208
209Revision History
210
211    Rev.    Date    Author     Changes
212    ----  -------- ---------  ------------------------------------------
213    4     02/11/16  thector    Fixed an incorrect vendor suffix (was IMG)
214    3     10/21/15  thector    Added OpenGL ES interactions.
215    2     08/27/14  elengyel   Added enum value for new token, resolved
216                               issues, changed status to complete.
217    1     08/14/14  elengyel   Initial draft.
218