IMG_user_clip_plane 

GL_IMG_user_clip_plane 

Copyright Imagination Technologies Limited, 2005.

Imagination Technologies

FINAL

1.0, 11 May 2009

OpenGL ES Extension #57

The extension is written against the OpenGLES 1.0 Specification.

The OpenGL ES 1.0 Specification does not support user clip planes. This extension
adds the support for clip planes. This extension was superceded by OpenGL ES 1.1

None

None

For the COMMON profile:
    void ClipPlanefIMG( GLenum p, GLfloat eqn[4] );

For the COMMON_LITE profile:
    void ClipPlanexIMG( GLenum p, GLfixed eqn[4] );

Accepted by the <pname> parameter of GetIntegerv function: 

    MAX_CLIP_PLANES_IMG               0x0D32

Accepted by the <pname> parameter of ClipPlanef, ClipPlanex, Enable and Disable:

    CLIP_PLANE0_IMG                   0x3000
    CLIP_PLANE1_IMG                   0x3001
    CLIP_PLANE2_IMG                   0x3002
    CLIP_PLANE3_IMG                   0x3003
    CLIP_PLANE4_IMG                   0x3004
    CLIP_PLANE5_IMG                   0x3005

Additions to Chapter 2.11 of the OpenGL ES 1.0 Specification (Clipping)    

(append after the last paragraph, after: "User-specified clipping [...]")
    In the presence of IMG_user_clip_plane a number of 6 clip planes will be
    exported to the user. The clip planes will restrict the view volume by defining
    half spaces. The intersection between those half spaces and the view volume
    defined by the back and front clipping plane represents the space where the
    geometry will be clipped. To define a clip plane the application must provide
    a plane equation by calling:

        ClipPlanefIMG(enum p, float eqn[4])
        ClipPlanexIMG(enum p, fixed eqn[4])

    where p describes which clip plane is currently set, CLIP_PLANEi, and eqn are 4
    floating point values, in COMMON profile and 4 fixed values in COMMON_LITE
    profile. The equation is represented by 4 values p1, p2, p3 and p4 which are
    multiplied by the inverse of the modelview matrix transforming them into
    eye space. 

        ( p1' p2' p3' p4' ) = ( p1 p2 p3 p4 ) M^-1

    Any vertex in eye space that satisfies the mathematical inequality will not be
    clipped, becuase they are located in the positive half space of the clip plane:

        ( p1' p2' p3' p4' )  ( x y z w )^T >= 0

    Clip planes need to be enabled in order to be used and this is done using

        Enable(enum p)

    where p is one of the clip planes enumerants, CLIP_PLANEi. If geometry is drawn
    with a specific clip plane enabled without specifing the clip plane equation
    the clipping results are undefined.

    To disable a clip plane, which is to disable clipping by that plane an application
    must call

        Disable(enum p)

    where p is one of the clip planes enumerants, CLIP_PLANEi.

    Even though this extension specifies a number of 6 clip planes more can be exported
    by different implementations. To find the maximum number of clip planes exported
    an application must call

        GetIntegerv(enum p, int *params)

    Where p is MAX_CLIP_PLANES_IMG. After a call to this function <params> will contain
    the number of clip planes exported by that particular extension.

INVALID_ENUM is generated by ClipPlanefIMG, ClipPlanexIMG, Enable and Disable if the 
<pname> parameter is not one of the clip plane defines.

Get Value			    Get Command    Type    Initial Value    Attribute
---------			    -----------    ----    -------------    ---------
MAX_CLIP_PLANES_IMG      GetIntegerv    N+      6                user clip planes

An easy way to test the conformance of user clip planes is to set up an ortographic 
projection and use all clip planes, together and separate, oriented across the 3 axes
(negative and positive), and check for correct geometry clipping.

0.1, 17/2/2004 vs:  Initial revision.
0.2, 3/11/2004 bcb: Renamed entrypoints to add IMG suffix.
0.3, 25/01/2005 nt: Added copyright notice and Number paragraph placeholder.
1.0, 11/05/2009 bcb: Final cleanup for publication