EXT_clip_control

GL_EXT_clip_control

Chad Versace, Google <chadversary@google.com>

David Reveman, Google <reveman@google.com>
Daniel Koch, NVIDIA
See also GL_ARB_clip_control.

Copyright (c) 2017 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

Complete

Last Modified Date: 2017-10-10
Revision: 2

OpenGL ES Extension #290

Requires OpenGL ES 2.0.

This extension is written against the OpenGL ES 3.2 Specification.

This extension provides additional clip control modes to configure how
clip space is mapped to window space.  This extension's goal is to 1)
allow OpenGL to effectively match Direct3D's coordinate system
conventions, and 2) potentially improve the numerical precision of the Z
coordinate mapping.

This extension is a port of GL_ARB_clip_control to OpenGL ES. For the
complete overview of this extension, refer to the "Overview" section of
GL_ARB_clip_control.

Append the EXT suffix to all new symbols.

Remove references to features not found in OpenGL ES 3.2: DEPTH_CLAMP and
and Begin/End,

Renumber sections to match the OpenGL ES 3.2 Specification.

void ClipControlEXT(enum origin, enum depth);

Accepted by the <origin> parameter of ClipControlEXT:

    LOWER_LEFT_EXT                              0x8CA1
    UPPER_LEFT_EXT                              0x8CA2

Accepted by the <depth> parameter of ClipControlEXT:

    NEGATIVE_ONE_TO_ONE_EXT                     0x935E
    ZERO_TO_ONE_EXT                             0x935F

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

    CLIP_ORIGIN_EXT                             0x935C
    CLIP_DEPTH_MODE_EXT                         0x935D

Insert before the 1st paragraph:

"The command

    ClipControlEXT(enum origin, enum depth);

controls the clipping volume behavior.  /origin/ must be either
LOWER_LEFT_EXT or UPPER_LEFT_EXT, otherwise the error INVALID_ENUM is
generated.  /depth/ must be either NEGATIVE_ONE_TO_ONE_EXT or
ZERO_TO_ONE_EXT, otherwise the error INVALID_ENUM is generated.

  These parameters update the clip control origin and
depth mode respectively.  The state required for clip control is one
bit for clip control origin and one bit for clip control depth mode.
The initial value of the clip control origin is LOWER_LEFT_EXT and the
initial value of the depth mode is NEGATIVE_ONE_TO_ONE_EXT.

Replace the first paragraph with:

"Primitives are clipped to the clip volume. In clip coordinates,
the view volume is defined by

    -w_c <= x_c <= w_c
    -w_c <= y_c <= w_c
     z_m <= z_c <= w_c

 where z_m is -w_c when the clip control depth mode is
 NEGATIVE_ONE_TO_ONE_EXT and z_m is 0 when the mode is ZERO_TO_ONE_EXT."

Replace the 3rd paragraph with (where ^T means transpose):

"If a vertex in clip coordinates is given by (x_c y_c z_c w_c)^T
then the vertex's normalized device coordinates are (x_d y_d z_d)^T =
(x_c/w_c f*y_c/w_c z_c/w_c)^T where /f/ is +1 when the clip control
origin is LOWER_LEFT_EXT and -1 when the origin is UPPER_LEFT_EXT."

Replace the 2nd sentence of the 1st paragraph with (where ^T means
transpose):

"The vertex's window coordinates, (x_w y_w z_w)^T are given by:

    ( x_w )     ( p_x/2 x_d + o_x )
    ( y_w )  =  ( p_y/2 y_d + o_y )
    ( z_w )     (     s z_d + b   )

where s is (f-n)/2 and b is (n+f)/2 when the clip control depth mode
is NEGATIVE_ONE_TO_ONE_EXT; or s is (f-n) and b is n when the mode
is ZERO_TO_ONE_EXT."

Replace the 3rd sentence of the 1st paragraph with:

"One way to compute this area is

           n-1
           ___
           \
  a = 1/2 f \  x^i_w * y^i(+)1_w - x^i(+)1_w * y^i_w
            /
           /__

where f is +1 when the clip control origin is LOWER_LEFT_EXT and -1 when
the origin is UPPER_LEFT_EXT, x^i_w and y^i_w are the x and y window
coordinates of the ith vertex of the n-vertex polygon (vertices
are numbered starting at zero for purposes of this computation),
and i(+)1 is (i+1) mod n."

The error INVALID_ENUM is generated by ClipControlEXT if origin is not
LOWER_LEFT_EXT or UPPER_LEFT_EXT.

The error INVALID_ENUM is generated by ClipControlEXT if depth is not
NEGATIVE_ONE_TO_ONE_EXT or ZERO_TO_ONE_EXT.

Get Value            Type  Get Command  Initial Value            Description      Sec
-------------------  ----  -----------  -----------------------  ---------------  ----
CLIP_ORIGIN_EXT        Z2  GetIntegerv  LOWER_LEFT_EXT           Clip origin      12.4
CLIP_DEPTH_MODE_EXT    Z2  GetIntegerv  NEGATIVE_ONE_TO_ONE_EXT  Clip depth mode  12.4

See the issue list in GL_ARB_clip_control.

1. 2017-08-08 (Chad Versace)
    - First draft. Port of GL_ARB_clip_control to OpenGL ES.
2. 2017-10-10 (Daniel Koch)
    - Added some missing EXT suffixes, remove mention of GetDoublev