xref: /third_party/openGLES/extensions/EXT/EXT_polygon_offset.txt

Name

    EXT_polygon_offset

Name String

    GL_EXT_polygon_offset

Version

    $Date: 1995/06/17 03:34:49 $ $Revision: 1.12 $

Number

    3

Dependencies

    None

Overview

    The depth values of fragments generated by rendering polygons are
    displaced by an amount that is proportional to the maximum absolute
    value of the depth slope of the polygon, measured and applied in window
    coordinates.  This displacement allows lines (or points) and polygons
    in the same plane to be rendered without interaction -- the lines
    rendered either completely in front of or behind the polygons
    (depending on the sign of the offset factor).  It also allows multiple
    coplanar polygons to be rendered without interaction, if different
    offset factors are used for each polygon.  Applications include
    rendering hidden-line images, rendering solids with highlighted edges,
    and applying `decals' to surfaces.

New Procedures and Functions

    void PolygonOffsetEXT(float factor,
                          float bias);

New Tokens

    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, and
    by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
    GetDoublev:

        POLYGON_OFFSET_EXT               0x8037

    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
    GetFloatv, and GetDoublev:

        POLYGON_OFFSET_FACTOR_EXT        0x8038
        POLYGON_OFFSET_BIAS_EXT          0x8039

Additions to Chapter 2 of the GL Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the GL Specification (Rasterization)

    The changes to the GL Specification are limited to the description of
    polygon rasterization, specifically while the polygon mode (specified
    by calling PolygonMode) is FILL.  The GL Specification requires that
    fragment Z values during such rasterization be computed using the
    equation


        Z = (a * Za) + (b * Zb) + (c * Zc)


    where a, b, and c are the barycentric coordinates of the fragment
    center, and Za, Zb, and Zc are the Z values of the triangle's vertices.
    When POLYGON_OFFSET_EXT is enabled, this extension modifies this
    equation as follows:


        Z' = (a * Za) + (b * Zb) + (c * Zc) + (factor * maxdZ) + bias


             / 0        Z' < 0
        Z = <  Z'       0 <= Z' <= 1
             \ 1        Z' > 1


    where factor and bias are the polygon offset factor and bias as
    specified by PolygonOffsetEXT, and maxdZ is the maximum positive change
    in Z for a unit-step in the X,Y plane.  MaxdZ can be approximated as
    the larger of the absolute values of dZ/dX and dZ/dY, the rates of
    change of Z in the positive X and Y directions.  The equations for
    maxdZ, dZ/dX, and dZ/dY are:


                             2         2
        maxdZ = sqrt[ (dZ/dX) + (dZ/dY) ]


                ((Yc - Yb) * (Zb - Za)) - ((Yb - Ya) * (Zc - Zb))
        dZ/dX = -------------------------------------------------
                                       area


                ((Xb - Xa) * (Zc - Zb)) - ((Xc - Xb) * (Zb - Za))
        dZ/dY = -------------------------------------------------
                                       area


        area = ((Xb - Xa) * (Yc - Yb)) - ((Xc - Xb) * (Yb - Ya))


    To simplify the calculations, maxdZ may be approximated by


        maxdZ = maximum( |dZ/dX| , |dZ/dY| )


    Note that all these equations treat window coordinate Z values as
    ranging from 0.0 through 1.0, regardless of their actual representation
    (refer to Controlling the Viewport in Chapter 2 of the GL Specification).

    POLYGON_OFFSET_EXT is enabled and disabled using Enable and Disable with
    parameter <cap> specified as POLYGON_OFFSET_EXT.

Additions to Chapter 4 of the GL Specification (Per-Fragment Operations
and the Framebuffer)

    None

Additions to Chapter 5 of the GL Specification (Special Functions)

    None

Additions to Chapter 6 of the GL Specification (State and State Requests)

    None

Additions to the GLX Specification

    None

GLX Protocol

    A new GL rendering command is added. The following command is sent to the 
    server as part of a glXRender request:


        PolygonOffsetEXT
            2           12              rendering command length
            2           4098            rendering command opcode
            4           FLOAT32         factor
            4           FLOAT32         bias

Errors

    INVALID_OPERATION is generated if PolygonOffsetEXT is called between
    execution of Begin and the corresponding execution of End.

New State

                                                        Initial
    Get Value                   Get Command     Type    Value   Attrib
    ---------                   -----------     ----    ------- ------
    POLYGON_OFFSET_EXT          IsEnabled       B       False   polygon/enable
    POLYGON_OFFSET_FACTOR_EXT   GetFloatv       R       0       polygon
    POLYGON_OFFSET_BIAS_EXT     GetFloatv       R       0       polygon

New Implementation Dependent State

    None