skia / external / github.com / KhronosGroup / OpenGL-Registry / refs/heads/11723-workgroup / . / extensions / EXT / EXT_polygon_offset_clamp.txt

Name | |

EXT_polygon_offset_clamp | |

Name Strings | |

GL_EXT_polygon_offset_clamp | |

Contact | |

Eric Lengyel (lengyel 'at' terathon.com) | |

Contributors | |

Eric Lengyel, Terathon Software | |

Tobias Hector, Imagination Technologies | |

Status | |

Complete. | |

Version | |

Last Modified Date: February 11, 2016 | |

Revision: 4 | |

Number | |

OpenGL Extension #460 | |

OpenGL ES Extension #252 | |

Dependencies | |

OpenGL 3.3 (either core or compatibility profiles), or OpenGL ES 1.0 is | |

required. | |

This extension is written against the OpenGL 3.3 (Core Profile) | |

Specification (March 11, 2010) and the OpenGL ES 3.1 Specification (October | |

29, 2014). | |

Overview | |

This extension adds a new parameter to the polygon offset function | |

that clamps the calculated offset to a minimum or maximum value. | |

The clamping functionality is useful when polygons are nearly | |

parallel to the view direction because their high slopes can result | |

in arbitrarily large polygon offsets. In the particular case of | |

shadow mapping, the lack of clamping can produce the appearance of | |

unwanted holes when the shadow casting polygons are offset beyond | |

the shadow receiving polygons, and this problem can be alleviated by | |

enforcing a maximum offset value. | |

IP Status | |

No known IP claims. | |

New Procedures and Functions | |

void PolygonOffsetClampEXT(float factor, float units, float clamp); | |

New Tokens | |

Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, | |

GetInteger64v, GetFloatv, and GetDoublev: | |

POLYGON_OFFSET_CLAMP_EXT 0x8E1B | |

Additions to Chapter 3 of the OpenGL 3.3 (Core Profile) Specification | |

(Rasterization), and Chapter 13 of the OpenGL ES Specification (Polygons) | |

-- Modify Open GL section 3.6.4 and OpenGL ES section 13.5.2, "Depth Offset" | |

Replace the 1st paragraph... | |

"The depth values of all fragments generated by the rasterization of | |

a polygon may be offset by a single value that is computed for that | |

polygon. The function that determines this value is specified with | |

the commands | |

void PolygonOffsetClampEXT(float factor, float units, float clamp); | |

void PolygonOffset(float factor, float units); | |

<factor> scales the maximum depth slope of the polygon, and <units> | |

scales an implementation-dependent constant that relates to the | |

usable resolution of the depth buffer. The resulting values are | |

summed to produce the polygon offset value, which may then be | |

clamped to a minimum or maximum value specified by <clamp>. The | |

values <factor>, <units>, and <clamp> may each be positive, | |

negative, or zero. Calling the command PolygonOffset is equivalent | |

to calling the command PolygonOffsetClampEXT with <clamp> equal to | |

zero." | |

Replace the 5th paragraph... | |

"The offset value o for a polygon is | |

_ | |

| m x <factor> + r x <units>, if <clamp> = 0 or NaN; | |

| | |

o = < min(m x <factor> + r x <units>, <clamp>), if <clamp> > 0; | |

| | |

|_ max(m x <factor> + r x <units>, <clamp>), if <clamp> < 0. | |

m is computed as described above. If the depth buffer uses a fixed- | |

point representation, m is a function of depth values in the range | |

[0, 1], and o is applied to depth values in the same range." | |

Additions to the AGL/EGL/GLX/WGL Specifications | |

None | |

GLX Protocol | |

A new GL rendering command is added. The following command is sent | |

to the server as part of a glXRender request: | |

PolygonOffsetClampEXT | |

2 16 rendering command length | |

2 4225 rendering command opcode | |

4 FLOAT32 factor | |

4 FLOAT32 units | |

4 FLOAT32 clamp | |

Errors | |

None | |

New State (OpenGL) | |

Get Value Type Get Command Initial Value Description Sec Attrib | |

------------------------ ---- ----------- ------------- -------------------- ----- ------- | |

POLYGON_OFFSET_CLAMP_EXT R GetFloatv 0 Polygon offset clamp 3.6.4 polygon | |

New State (OpenGL ES) | |

Add the following to Table 20.6: Rasterization | |

Get Value Type Get Command Initial Value Description Sec | |

------------------------ ---- ----------- ------------- -------------------- ------ | |

POLYGON_OFFSET_CLAMP_EXT R GetFloatv 0 Polygon offset clamp 13.5.2 | |

New Implementation Dependent State | |

None | |

Issues | |

1) Should the PolygonOffsetClampEXT command specify only the <clamp> | |

parameter, or should it specify all three of the parameters | |

<factor>, <units>, and <clamp>? | |

Defining a new command that specifies new state in addition to | |

state that can be specified with an existing command has a | |

precedent in the BlendFuncSeparate command. The argument can be | |

made that an application would usually want to set the <factor> | |

and <units> values at the same time it sets the <clamp> value, | |

and making one GL call is better than making two GL calls. | |

Furthermore, requiring that a call to PolygonOffset sets | |

POLYGON_OFFSET_CLAMP_EXT to zero insulates applications unaware | |

of the new state from failures to restore it to its initial | |

value in separate libraries, and this cannot be done if an | |

orthogonal command specifying only the <clamp> value were to be | |

defined. | |

RESOLVED: This extension defines a new command that specifies | |

the <factor>, <units>, and <clamp> parameters. | |

2) What happens if <clamp> is infinity or NaN? | |

As per Section 2.1, the result of providing an infinity or NaN | |

is unspecified. However, if <clamp> is positive or negative | |

infinity, then Equation (3.13), in the literal mathematical | |

sense, is effectively reduced to the case in which no clamping | |

occurs, and this should be the defined behavior. | |

If <clamp> is a floating-point NaN, then we could leave the | |

result undefined, but that could lead to application code | |

working correctly with one implementation and then inexplicably | |

failing with another. It would be better to define the behavior | |

such that no clamping occurs. If this is not the behavior | |

exhibited by the hardware, then the implementation can turn all | |

infinites and NaNs into zero using the following code: | |

int32_t clampBits = *(int32_t *) &clamp; | |

clampBits &= (((clampBits >> 23) & 0xFF) - 0xFF) >> 31; | |

This ANDs with all one bits if and only if the floating-point | |

exponent is less than 255. Otherwise, it ANDs with all zero | |

bits. (This assumes a well-defined right shift of negative | |

integers.) | |

RESOLVED: If <clamp> is infinity or NaN, then no clamping is | |

applied to the polygon offset. | |

3) What happens if <clamp> is a denormalized floating-point value? | |

As per Section 2.1, the result of providing a denormalized value | |

must yield predictable results. However, some implementations | |

may treat denormalized values as equal to zero, and other | |

implementations may treat them as greater than or less than | |

zero. To ensure uniform behavior across all implementations, we | |

can require that denormalized values not be equal to zero. This | |

may necessitate that implementations convert denormalized values | |

to the smallest representable normalized value with the same | |

sign. | |

RESOLVED: Denormalized values are not considered equal to zero | |

in Equation (3.13). | |

Revision History | |

Rev. Date Author Changes | |

---- -------- --------- ------------------------------------------ | |

4 02/11/16 thector Fixed an incorrect vendor suffix (was IMG) | |

3 10/21/15 thector Added OpenGL ES interactions. | |

2 08/27/14 elengyel Added enum value for new token, resolved | |

issues, changed status to complete. | |

1 08/14/14 elengyel Initial draft. |