Name

    IMG_user_clip_plane 

Name Strings

    GL_IMG_user_clip_plane 

Notice

    Copyright Imagination Technologies Limited, 2005.

Contact

    Imagination Technologies

Status

    FINAL

Version

    1.0, 11 May 2009

Number

    OpenGL ES Extension #57

Dependencies

    The extension is written against the OpenGLES 1.0 Specification.
 
Overview

    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

IP Status

    None

Issues

    None

New Procedures and Functions

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

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


New Tokens

    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 OpenGLES 1.0 Specification 

    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.

Errors

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

New State

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

Conformance Testing

    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.

Revision History
    
    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