• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    IMG_user_clip_plane
4
5Name Strings
6
7    GL_IMG_user_clip_plane
8
9Notice
10
11    Copyright Imagination Technologies Limited, 2005.
12
13Contact
14
15    Imagination Technologies
16
17Status
18
19    FINAL
20
21Version
22
23    1.0, 11 May 2009
24
25Number
26
27    OpenGL ES Extension #57
28
29Dependencies
30
31    The extension is written against the OpenGLES 1.0 Specification.
32
33Overview
34
35    The OpenGL ES 1.0 Specification does not support user clip planes. This extension
36    adds the support for clip planes. This extension was superceded by OpenGL ES 1.1
37
38IP Status
39
40    None
41
42Issues
43
44    None
45
46New Procedures and Functions
47
48    For the COMMON profile:
49        void ClipPlanefIMG( GLenum p, GLfloat eqn[4] );
50
51    For the COMMON_LITE profile:
52        void ClipPlanexIMG( GLenum p, GLfixed eqn[4] );
53
54
55
56New Tokens
57
58    Accepted by the <pname> parameter of GetIntegerv function:
59
60        MAX_CLIP_PLANES_IMG               0x0D32
61
62    Accepted by the <pname> parameter of ClipPlanef, ClipPlanex, Enable and Disable:
63
64        CLIP_PLANE0_IMG                   0x3000
65        CLIP_PLANE1_IMG                   0x3001
66        CLIP_PLANE2_IMG                   0x3002
67        CLIP_PLANE3_IMG                   0x3003
68        CLIP_PLANE4_IMG                   0x3004
69        CLIP_PLANE5_IMG                   0x3005
70
71
72
73Additions to OpenGLES 1.0 Specification
74
75    Additions to Chapter 2.11 of the OpenGL ES 1.0 Specification (Clipping)
76
77	(append after the last paragraph, after: "User-specified clipping [...]")
78        In the presence of IMG_user_clip_plane a number of 6 clip planes will be
79        exported to the user. The clip planes will restrict the view volume by defining
80        half spaces. The intersection between those half spaces and the view volume
81        defined by the back and front clipping plane represents the space where the
82        geometry will be clipped. To define a clip plane the application must provide
83        a plane equation by calling:
84
85            ClipPlanefIMG(enum p, float eqn[4])
86            ClipPlanexIMG(enum p, fixed eqn[4])
87
88        where p describes which clip plane is currently set, CLIP_PLANEi, and eqn are 4
89        floating point values, in COMMON profile and 4 fixed values in COMMON_LITE
90        profile. The equation is represented by 4 values p1, p2, p3 and p4 which are
91        multiplied by the inverse of the modelview matrix transforming them into
92        eye space.
93
94            ( p1' p2' p3' p4' ) = ( p1 p2 p3 p4 ) M^-1
95
96        Any vertex in eye space that satisfies the mathematical inequality will not be
97        clipped, becuase they are located in the positive half space of the clip plane:
98
99            ( p1' p2' p3' p4' )  ( x y z w )^T >= 0
100
101        Clip planes need to be enabled in order to be used and this is done using
102
103            Enable(enum p)
104
105        where p is one of the clip planes enumerants, CLIP_PLANEi. If geometry is drawn
106        with a specific clip plane enabled without specifing the clip plane equation
107        the clipping results are undefined.
108
109        To disable a clip plane, which is to disable clipping by that plane an application
110        must call
111
112            Disable(enum p)
113
114        where p is one of the clip planes enumerants, CLIP_PLANEi.
115
116        Even though this extension specifies a number of 6 clip planes more can be exported
117        by different implementations. To find the maximum number of clip planes exported
118        an application must call
119
120            GetIntegerv(enum p, int *params)
121
122        Where p is MAX_CLIP_PLANES_IMG. After a call to this function <params> will contain
123        the number of clip planes exported by that particular extension.
124
125Errors
126
127    INVALID_ENUM is generated by ClipPlanefIMG, ClipPlanexIMG, Enable and Disable if the
128    <pname> parameter is not one of the clip plane defines.
129
130New State
131
132    Get Value			    Get Command    Type    Initial Value    Attribute
133    ---------			    -----------    ----    -------------    ---------
134    MAX_CLIP_PLANES_IMG      GetIntegerv    N+      6                user clip planes
135
136
137Conformance Testing
138
139    An easy way to test the conformance of user clip planes is to set up an ortographic
140    projection and use all clip planes, together and separate, oriented across the 3 axes
141    (negative and positive), and check for correct geometry clipping.
142
143Revision History
144
145    0.1, 17/2/2004 vs:  Initial revision.
146    0.2, 3/11/2004 bcb: Renamed entrypoints to add IMG suffix.
147    0.3, 25/01/2005 nt: Added copyright notice and Number paragraph placeholder.
148    1.0, 11/05/2009 bcb: Final cleanup for publication
149
150
151