1 2Name 3 4 ATI_element_array 5 6 7Name Strings 8 9 GL_ATI_element_array 10 11 12Contact 13 14 Rick Hammerstone, AMD (rick.hammerstone 'at' amd.com) 15 16 17Version 18 19 0.3 - 11/04/06 20 Updated contact info after ATI/AMD merger. 21 22 0.2 - 09/18/01 23 Changed default behavior of draw commands when element array is 24 not enabled. Now generates an error and draws nothing. 25 26 0.1 - 07/06/01 27 Initial revision 28 29 30Number 31 32 256 33 34Dependencies 35 36 This extension is written against the OpenGL 1.2.1 Specification. 37 OpenGL 1.1 is required. ATI_vertex_array_object affects the 38 definition of this extension. 39 40 41Overview 42 43 This extension provides a mechanism for an application to create 44 an array of index data for use in specifying geometric primitives. 45 46 This extension is most useful when used in conjunction with the 47 ATI_vertex_array_object extension. ATI_vertex_array_object 48 provides an interface for storing vertex array data in persistent, 49 hardware-addressable memory. In cases where large amounts of 50 vertex data are in use, the index data used to construct 51 primitives (typically as passed to the GL through DrawElements) 52 can impose a significant bandwidth burden. ATI_element_array 53 allows the application to specify independent arrays of elements, 54 which can then be cached using ATI_vertex_array_object. 55 56 57Issues 58 59 Should we allow ElementPointerATI to specify a stride? 60 61 No, the expectation is that the indices are always packed 62 together. 63 64 Should we allow ElementPointerATI to accept more types than those 65 accepted by DrawElements and DrawRangeElements? 66 67 No, it doesn't seem useful to allow float indices, they have 68 to get converted to some kind of int anyways. 69 70 Should the element count be specified in the draw command, or as 71 part of the definition of the element array. 72 73 As part of the draw command. Specifying it as part of the 74 definition of element array sort of makes sense, but it 75 doesn't really fit with the way that vertex arrays currently 76 work. 77 78 Do we want to specify new entry points for the draw commands? 79 80 Yes. The alternative is to overload DrawElements and 81 DrawRangeElements by doing something funky like passing a null 82 pointer. This seems like it would be too confusing. 83 84 Is it useful to have the draw commands do something (other than 85 return an error) when the element array is disabled? 86 87 No. It's very hard to ascertain the intent of the application 88 at this point, so it's probably best to not draw anything. 89 90 91New Procedures and Functions 92 93 void ElementPointerATI(enum type, const void *pointer) 94 95 void DrawElementArrayATI(enum mode, sizei count) 96 97 void DrawRangeElementArrayATI(enum mode, uint start, 98 uint end, sizei count) 99 100 101New Tokens 102 103 Accepted by the <array> parameter of EnableClientState and 104 DisableClientState, the <value> parameter of IsEnabled, and if 105 ATI_vertex_array_object is defined, the <array> parameter of 106 ArrayObjectATI, GetArrayObjectivATI, GetArrayObjectfvATI: 107 108 ELEMENT_ARRAY_ATI 0x8768 109 110 Accepted by the <value> parameter of GetBooleanv, GetIntegerv, 111 GetFloatv, and GetDoublev: 112 113 ELEMENT_ARRAY_TYPE_ATI 0x8769 114 115 Accepted by the <pname> paramater of GetPointerv: 116 117 ELEMENT_ARRAY_POINTER_ATI 0x876A 118 119 120Additions to Chapter 2 of the GL Specification (OpenGL Operation) 121 122 In section 2.6.3, GL Commands within Begin/End, add 123 ElementArrayATI to the list of commands that are not allowed 124 within any Begin/End pair, but may or may not generate an error. 125 126 127 Inserted in section 2.8, Vertex Arrays, after the description of 128 DrawRangeElements, but before the description of 129 InterleavedArrays: 130 131 The commands 132 133 void DrawElementArrayATI(enum mode, sizei count) 134 135 void DrawRangeElementArrayATI(enum mode, uint start, 136 uint end, sizei count) 137 138 can be used to construct a sequence of geometric primitives in the 139 same manner as DrawElements and DrawRangeElements, but using 140 a previously defined array of indices. For DrawElementArrayATI, 141 the <mode> and <count> arguments match the corresponding arguments 142 to DrawElements. For DrawRangeElementArrayATI, the <mode>, 143 <start>, <end> and <count> arguments match the corresponding 144 arguments to DrawRangeElements. 145 146 For both DrawElementArrayATI and DrawRangeElementArrayATI, the 147 list of indices used to generate primitives is defined by the 148 command 149 150 void ElementPointer(enum type, const void *pointer) 151 152 The <pointer> argument is used to specify the list of indices, and 153 the <type> argument specifies their format. These arguments match 154 the <type> and <indices> arguments to DrawElements and 155 DrawRangeElements, and the allowed types match those accepted by 156 these two commands -- GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, and 157 GL_UNSIGNED_INT. ElementPointer does not specify a stride between 158 successive indices in the array, the values must be stored 159 sequentially in memory. 160 161 The array of element indices can be enabled and disabled by 162 calling EnableClientState and DisableClientState with the argument 163 ELEMENT_ARRAY_ATI. DrawElements and DrawRangeElements ignore the 164 currently enabled element array. 165 166 If a DrawElementArrayATI or DrawRangeElementArrayATI command is 167 issued when there is no currently enabled element array, an error 168 is generated, no drawing is done and the current state is not 169 updated. 170 171 172 173Additions to Chapter 3 of the 1.2.1 Specification (Rasterization) 174 175 None 176 177 178Additions to Chapter 4 of the 1.2.1 Specification (Per-Fragment 179Operations and the Frame Buffer) 180 181 None 182 183 184Additions to Chapter 5 of the 1.2.1 Specification (Special Functions) 185 186 In section 5.4, Display Lists, change the last sentence of the first 187 paragraph to read: 188 189 (Vertex array and element array pointers are dereferenced when the 190 commands ArrayElement, DrawArrays, DrawElements, 191 DrawRangeElements, DrawElementArrayATI, or 192 DrawRangeElementArrayATI are accumulated into a display list.) 193 194 In section 5.4, Display Lists, add ElementArrayATI to the list of 195 commands that are not compiled into display lists but are executed 196 immediately. 197 198 199Additions to Chapter 6 of the 1.2.1 Specification (State and State 200Requests) 201 202 In section 6.1.11, Pointer and String Queries, add 203 ELEMENT_ARRAY_POINTER_ATI to the list of possible values for the 204 <pname> parameter of GetPointerv. 205 206 207Additions to the specification of ATI_vertex_array_object 208 209 Added to the discussion of the <size>, <type>, and <stride> 210 parameters of ArrayObjectATI: 211 212 If the <array> parameter of ArrayObjectATI is ELEMENT_ARRAY_ATI, 213 then <size> must be one, and <stride> must be zero. INVALID_VALUE 214 is generated if either of these parameters is invalid. The <type> 215 parameter must be UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT. 216 INVALID_ENUM is generated if <type> is not one of these values. 217 218 219Errors 220 221 Invalid <mode> or <count> parameters to DrawElementArrayATI 222 generate the same errors as would the corresponding call to 223 DrawElements. 224 225 Invalid <mode>, <count>, <start>, or <end> parameters to 226 DrawRangeElementArrayATI generate the same errors as would the 227 corresponding call to DrawRangeElements. 228 229 INVALID_ENUM is generated if the <type> parameter of 230 ElementArrayATI is not UNSIGNED_BYTE, UNSIGNED_SHORT, or 231 UNSIGNED_INT. 232 233 INVALID_OPERATION is generated if a DrawElementArrayATI or 234 DrawRangeElementArrayATI command is issued when there is no 235 currently enabled element array. 236 237 238New State 239 240 Added to table 6.6, Vertex Array Data 241 242 Get Value Get Command Type Initial Value Attrib 243 --------- ----------- ---- ------------- ------ 244 ELEMENT_ARRAY_ATI IsEnabled B False client 245 ELEMENT_ARRAY_TYPE_ATI GetIntegerv Z4 UNSIGNED_INT client 246 ELEMENT_ARRAY_POINTER_ATI GetPointerv Z+ 0 client 247 248 249Implementation Notes 250 251 For maximum performance, applications should use 252 UNSIGNED_SHORT or UNSIGNED_INT indices. 253