1Name 2 3 ARB_vertex_array_object 4 5Name Strings 6 7 GL_ARB_vertex_array_object 8 9Contact 10 11 Ian Romanick, IBM Corporation (idr 'at' us.ibm.com) 12 13Notice 14 15 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Approved by the ARB on July 11, 2008 31 32Version 33 34 Last Modified Data: October 8, 2012 35 Author revision: 13 36 37Number 38 39 ARB Extension #54 40 41Dependencies 42 43 This extension is written against the OpenGL 2.1 specification (December 44 1st, 2006). 45 46 APPLE_vertex_array_object affects the definition of this extension. 47 48Overview 49 50 This extension introduces named vertex array objects which encapsulate 51 vertex array state on the client side. These objects allow applications 52 to rapidly switch between large sets of array state. In addition, layered 53 libraries can return to the default array state by simply creating and 54 binding a new vertex array object. 55 56 This extension differs from GL_APPLE_vertex_array_object in that client 57 memory cannot be accessed through a non-zero vertex array object. It also 58 differs in that vertex array objects are explicitly not sharable between 59 contexts. 60 61New Procedures and Functions 62 63 void BindVertexArray(uint array); 64 65 void DeleteVertexArrays(sizei n, const uint *arrays); 66 67 void GenVertexArrays(sizei n, uint *arrays); 68 69 boolean IsVertexArray(uint array); 70 71New Tokens 72 73 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 74 GetFloatv, and GetDoublev: 75 76 VERTEX_ARRAY_BINDING 0x85B5 77 78Additions to Chapter 2 of the OpenGL 2.1 Specification (OpenGL Operation) 79 80 Add new section "2.X Vertex Array Objects" between sections "2.9 Buffer 81 Objects" and "2.10 Rectangles". 82 83 The buffer objects that are to be used by the vertex and geometry stages 84 of the GL are collected together to form a vertex array object. All 85 state related to the definition of data used by the vertex processor is 86 encapsulated in a vertex array object. 87 88 The command 89 90 void GenVertexArrays(sizei n, uint *arrays); 91 92 returns <n> previous unused vertex array object names in <arrays>. These 93 names are marked as used, for the purposes of GenVertexArrays only, but 94 they acquire array state only when they are first bound. 95 96 Vertex array objects are deleted by calling 97 98 void DeleteVertexArrays(sizei n, const uint *arrays); 99 100 <arrays> contains <n> names of vertex array objects to be deleted. Once 101 a vertex array object is deleted it has no contents and its name is 102 again unused. If a vertex array object that is currently bound is 103 deleted, the binding for that object reverts to zero and the default 104 vertex array becomes current. Unused names in <arrays> are silently 105 ignored, as is the value zero. 106 107 A vertex array object is created by binding a name returned by 108 GenVertexArrays with the command 109 110 void BindVertexArray(uint array); 111 112 <array> is the vertex array object name. The resulting vertex array 113 object is a new state vector, comprising all the state values listed in 114 tables 6.6 (except for the CLIENT_ACTIVE_TEXTURE selector state), 6.7, 115 and 6.8 (except for the ARRAY_BUFFER_BINDING state). 116 117 BindVertexArray may also be used to bind an existing vertex array 118 object. If the bind is successful no change is made to the state of the 119 bound vertex array object, and any previous binding is broken. 120 121 The currently bound vertex array object is used for all commands 122 which modify vertex array state, such as VertexAttribPointer and 123 EnableVertexAttribArray; all commands which draw from vertex arrays, 124 such as DrawArrays and DrawElements; and all queries of vertex 125 array state (see chapter 6). 126 127 BindVertexArray fails and an INVALID_OPERATION error is generated if 128 array is not zero or a name returned from a previous call to 129 GenVertexArrays, or if such a name has since been deleted with 130 DeleteVertexArrays. 131 132 An INVALID_OPERATION error is generated if any of the *Pointer commands 133 specifying the location and organization of vertex data are called while 134 a non-zero vertex array object is bound, zero is bound to the 135 ARRAY_BUFFER buffer object, and the pointer is not NULL[fn]. 136 [fn: This error makes it impossible to create a vertex array 137 object containing client array pointers.] 138 139Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization) 140 141 None 142 143Additions to Chapter 4 of the OpenGL 2.1 Specification (Per-Fragment 144 Operations and the Framebuffer) 145 146 None 147 148Additions to Chapter 5 of the OpenGL 2.1 Specification (Special Functions) 149 150 Modify Section 5.4, Display Lists (p. 240) 151 152 (add new paragraph after 10th paragraph on p. 244) 153 154 Vertex array objects: GenVertexArrays, DeleteVertexArrays, 155 BindVertexArray 156 157Additions to Chapter 6 of the OpenGL 2.1 Specification (Querying GL State) 158 159 Modify Section 6.1.2, Data Conversions (p. 248) 160 161 (add new paragraph after last paragraph of section, p. 249) 162 163 Vertex-array state variables are qualified by the value of 164 VERTEX_ARRAY_BINDING to determine which vertex array object is queried. 165 Tables 6.6, 6.7, and 6.8 define the set of state stored in a vertex array 166 object. 167 168 Modify Section 6.1.11, Pointer and String Queries (p. 257) 169 170 (add new paragraph after 1st paragraph of section, p. 257) 171 172 Queries for VERTEX_ARRAY_POINTER, NORMAL_ARRAY_POINTER, 173 COLOR_ARRAY_POINTER, SECONDARY_COLOR_ARRAY_POINTER, INDEX_ARRAY_POINTER, 174 TEXTURE_COORD_ARRAY_POINTER, FOG_COORD_ARRAY_POINTER, or 175 EDGE_FLAG_ARRAY_POINTER return the value stored in the currently bound 176 vertex array object. 177 178 Add new section "6.1.X Vertex Array Object Queries" between sections 179 "6.1.13 Buffer Object Queries" and "6.1.14 Shader and Program Queries". 180 181 The command 182 183 boolean IsVertexArray(uint array); 184 185 returns TRUE if <array> is the name of a vertex array object. If <array> 186 is zero, or a non-zero value that is not the name of a vertex array 187 object, IsVertexArray returns FALSE. No error is generated is <array> is 188 not a valid vertex array object name. 189 190 Modify Section 6.1.14, Shader and Program Queries, p. 260 191 192 (modify the first paragraph on page 263) 193 194 Replace the text 195 196 "Note that all the queries except CURRENT_VERTEX_ATTRIB return client 197 state." 198 199 with 200 201 "Note that all the queries except CURRENT_VERTEX_ATTRIB return values 202 stored in the currently bound vertex array object (the value of 203 VERTEX_ARRAY_BINDING). If the zero object is bound, these values 204 are client state." 205 206 (modify the 3rd paragraph on page 263 to read) 207 208 The command 209 210 void GetVertexAttribPointerv(uint index, enum pname, void **pointer); 211 212 obtains the pointer named <pname> for vertex attribute numbered <index> 213 and places the information in <pointer>. <pname> must be 214 VERTEX_ATTRIB_ARRAY_POINTER. The value returned is queried from the 215 currently bound vertex array object. If the zero object is bound, the 216 value is queried from client state. An INVALID_VALUE error is generated 217 if <index> is greater than or equal to the value of MAX_VERTEX_ATTRIBS. 218 219Additions to Appendix X of the OpenGL X.X specification (Sharing) 220 221 Vertex array objects are not sharable between contexts. 222 223Additions to the GLX Specification 224 225 No change is made to the GLX API. 226 227Interactions with APPLE_vertex_array_object 228 229 Vertex array objects as defined by this spec fill the same role as the 230 objects defined in APPLE_vertex_array_object but have some significant 231 semantic differences. If both types of object are supported by an 232 implementation, BindVertexArray will accept object names from either 233 type of object. Names passed to BindVertexArray must have been 234 previously returned by GenVertexArrays, previously returned by 235 GenVertexArraysAPPLE, or previously bound by BindVertexArrayAPPLE. 236 BindVertexArrayAPPLE must also accept names that were previously returned 237 by GenVertexArrays and bound with BindVertexArray. 238 239 In addition, the enumerant value for VERTEX_ARRAY_BINDING is the same 240 as VERTEX_ARRAY_BINDING_APPLE. 241 242 This allows applications using ARB VAOs to safely call into libraries that 243 internally use Apple VAOs, and vice-versa. 244 245 The first bind call, either BindVertexArray or BindVertexArrayAPPLE, 246 determines the semantic of the object. 247 248GLX Protocol 249 250 The following rendering commands are sent to the server as part of a 251 glXRender request. 252 253 BindVertexArray 254 255 2 8 rendering command length 256 2 350 rendering command opcode 257 4 CARD32 array 258 259 DeleteVertexArrays 260 261 2 8+(n*4) rendering command length 262 2 351 rendering command opcode 263 4 CARD32 n 264 n*4 LISTofCARD32 arrays 265 266 The following non-rendering commands are sent using glx single requests: 267 268 GenVertexArrays 269 270 1 CARD8 opcode (X assigned) 271 1 206 GLX opcode 272 2 3 request length 273 4 GLX_CONTEXT_TAG context tag 274 4 CARD32 n 275 => 276 1 1 reply 277 1 unused 278 2 CARD16 sequence number 279 4 n reply length 280 24 unused 281 n*4 LISTofCARD32 arrays 282 283 IsVertexArray 284 285 1 CARD8 opcode (X assigned) 286 1 207 GLX opcode 287 2 3 request length 288 4 GLX_CONTEXT_TAG context tag 289 4 CARD32 array 290 => 291 1 1 reply 292 1 unused 293 2 CARD16 sequence number 294 4 0 reply length 295 4 BOOL32 return value 296 20 unused 297 298 New protocols for GetPointerv and GetVertexAttribPointerv are specified 299 300 GetPointerv 301 302 1 CARD8 opcode (X assigned) 303 1 208 GLX opcode 304 2 3 request length 305 4 GLX_CONTEXT_TAG context tag 306 4 ENUM pname 307 => 308 1 1 reply 309 1 1 unused 310 2 CARD16 sequence number 311 4 m reply length, m = (n + p) / 4 312 4 unused 313 4 CARD32 n 314 16 unused 315 n LISTofBYTE params 316 p unused, p=pad(n) 317 318 GetVertexAttribPointerv 319 320 1 CARD8 opcode (X assigned) 321 1 209 GLX opcode 322 2 4 request length 323 4 GLX_CONTEXT_TAG context tag 324 4 CARD32 index 325 4 ENUM pname 326 => 327 1 1 reply 328 1 1 unused 329 2 CARD16 sequence number 330 4 m reply length, m = (n + p) / 4 331 4 unused 332 4 CARD32 n 333 16 unused 334 n LISTofBYTE pointer 335 p unused, p=pad(n) 336 337Errors 338 339 INVALID_OPERATION is generated if any of the commands defined in this 340 extension is executed between the execution of Begin and the corresponding 341 execution of End. 342 343New State 344 345 Get Value Get Command Type Value Attrib 346 --------- ----------- ---- ------- ------ 347 VERTEX_ARRAY_BINDING GetIntegerv Z+ 0 vertex-array 348 349New Implementation Dependent State 350 351 None 352 353Issues 354 355 (1) Are vertex array objects client or server state? 356 357 DISCUSSION: Ideally they should be server state, like texture objects. 358 However, much of the state that is encapsulated by VAOs is client-state. 359 360 RESOLUTION: Resolved. VAOs are server state. This essentially means that 361 client array state must be duplicated on the server. For practical 362 purposes, VBOs already require this duplication. 363 364 (2) What happens when a buffer object that is attached to a non-current 365 VAO is deleted? 366 367 RESOLUTION: Nothing (though a reference count may be decremented). 368 A buffer object that is deleted while attached to a non-current VAO 369 is treated just like a buffer object bound to another context (or to 370 a current VAO in another context). 371 372 (3) Are VAOs sharable? 373 374 DISCUSSION: There are many difficulties and complications involved in 375 guaranteeing correct behavior when "container" objects are sharable. 376 377 RESOLUTION: RESOLVED: NO. 378 379 (4) Can buffer objects attached to a VAO be modified? 380 381 DISCUSSION: Operations such as updating the contents of a buffer object, 382 either via mapping the buffer or calling BufferSubData, are not 383 problematic. However, operations that cause a change in the underlying 384 data structure can be very problematic from a hardware / driver 385 perspective. Currently the only such operation is BufferData which causes 386 the buffer to be reallocated. 387 388 RESOLUTION: RESOLVED. Yes. Calling BufferData on a buffer attached 389 to a VAO is allowed. 390 391 (5) What are the interactions with this extension and 392 APPLE_vertex_array_object? 393 394 DISCUSSION: The only question is what the behavior should be when both an 395 ARB vertex array object and an Apple vertex array object are bound at the 396 same time. 397 398 RESOLUTION: Resolved. If both extensions are supported by an 399 implementation, both object types share a name space. Most of the useful 400 interactions fall out as a result of that. Please refer to the section 401 "Interactions with APPLE_vertex_array_object" above for more details. 402 403 (6) Why don't the new tokens and entry points in this extension have 404 "ARB" suffixes like other ARB extensions? 405 406 RESOLVED: Unlike most ARB extensions, this is a strict subset of 407 functionality already approved in OpenGL 3.0. This extension exists 408 only to support that functionality on older hardware that cannot 409 implement a full OpenGL 3.0 driver. Since there are no possible 410 behavior changes between the ARB extension and core features, source 411 code compatibility is improved by not using suffixes on the 412 extension. 413 414 (7) How does this extension affect the GLX protocol of the commands that 415 modify or query vertex array state? 416 417 RESOLVED: This extension changes the behaviour of all the commands that 418 modify or query vertex array state to use currently bound vertex array 419 object when a non-zero vertex array object is bound. 420 Since vertex array object is stored in the server, new protocol must be 421 specified for GetPointerv and GetVertexAttribPointerv. 422 Additionally, commands GetVertexAttribdv, GetVertexAttribfv and 423 GetVertexAttribiv must query state from the server and commands 424 VertexAttrib*Pointer, EnableVertexAttribArray and DisableVertexAttribArray 425 must modify state in the server when a non-zero vertex array object is 426 bound. If the zero object is bound, the value is queried from client state. 427 428Revision History 429 430 Rev. Date Author Changes 431 ---- ---------- -------- ---------------------------------------------- 432 1 04/17/2008 idr Initial version based on 433 GL_APPLE_vertex_array_object spec. 434 435 2 04/18/2008 idr Added sharability issue. 436 437 3 05/02/2008 idr Added issues #4 and #5. 438 439 4 05/15/2008 idr Resolved issue #1. VAOs are server state. 440 Resolved issue #5. ARB and APPLE VAOs share 441 a name space. 442 443 5 06/04/200 Jon Leech Minor typos, rearrange errors. 444 445 6 06/15/2008 Jon Leech More minor typos, clarify GenVertexArrays 446 behavior. 447 448 7 07/08/2008 js - noted that VAO is not supposed to include 449 CLIENT_ACTIVE_TEXTURE (bugzilla 3611) 450 - resolved all other open issues as per working 451 group discussions 452 - deleted obsolete INVALID_OPERATION on 453 draw with client arrays since it's no 454 longer possible to define a VAOs with client 455 arrays, as per working group discussions 456 - synced up BindVertexArray language with GL 3 spec 457 draft glspec30.20080708.1.pdf. 458 459 8 08/07/2008 Jon Leech Remove ARB suffixes. 460 461 9 08/20/2008 Jon Leech Cleanup formatting errors. 462 463 10 09/21/2011 Jon Leech Clarify that all *Pointer commands generate 464 errors when attempting to specify client 465 array pointers in a VAO (Bug 3696). 466 11 09/22/2011 Jon Leech Exclude ARRAY_BUFFER_BINDING from VAO 467 state (Bug 5659). 468 12 09/19/2012 Jon Leech Language tweaks for consistency with 469 OpenGL 3.1 specification (Bug 4306). 470 471 13 10/08/2012 srahman Added GLX protocol and issue #7. 472