• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    APPLE_element_array
4
5Name Strings
6
7    GL_APPLE_element_array
8
9Contact
10
11    Bob Beretta, Apple Computer (beretta 'at' apple.com)
12
13Version
14
15    1.0
16
17Number
18
19    271
20
21Dependencies
22
23    Written based on the wording of the OpenGL 1.3 specification.
24
25    Assumes support for the APPLE_vertex_array_range extension.
26
27Overview
28
29    This extension provides facilities to improve DrawElements style vertex
30    indices submission performance by allowing index arrays.  Using this
31    extension these arrays can be contained inside a vertex array range and
32    thus pulled directly by the graphics processor, avoiding the CPU overhead
33    of touching the index data.
34
35    This extension is most useful when used in conjunction with the
36    APPLE_vertex_array_range extension. APPLE_vertex_array_range provides an
37    interface for storing vertex array data. In cases where large amounts of
38    vertex data are in use, the index data used to construct primitives
39    (typically as passed to the GL through DrawElements) can impose a
40    significant bandwidth burden. APPLE_element_array allows the application to
41    specify independent arrays of elements, which can then be cached using
42    APPLE_vertex_array_range.  In effect this creates a more orthogonal
43    interface for both vertex indices and data.
44
45
46Issues
47
48    Must the element array be enabled?
49
50        RESOLVED: Yes, for orthogonality with the rest of the API.
51
52New Procedures and Functions
53
54    void ElementPointerAPPLE(enum type, const void *pointer);
55
56    void DrawElementArrayAPPLE(enum mode, int first, sizei count)
57
58    void DrawRangeElementArrayAPPLE(enum mode, uint start,
59                                    uint end, int first, sizei count)
60
61    void MultiDrawElementArrayAPPLE(enum mode, const int *first,
62                                    const sizei *count, sizei primcount);
63
64    void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
65                                         const int *first,
66                                         const sizei *count,
67                                         sizei primcount);
68
69
70New Tokens
71
72    Accepted by the <array> parameter of EnableClientState and
73    DisableClientState and the <value> parameter of IsEnabled:
74
75        ELEMENT_ARRAY_APPLE             0x8A0C
76
77    Accepted by the <value> parameter of GetBooleanv, GetIntegerv,
78    GetFloatv, and GetDoublev:
79
80        ELEMENT_ARRAY_TYPE_APPLE        0x8A0D
81
82    Accepted by the <pname> parameter of GetPointerv:
83
84        ELEMENT_ARRAY_POINTER_APPLE     0x8A0E
85
86
87Additions to Chapter 2 of the GL Specification (OpenGL Operation)
88
89    In section 2.6.3, GL Commands within Begin/End, add
90    ElementArrayAPPLE to the list of commands that are not allowed
91    within any Begin/End pair, but may or may not generate an error.
92
93
94    Inserted in section 2.8, Vertex Arrays, after the description of
95    DrawRangeElements, but before the description of
96    InterleavedArrays:
97
98    "The commands
99
100        void DrawElementArrayAPPLE(enum mode, int first, sizei count)
101
102        void DrawRangeElementArrayAPPLE(enum mode, uint start,
103                                        uint end, int first, sizei count)
104
105    can be used to construct a sequence of geometric primitives in the same
106    manner as DrawElements and DrawRangeElements, but using a previously defined
107    array of indices. For DrawElementArrayAPPLE, the <mode> and <count>
108    arguments match the corresponding arguments to DrawElements. For
109    DrawRangeElementArrayAPPLE, the <mode>, <start>, <end> and <count> arguments
110    match the corresponding arguments to DrawRangeElements.  For either routine,
111    the <first> argument specifies the first element of the current element
112    array to be used in generating primitives.
113
114    For both DrawElementArrayAPPLE and DrawRangeElementArrayAPPLE, the list of
115    indices used to generate primitives is defined by the command
116
117        void ElementPointer(enum type, const void *pointer)
118
119    The <pointer> argument is used to specify the list of indices, and the
120    <type> argument specifies their format. These arguments match the <type> and
121    <indices> arguments to DrawElements and DrawRangeElements, and the allowed
122    types match those accepted by these two commands -- GL_UNSIGNED_BYTE,
123    GL_UNSIGNED_SHORT, and GL_UNSIGNED_INT. ElementPointer does not specify a
124    stride between successive indices in the array, the values must be stored
125    sequentially in memory.
126
127    The commands MultiDrawElementArrayAPPLE and MultiDrawRangeElementArrayAPPLE
128    provides functionality equivalent to EXT_multi_draw_arrays allowing multiple
129    lists of indices in one call.
130
131
132    The command
133
134      void MultiDrawElementArrayAPPLE(enum mode, const int *first,
135                                   const sizei *count, sizei primcount)
136
137    is equivalent to the following sequence of commands:
138
139        for(i=0; i<primcount; i++) {
140            if ((*(first+i)>=0) && (*(count+i)>0))
141                DrawElementArrayAPPLE(mode, *(first+i), *(count+i));
142        }
143
144    and the command
145
146      void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
147                                        const int *first,
148                                        const sizei *count,
149                                        sizei primcount)
150
151    is equivalent to the following sequence of commands:
152
153        for(i=0; i<primcount; i++) {
154            if ((*(first+i)>=0) && (*(count+i)>0))
155                DrawRangeElementArrayAPPLE(mode, start, end, *(first+i),
156                                           *(count+i));
157        }
158
159    The array of element indices can be enabled and disabled by calling
160    EnableClientState and DisableClientState with the argument
161    ELEMENT_ARRAY_APPLE. DrawElements and DrawRangeElements ignore the currently
162    enabled element array.
163
164    If a DrawElementArrayAPPLE or DrawRangeElementArrayAPPLE command is issued
165    when there is no currently enabled element array, an error is generated, no
166    drawing is done and the current state is not updated."
167
168
169    Replace the last paragraph of section 2.8 "Vertex Arrays" (page 28) with the
170    following:
171
172    "If the number of supported texture units (the value of MAX_TEXTURE_UNITS)
173    is k, then the client state required to implement vertex arrays consists of
174    5+k boolean values, 6+k memory pointers, 5+k integer stride values, 5+k
175    symbolic constants representing array types, and 3+k integers representing
176    values per element. In the initial state, the boolean values are each
177    disabled, the memory pointers are each null, the strides are each zero, the
178    array types are each FLOAT, except for the element array type, which is
179    UNSIGNED_INT, and the integers representing values per element are each
180    four."
181
182
183    Add to the section describing the operation of the vertex array range:
184
185    "When the vertex array range is valid, changes to element array data used by
186    the DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
187    MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE commands
188    need to be synchronized in the same manner as other vertex array data.
189
190    Undefined vertices maybe generated by DrawElementArrayAPPLE,
191    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
192    MultiDrawRangeElementArrayAPPLE when the vertex array range is enabled if
193    any element required by the element array falls outside of the vertex array
194    range."
195
196
197Additions to Chapter 3 of the 1.3 Specification (Rasterization)
198
199    None
200
201
202Additions to Chapter 4 of the 1.3 Specification (Per-Fragment
203Operations and the Frame Buffer)
204
205    None
206
207
208Additions to Chapter 5 of the 1.3 Specification (Special Functions)
209
210    In section 5.4, Display Lists, change the last sentence of the first
211    paragraph to read:
212
213    "(Vertex array and element array pointers are de-referenced when the
214    commands ArrayElement, DrawArrays, DrawElements, DrawRangeElements,
215    DrawElementArrayAPPLE, or DrawRangeElementArrayAPPLE are accumulated into a
216    display list.)
217
218    In section 5.4, Display Lists, add ElementArrayAPPLE to the list of commands
219    that are not compiled into display lists but are executed immediately.  In
220    additional add to the end of the section:
221
222    "If a display list is compiled while VERTEX_ARRAY_RANGE_APPLE is enabled,
223    the commands ArrayElement, DrawArrays, DrawElements,
224    DrawRangeElements, DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
225    MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE are
226    accumulated into a display list as if VERTEX_ARRAY_RANGE_APPLE is
227    disabled."
228
229
230Additions to Chapter 6 of the 1.3 Specification (State and State
231Requests)
232
233    In "Pointer and String Queries", section 6.1.11, add
234    ELEMENT_ARRAY_POINTER_APPLE to the list of possible values for the
235    <pname> parameter of GetPointerv.
236
237
238Additions to the specification of APPLE_vertex_array_range
239
240    The element array is included in the vertex array data that is expected
241    to reside fully within the specified vertex array range, if enabled.  If
242    elements in the array lie outside the current vertex array range the
243    result is undefined.
244
245
246Errors
247
248    The error INVALID_OPERATION is generated if DrawElementArrayAPPLE,
249    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
250    MultiDrawRangeElementArrayAPPLE is called between the execution of Begin and
251    the corresponding execution of End.
252
253    The error INVALID_VALUE is generated if DrawElementArrayAPPLE or
254    DrawRangeElementArrayAPPLE is called where either <first> or <count> is
255    negative.
256
257    The error INVALID_VALUE is generated if MultiDrawElementArrayAPPLE or
258    MultiDrawRangeElementArrayAPPLE is called where <primcount> is negative.
259
260    The error INVALID_VALUE is generated if DrawRangeElementArrayAPPLE or
261    MultiDrawRangeElementArrayAPPLE is called where <start> is greater than
262    <end>.
263
264    INVALID_ENUM is generated if the <type> parameter of ElementPointerAPPLE is
265    not UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT.
266
267    INVALID_OPERATION is generated if a DrawElementArrayAPPLE,
268    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE or
269    MultiDrawRangeElementArrayAPPLE command is issued when there is no currently
270    enabled element array.
271
272
273New State
274
275    Added to table 6.6, Vertex Array Data
276
277    Get Value                   Get Command     Type    Initial Value   Attrib
278    ---------                   -----------     ----    -------------   ------
279    ELEMENT_ARRAY_APPLE         IsEnabled       B       False           client
280    ELEMENT_ARRAY_TYPE_APPLE    GetIntegerv     Z4      UNSIGNED_INT    client
281    ELEMENT_ARRAY_POINTER_APPLE GetPointerv     Z+      0               client
282
283
284Implementation Notes
285
286    For maximum performance, applications should use
287    UNSIGNED_SHORT or UNSIGNED_INT indices.
288
289