1Name 2 3 OES_vertex_array_object 4 5Name Strings 6 7 GL_OES_vertex_array_object 8 9Contributors 10 11 Ben Bowman 12 Yuan Wang 13 Benj Lipchak 14 15Contact 16 17 Ben Bowman, Imagination Technologies (benji 'dot' bowman 'at' imgtec 'dot' com) 18 19Notice 20 21 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34IP Status 35 36 37Status 38 39 Complete. Approved by the OpenGL ES WG on November 11, 2009. 40 Approved by the Khronos Board of Promoters on January 29, 2010. 41 42Version 43 44 Version 16, April 17, 2014 45 46Number 47 48 OpenGL ES Extension #71 49 50Dependencies 51 52 This extension is written against the OpenGL ES Common 1.1.12 53 Specification (April 24, 2008) and the OpenGL ES 2.0.24 54 Specification (April 22, 2009). 55 56 OES_matrix_palette affects the definition of this extension. 57 58Overview 59 60 This extension introduces vertex array objects which encapsulate 61 vertex array states on the server side (vertex buffer objects). 62 These objects aim to keep pointers to vertex data and to provide 63 names for different sets of vertex data. Therefore applications are 64 allowed to rapidly switch between different sets of vertex array 65 state, and to easily return to the default vertex array state. 66 67Issues 68 69 * Should vertex array objects be sharable across multiple OpenGL ES 70 contexts? 71 72 RESOLVED: No. The OpenGL ES working group took a straw poll and agreed 73 that the advantages of compatibility with OpenGL and ease of 74 implementation were more important than the disadvantage of creating 75 the first non-shared named object in OpenGL ES. 76 77 * Is it required for a vertex array object name to be explicitly 78 generated before being bound? 79 80 RESOLVED: Yes. The OpenGL ES working group agreed that 81 compatibility with OpenGL and the ability to to guide developers to 82 more "future looking" object usage were more important than keeping 83 consistency with other objects in OpenGL ES 1 and 2. 84 85 * Should a vertex array object be allowed to encapsulate client 86 vertex arrays? 87 88 RESOLVED: No. The OpenGL ES working group agreed that compatibility 89 with OpenGL and the ability to to guide developers to more 90 performant drawing by enforcing VBO usage were more important than 91 the possibility of hurting adoption of VAOs. 92 93 * Should client array indices be employed by DrawElements when a 94 non-zero vertex array object is bound? 95 96 RESOLVED: Yes. The original ARB_vao and OpenGL 3.0 incarnations of 97 this feature allowed client index data, so this extension should 98 also. 99 100 * When an application attempts to utilise a zero-named vertex array 101 buffer or a zero-named element array buffer, while a non-zero 102 vertex array object is presently attached, what should happen? 103 104 RESOLVED: Generally speaking, these kinds of endeavours are 105 erroneous, but some cases are deliberately tolerated. And they are 106 detailed as follows: 107 108 - Binding a zero-named vertex array buffer: 109 this can be detected by *Pointer(ES1) or VertexAttribPointer(ES2); 110 111 - if the pointer argument is not NULL: 112 this means to bind a client vertex array; 113 an INVALID_OPERATION error will be returned. 114 115 - if the pointer argument is NULL: 116 the result or drawing will be undefined, but with no GL error; 117 this enables a previously encapsulated vertex array buffer to 118 be detached from a vertex array object. 119 120 - Binding a zero-named element array buffer: 121 this can be identified by DrawElements; 122 123 - no restrictions. 124 125 126New Procedures and Functions 127 128 void BindVertexArrayOES(uint array); 129 130 void DeleteVertexArraysOES(sizei n, const uint *arrays); 131 132 void GenVertexArraysOES(sizei n, uint *arrays); 133 134 boolean IsVertexArrayOES(uint array); 135 136New Tokens 137 138 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv: 139 140 VERTEX_ARRAY_BINDING_OES 0x85B5 141 142Additions to Chapter 2 (OpenGL ES Operation) 143 144 * Add a new Section "2.X Vertex Array Objects" after Section "2.9 145 Buffer Objects". 146 147 The buffer objects that are to be used by the vertex stage of the 148 GL ES are collected together to form a vertex array object. All 149 state related to the definition of the data used by the vertex 150 processor is encapsulated in a vertex array object. 151 152 The command 153 154 void GenVertexArraysOES(sizei n, uint *arrays); 155 156 returns <n> previous unused vertex array object names in <arrays>. 157 These names are marked as used, for the purposes of 158 GenVertexArraysOES only, but they acquire array state only when 159 they are first bound, just as if they were unused. 160 161 Vertex array objects are deleted by calling 162 163 void DeleteVertexArraysOES(sizei n, const uint *arrays); 164 165 <arrays> contains <n> names of vertex array objects to be deleted. 166 Once a vertex array object is deleted it has no contents and its 167 name becomes unused again. If a vertex array object that is 168 currently bound is deleted, the binding for that object reverts to 169 zero and the default vertex array becomes current. Unused names in 170 <arrays> are silently ignored, as if they have the value zero. 171 172 The name space for vertex array objects is the unsigned integers, 173 with zero reserved for the GL ES. 174 175 A vertex array object is created by binding an unused name with the 176 command 177 178 void BindVertexArrayOES(uint array); 179 180IF(ES1) 181 182 and <array> here is the vertex array object name. The resulting 183 vertex array object is a new state vector, comprising all the state 184 values (listed in Tables 6.4 & 6.5, except CLIENT_ACTIVE_TEXTURE 185 and ARRAY_BUFFER_BINDING): 186 187 VERTEX_ARRAY, 188 VERTEX_ARRAY_SIZE, 189 VERTEX_ARRAY_TYPE, 190 VERTEX_ARRAY_STRIDE, 191 VERTEX_ARRAY_POINTER, 192 VERTEX_ARRAY_BUFFER_BINDING, 193 194 NORMAL_ARRAY, 195 NORMAL_ARRAY_TYPE, 196 NORMAL_ARRAY_STRIDE, 197 NORMAL_ARRAY_POINTER, 198 NORMAL_ARRAY_BUFFER_BINDING, 199 200 COLOR_ARRAY, 201 COLOR_ARRAY_SIZE, 202 COLOR_ARRAY_TYPE, 203 COLOR_ARRAY_STRIDE, 204 COLOR_ARRAY_POINTER, 205 COLOR_ARRAY_BUFFER_BINDING, 206 207 TEXTURE_COORD_ARRAY, 208 TEXTURE_COORD_ARRAY_SIZE, 209 TEXTURE_COORD_ARRAY_TYPE, 210 TEXTURE_COORD_ARRAY_STRIDE, 211 TEXTURE_COORD_ARRAY_POINTER, 212 TEXTURE_COORD_ARRAY_BUFFER_BINDING, 213 214 POINT_SIZE_ARRAY_OES, 215 POINT_SIZE_ARRAY_TYPE_OES, 216 POINT_SIZE_ARRAY_STRIDE_OES, 217 POINT_SIZE_ARRAY_POINTER_OES, 218 POINT_SIZE_ARRAY_BUFFER_BINDING_OES, 219 220 ELEMENT_ARRAY_BUFFER_BINDING. 221 222 BindVertexArrayOES may also be used to bind an existing vertex 223 array object. If the binding is successful, no change is made to 224 the state of the bound vertex array object, and any previous 225 binding is broken. 226 227 BindVertexArrayOES fails and an INVALID_OPERATION error is 228 generated if array is not a name returned from a previous call to 229 GenVertexArraysOES, or if such a name has since been deleted with 230 DeleteVertexArraysOES. An INVALID_OPERATION error is generated if 231 any of the *Pointer commands specifying the location and 232 organization of vertex array data are called while a non-zero 233 vertex array object is bound, zero is bound to the ARRAY_BUFFER 234 buffer object binding point, and the pointer argument is not NULL 235 [fn1]. 236 [fn1: This error makes it impossible to create a vertex array 237 object containing client array pointers, while still allowing 238 buffer objects to be unbound.] 239 240 The currently bound vertex array object is used for all commands 241 that modify vertex array state, such as 242 VertexPointer, 243 NormalPointer, 244 ColorPointer, 245 TexCoordPointer, 246 PointSizePointerOES, 247 EnableClientState, 248 DisableClientState, 249 ClientActiveTexture, 250 all commands that draw from vertex arrays, such as 251 DrawArrays 252 DrawElements, 253 and all queries of vertex array state (see Chapter 6). 254 255END(ES1) 256 257IF(ES2) 258 259 and <array> here is the vertex array object name. The resulting 260 vertex array object is a new state vector, comprising all the state 261 values (listed in Table 6.2, except ARRAY_BUFFER_BINDING): 262 263 VERTEX_ATTRIB_ARRAY_ENABLED, 264 VERTEX_ATTRIB_ARRAY_SIZE, 265 VERTEX_ATTRIB_ARRAY_STRIDE, 266 VERTEX_ATTRIB_ARRAY_TYPE, 267 VERTEX_ATTRIB_ARRAY_NORMALIZED, 268 VERTEX_ATTRIB_ARRAY_POINTER, 269 ELEMENT_ARRAY_BUFFER_BINDING, 270 VERTEX_ATTRIB_ARRAY_BUFFER_BINDING. 271 272 BindVertexArrayOES may also be used to bind an existing vertex 273 array object. If the binding is successful, no change is made to 274 the state of the bound vertex array object, and any previous 275 binding is broken. 276 277 BindVertexArrayOES fails and an INVALID_OPERATION error is 278 generated if array is not a name returned from a previous call to 279 GenVertexArraysOES, or if such a name has since been deleted with 280 DeleteVertexArraysOES. An INVALID_OPERATION error is generated if 281 VertexAttribPointer is called while a non-zero vertex array object 282 is bound, zero is bound to the <ARRAY_BUFFER> buffer object binding 283 point and the pointer argument is not NULL [fn1]. 284 [fn1: This error makes it impossible to create a vertex array 285 object containing client array pointers, while still allowing 286 buffer objects to be unbound.] 287 288 The currently bound vertex array object is used for all commands 289 that modify vertex array state, such as VertexAttribPointer and 290 EnableVertexAttribArray; all commands that draw from vertex arrays, 291 such as DrawArrays and DrawElements; and all queries of vertex 292 array state (see Chapter 6). 293 294END(ES2) 295 296 And the presently attached vertex array object has the following 297 impacts on the draw commands: 298 299 While a non-zero vertex array object is bound, if any enabled 300 array's buffer binding is zero, when DrawArrays or 301 DrawElements is called, the result is undefined. 302 303Additions to Chapter 3 (Rasterization) 304 305 * None. 306 307 308Additions to Chapter 4 (Per-Fragment Operations and the Framebuffer) 309 310 * None. 311 312 313Additions to Chapter 5 (Special Functions) 314 315 * None. 316 317 318Additions to Chapter 6 (State and State Requests) 319 320IF(ES1) 321 322 * Add a new paragraph at the end of Section 6.1.2: Data Conversions 323 (Page 119). 324 325 Vertex array state variables are qualified by the value of 326 VERTEX_ARRAY_BINDING_OES to determine which vertex array object is 327 queried. Tables 6.4 & 6.5 define the set of state stored in a 328 vertex array object. 329 330 * Add a new Section "6.1.X Vertex Array Object Queries" after 331 Sections "6.1.6 Buffer Object Queries" (Page 120). 332 333 The command 334 335 boolean IsVertexArrayOES(uint array); 336 337 returns TRUE if <array> is the name of a vertex array object. If 338 <array> is zero, or a non-zero value that is not the name of a 339 vertex array object, IsVertexArrayOES returns FALSE. No error is 340 generated if <array> is not a valid array object name. 341 342END(ES1) 343 344IF(ES2) 345 346 * Add a new paragraph at the end of Section 6.1.2: Data Conversions 347 (Page 123). 348 349 Vertex array state variables are qualified by the value of 350 VERTEX_ARRAY_BINDING_OES to determine which vertex array object is 351 queried. Table 6.2 defines the set of state stored in a vertex 352 array object. 353 354 * Add a new Section "6.1.X Vertex Array Object Queries" between 355 Sections "6.1.6 Buffer Object Queries" and "6.1.7 Framebuffer 356 Object and Renderbuffer Queries" (Page 126). 357 358 The command 359 360 boolean IsVertexArrayOES(uint array); 361 362 returns TRUE if <array> is the name of a vertex array object. If 363 <array> is zero, or a non-zero value that is not the name of a 364 vertex array object, IsVertexArray returns FALSE. No error is 365 generated if <array> is not a valid array object name. 366 367 * Modify lines in Section 6.1.8: Shader and Program Queries 368 369 Page 131: replace "Note that all the queries except 370 CURRENT_VERTEX_ATTRIB return client state." 371 with 372 "Note that all the queries except CURRENT_VERTEX_ATTRIB return 373 values stored in the currently bound vertex array object (the value 374 of VERTEX_ARRAY_BINDING). If the zero object is bound, then the 375 queries return client state." 376 377 Page 131: add lines after "<pname> must be VERTEX_ATTRIB_ARRAY_POINTER." 378 The value returned is queried from the currently bound vertex array 379 object. If the zero object is bound, the value is queried from 380 client state. 381 382 383Additions to Appendix C (Deleting Shared Objects) 384 385 * Add another section in C.2 Sharing objects across multiple OpenGL 386 ES contexts (Page 163). 387 388 Objects which cannot be shared in this manner include: 389 vertex array objects 390 391END(ES2) 392 393IF(ES1) 394 395Dependencies on OES_matrix_palette 396 397 If OES_matrix_palette is supported, the language below should be 398 added into Chapter 2. 399 400 The vertex array object can also comprise the following state values: 401 MATRIX_INDEX_ARRAY_OES, 402 MATRIX_INDEX_ARRAY_SIZE_OES, 403 MATRIX_INDEX_ARRAY_TYPE_OES, 404 MATRIX_INDEX_ARRAY_STRIDE_OES, 405 MATRIX_INDEX_ARRAY_POINTER_OES, 406 MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES, 407 408 WEIGHT_ARRAY_OES, 409 WEIGHT_ARRAY_SIZE_OES, 410 WEIGHT_ARRAY_TYPE_OES, 411 WEIGHT_ARRAY_STRIDE_OES, 412 WEIGHT_ARRAY_POINTER_OES, 413 WEIGHT_ARRAY_BUFFER_BINDING_OES. 414 415 And the currently bound vertex array object can also be used for the 416 following commands 417 WeightPointerOES, 418 MatrixIndexPointerOES. 419 420END(ES1) 421 422Revision History 423 424 Rev. Date Author Changes 425 ------- ---------- ------------ ----------------------------------------------------- 426 16 04/17/14 Jon Leech Update wording of first issue (Bug 7847). 427 15 02/05/10 Jon Leech Update Status and assign extension number. 428 Reflow spec text to standard widths. 429 14 10/11/09 Ben Bowman Allow VAO to employ client indices. 430 13 09/11/09 Yuan Wang Forbade VAO to employ client array indices. 431 12 04/11/09 Ben Bowman Updated EXT to OES and adopted resolutions of the 432 OpenGL ES working group meeting on 04/11/09. (re) 433 disallow user generated (non Gen'd) names. 434 11 23/10/09 Ben Bowman Fixed INVALID_OPERATION error for client arrays. 435 10 14/10/09 Ben Bowman Adopted resolutions of the OpenGL ES working group 436 meeting on 14/10/09. (re) disallow client arrays to 437 be included in VAOs. Disallow sharing of VAOs. 438 9 14/10/09 Yuan Wang Added dependencies on OES_matrix_palette 439 8 14/10/09 Ben Bowman Formatting. Reopen of shared object decision. 440 7 09/09/09 Ben Bowman Cleanup of issues list. 441 6 04/09/09 Yuan Wang Changed contact details and added contributors. 442 Replaced IMG with EXT, added the extension for ES1 443 specification and added revision history. 444 5 20/08/09 Yuan Wang Allowed VAO to encapsulate client attribute arrays. 445 4 16/07/09 Yuan Wang Added ELEMENT_ARRAY_BUFFER_BINDING into VAO's 446 contained states, but took ARRAY_BUFFER_BINDING 447 out of the states. 448 3 07/07/09 Yuan Wang Removed VERTEX_ARRAY_IMG token, and removed target 449 param from BindVertexArrayIMG, since there is only 450 one type of target for VAO. 451 2 26/06/09 Yuan Wang Added IMG affix and VERTEX_ARRAY target for 452 BindVertexArrayIMG. 453 1 15/06/09 Yuan Wang Initial revision. 454 455 456 457 458