Name 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. New Procedures and Functions 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); New Tokens Accepted by the parameter of EnableClientState and DisableClientState and the parameter of IsEnabled: ELEMENT_ARRAY_APPLE 0x8A0C Accepted by the parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: ELEMENT_ARRAY_TYPE_APPLE 0x8A0D Accepted by the parameter of GetPointerv: ELEMENT_ARRAY_POINTER_APPLE 0x8A0E 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 and arguments match the corresponding arguments to DrawElements. For DrawRangeElementArrayAPPLE, the , , and arguments match the corresponding arguments to DrawRangeElements. For either routine, the 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 argument is used to specify the list of indices, and the argument specifies their format. These arguments match the and 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=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=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 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 or is negative. The error INVALID_VALUE is generated if MultiDrawElementArrayAPPLE or MultiDrawRangeElementArrayAPPLE is called where is negative. The error INVALID_VALUE is generated if DrawRangeElementArrayAPPLE or MultiDrawRangeElementArrayAPPLE is called where is greater than . INVALID_ENUM is generated if the 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.