Back to the OpenGL extension cross reference
GL_APPLE_element_array
APPLE_element_array
Name Strings
GL_APPLE_element_array
Contact
Bob Beretta, Apple Computer (beretta 'at' apple.com)
Version
1.0
Number
271
Dependencies
Written based on the wording of the OpenGL 1.3 specification.
Assumes support for the APPLE_vertex_array_range extension.
Overview
This extension provides facilities to improve DrawElements style vertex
indices submission performance by allowing index arrays. Using this
extension these arrays can be contained inside a vertex array range and
thus pulled directly by the graphics processor, avoiding the CPU overhead
of touching the index data.
This extension is most useful when used in conjunction with the
APPLE_vertex_array_range extension. APPLE_vertex_array_range provides an
interface for storing vertex array data. In cases where large amounts of
vertex data are in use, the index data used to construct primitives
(typically as passed to the GL through DrawElements) can impose a
significant bandwidth burden. APPLE_element_array allows the application to
specify independent arrays of elements, which can then be cached using
APPLE_vertex_array_range. In effect this creates a more orthogonal
interface for both vertex indices and data.
Issues
Must the element array be enabled?
RESOLVED: Yes, for orthogonality with the rest of the API.
void ElementPointerAPPLE(enum type, const void *pointer);
void DrawElementArrayAPPLE(enum mode, int first, sizei count)
void DrawRangeElementArrayAPPLE(enum mode, uint start,
uint end, int first, sizei count)
void MultiDrawElementArrayAPPLE(enum mode, const int *first,
const sizei *count, sizei primcount);
void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
const int *first,
const sizei *count,
sizei primcount);
Accepted by the <array> parameter of EnableClientState and
DisableClientState and the <value> parameter of IsEnabled:
ELEMENT_ARRAY_APPLE 0x8768
Accepted by the <value> parameter of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev:
ELEMENT_ARRAY_TYPE_APPLE 0x8769
Accepted by the <pname> parameter of GetPointerv:
ELEMENT_ARRAY_POINTER_APPLE 0x876A
Additions to Chapter 2 of the GL Specification (OpenGL Operation)
In section 2.6.3, GL Commands within Begin/End, add
ElementArrayAPPLE to the list of commands that are not allowed
within any Begin/End pair, but may or may not generate an error.
Inserted in section 2.8, Vertex Arrays, after the description of
DrawRangeElements, but before the description of
InterleavedArrays:
"The commands
void DrawElementArrayAPPLE(enum mode, int first, sizei count)
void DrawRangeElementArrayAPPLE(enum mode, uint start,
uint end, int first, sizei count)
can be used to construct a sequence of geometric primitives in the same
manner as DrawElements and DrawRangeElements, but using a previously defined
array of indices. For DrawElementArrayAPPLE, the <mode> and <count>
arguments match the corresponding arguments to DrawElements. For
DrawRangeElementArrayAPPLE, the <mode>, <start>, <end> and <count> arguments
match the corresponding arguments to DrawRangeElements. For either routine,
the <first> argument specifies the first element of the current element
array to be used in generating primitives.
For both DrawElementArrayAPPLE and DrawRangeElementArrayAPPLE, the list of
indices used to generate primitives is defined by the command
void ElementPointer(enum type, const void *pointer)
The <pointer> argument is used to specify the list of indices, and the
<type> argument specifies their format. These arguments match the <type> and
<indices> arguments to DrawElements and DrawRangeElements, and the allowed
types match those accepted by these two commands -- GL_UNSIGNED_BYTE,
GL_UNSIGNED_SHORT, and GL_UNSIGNED_INT. ElementPointer does not specify a
stride between successive indices in the array, the values must be stored
sequentially in memory.
The commands MultiDrawElementArrayAPPLE and MultiDrawRangeElementArrayAPPLE
provides functionality equivalent to EXT_multi_draw_arrays allowing multiple
lists of indices in one call.
The command
void MultiDrawElementArrayAPPLE(enum mode, const int *first,
const sizei *count, sizei primcount)
is equivalent to the following sequence of commands:
for(i=0; i<primcount; i++) {
if ((*(first+i)>=0) && (*(count+i)>0))
DrawElementArrayAPPLE(mode, *(first+i), *(count+i));
}
and the command
void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
const int *first,
const sizei *count,
sizei primcount)
is equivalent to the following sequence of commands:
for(i=0; i<primcount; i++) {
if ((*(first+i)>=0) && (*(count+i)>0))
DrawRangeElementArrayAPPLE(mode, start, end, *(first+i),
*(count+i));
}
The array of element indices can be enabled and disabled by calling
EnableClientState and DisableClientState with the argument
ELEMENT_ARRAY_APPLE. DrawElements and DrawRangeElements ignore the currently
enabled element array.
If a DrawElementArrayAPPLE or DrawRangeElementArrayAPPLE command is issued
when there is no currently enabled element array, an error is generated, no
drawing is done and the current state is not updated."
Replace the last paragraph of section 2.8 "Vertex Arrays" (page 28) with the
following:
"If the number of supported texture units (the value of MAX_TEXTURE_UNITS)
is k, then the client state required to implement vertex arrays consists of
5+k boolean values, 6+k memory pointers, 5+k integer stride values, 5+k
symbolic constants representing array types, and 3+k integers representing
values per element. In the initial state, the boolean values are each
disabled, the memory pointers are each null, the strides are each zero, the
array types are each FLOAT, except for the element array type, which is
UNSIGNED_INT, and the integers representing values per element are each
four."
Add to the section describing the operation of the vertex array range:
"When the vertex array range is valid, changes to element array data used by
the DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE commands
need to be synchronized in the same manner as other vertex array data.
Undefined vertices maybe generated by DrawElementArrayAPPLE,
DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
MultiDrawRangeElementArrayAPPLE when the vertex array range is enabled if
any element required by the element array falls outside of the vertex array
range."
Additions to Chapter 3 of the 1.3 Specification (Rasterization)
None
Additions to Chapter 4 of the 1.3 Specification (Per-Fragment
Operations and the Frame Buffer)
None
Additions to Chapter 5 of the 1.3 Specification (Special Functions)
In section 5.4, Display Lists, change the last sentence of the first
paragraph to read:
"(Vertex array and element array pointers are de-referenced when the
commands ArrayElement, DrawArrays, DrawElements, DrawRangeElements,
DrawElementArrayAPPLE, or DrawRangeElementArrayAPPLE are accumulated into a
display list.)
In section 5.4, Display Lists, add ElementArrayAPPLE to the list of commands
that are not compiled into display lists but are executed immediately. In
additional add to the end of the section:
"If a display list is compiled while VERTEX_ARRAY_RANGE_APPLE is enabled,
the commands ArrayElement, DrawArrays, DrawElements,
DrawRangeElements, DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE are
accumulated into a display list as if VERTEX_ARRAY_RANGE_APPLE is
disabled."
Additions to Chapter 6 of the 1.3 Specification (State and State
Requests)
In "Pointer and String Queries", section 6.1.11, add
ELEMENT_ARRAY_POINTER_APPLE to the list of possible values for the
<pname> parameter of GetPointerv.
Additions to the specification of APPLE_vertex_array_range
The element array is included in the vertex array data that is expected
to reside fully within the specified vertex array range, if enabled. If
elements in the array lie outside the current vertex array range the
result is undefined.
Errors
The error INVALID_OPERATION is generated if DrawElementArrayAPPLE,
DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
MultiDrawRangeElementArrayAPPLE is called between the execution of Begin and
the corresponding execution of End.
The error INVALID_VALUE is generated if DrawElementArrayAPPLE or
DrawRangeElementArrayAPPLE is called where either <first> or <count> is
negative.
The error INVALID_VALUE is generated if MultiDrawElementArrayAPPLE or
MultiDrawRangeElementArrayAPPLE is called where <primcount> is negative.
The error INVALID_VALUE is generated if DrawRangeElementArrayAPPLE or
MultiDrawRangeElementArrayAPPLE is called where <start> is greater than
<end>.
INVALID_ENUM is generated if the <type> parameter of ElementPointerAPPLE is
not UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT.
INVALID_OPERATION is generated if a DrawElementArrayAPPLE,
DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE or
MultiDrawRangeElementArrayAPPLE command is issued when there is no currently
enabled element array.
New State
Added to table 6.6, Vertex Array Data
Get Value Get Command Type Initial Value Attrib
--------- ----------- ---- ------------- ------
ELEMENT_ARRAY_APPLE IsEnabled B False client
ELEMENT_ARRAY_TYPE_APPLE GetIntegerv Z4 UNSIGNED_INT client
ELEMENT_ARRAY_POINTER_APPLE GetPointerv Z+ 0 client
Implementation Notes
For maximum performance, applications should use
UNSIGNED_SHORT or UNSIGNED_INT indices.
Implementation Support
List of OpenGL implementations supporting the GL_APPLE_element_array extension
Original File
Original text file for the GL_APPLE_element_array extension
Page generated on Sun Nov 20 18:39:00 2005