| 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 <array> parameter of EnableClientState and |
| DisableClientState and the <value> parameter of IsEnabled: |
| |
| ELEMENT_ARRAY_APPLE 0x8A0C |
| |
| Accepted by the <value> parameter of GetBooleanv, GetIntegerv, |
| GetFloatv, and GetDoublev: |
| |
| ELEMENT_ARRAY_TYPE_APPLE 0x8A0D |
| |
| Accepted by the <pname> 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 <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. |
| |