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 parameter of GetIntegerv function: MAX_CLIP_PLANES_IMG 0x0D32 Accepted by the 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 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 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