OES_vertex_array_object

Name

OES_vertex_array_object

Name Strings

GL_OES_vertex_array_object

Contributors

Ben Bowman
Yuan Wang
Benj Lipchak
  

Contact

Ben Bowman, Imagination Technologies (benji 'dot' bowman 'at' imgtec 'dot' com)

Notice

Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html
  

Specification Update Policy

Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL ES Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
    https://www.khronos.org/registry/OpenGL/docs/update_policy.php
  

IP Status

Status

Complete. Approved by the OpenGL ES WG on November 11, 2009.
Approved by the Khronos Board of Promoters on January 29, 2010.
  

Version

Version 16, April 17, 2014

Number

OpenGL ES Extension #71

Dependencies

This extension is written against the OpenGL ES Common 1.1.12
Specification (April 24, 2008) and the OpenGL ES 2.0.24
Specification (April 22, 2009).

OES_matrix_palette affects the definition of this extension.
  

Overview

This extension introduces vertex array objects which encapsulate
vertex array states on the server side (vertex buffer objects).
These objects aim to keep pointers to vertex data and to provide
names for different sets of vertex data. Therefore applications are
allowed to rapidly switch between different sets of vertex array
state, and to easily return to the default vertex array state.
  

Issues

Should vertex array objects be sharable across multiple OpenGL ES contexts?

RESOLVED: No. The OpenGL ES working group took a straw poll and agreed that the advantages of compatibility with OpenGL and ease of implementation were more important than the disadvantage of creating the first non-shared named object in OpenGL ES.
Is it required for a vertex array object name to be explicitly generated before being bound?

RESOLVED: Yes. The OpenGL ES working group agreed that compatibility with OpenGL and the ability to to guide developers to more "future looking" object usage were more important than keeping consistency with other objects in OpenGL ES 1 and 2.
Should a vertex array object be allowed to encapsulate client vertex arrays?

RESOLVED: No. The OpenGL ES working group agreed that compatibility with OpenGL and the ability to to guide developers to more performant drawing by enforcing VBO usage were more important than the possibility of hurting adoption of VAOs.
Should client array indices be employed by DrawElements when a non-zero vertex array object is bound?

RESOLVED: Yes. The original ARB_vao and OpenGL 3.0 incarnations of this feature allowed client index data, so this extension should also.
When an application attempts to utilise a zero-named vertex array buffer or a zero-named element array buffer, while a non-zero vertex array object is presently attached, what should happen?

RESOLVED: Generally speaking, these kinds of endeavours are erroneous, but some cases are deliberately tolerated. And they are detailed as follows:
- Binding a zero-named vertex array buffer: this can be detected by *Pointer(ES1) or VertexAttribPointer(ES2);
  - if the pointer argument is not NULL: this means to bind a client vertex array; an INVALID_OPERATION error will be returned.
  - if the pointer argument is NULL: the result or drawing will be undefined, but with no GL error; this enables a previously encapsulated vertex array buffer to be detached from a vertex array object.
- Binding a zero-named element array buffer: this can be identified by DrawElements;
  - no restrictions.

New Procedures and Functions

void BindVertexArrayOES(uint array);

void DeleteVertexArraysOES(sizei n, const uint *arrays);

void GenVertexArraysOES(sizei n, uint *arrays);

boolean IsVertexArrayOES(uint array);

New Tokens

Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv:

    VERTEX_ARRAY_BINDING_OES    0x85B5

Additions to Chapter 2 (OpenGL ES Operation)

Add a new Section "2.X Vertex Array Objects" after Section "2.9 Buffer Objects".

The buffer objects that are to be used by the vertex stage of the GL ES are collected together to form a vertex array object. All state related to the definition of the data used by the vertex processor is encapsulated in a vertex array object.

The command
```
 void GenVertexArraysOES(sizei n, uint *arrays);
```
returns previous unused vertex array object names in . These names are marked as used, for the purposes of GenVertexArraysOES only, but they acquire array state only when they are first bound, just as if they were unused.

Vertex array objects are deleted by calling
```
 void DeleteVertexArraysOES(sizei n, const uint *arrays);
```
contains names of vertex array objects to be deleted. Once a vertex array object is deleted it has no contents and its name becomes unused again. If a vertex array object that is currently bound is deleted, the binding for that object reverts to zero and the default vertex array becomes current. Unused names in are silently ignored, as if they have the value zero. The name space for vertex array objects is the unsigned integers, with zero reserved for the GL ES. A vertex array object is created by binding an unused name with the command void BindVertexArrayOES(uint array);

IF(ES1)

 and <array> here is the vertex array object name. The resulting
 vertex array object is a new state vector, comprising all the state
 values (listed in Tables 6.4 & 6.5, except CLIENT_ACTIVE_TEXTURE
 and ARRAY_BUFFER_BINDING):

 VERTEX_ARRAY,
 VERTEX_ARRAY_SIZE,
 VERTEX_ARRAY_TYPE,
 VERTEX_ARRAY_STRIDE,
 VERTEX_ARRAY_POINTER,
 VERTEX_ARRAY_BUFFER_BINDING,

 NORMAL_ARRAY,
 NORMAL_ARRAY_TYPE,
 NORMAL_ARRAY_STRIDE,
 NORMAL_ARRAY_POINTER,
 NORMAL_ARRAY_BUFFER_BINDING,

 COLOR_ARRAY,
 COLOR_ARRAY_SIZE,
 COLOR_ARRAY_TYPE,
 COLOR_ARRAY_STRIDE,
 COLOR_ARRAY_POINTER,
 COLOR_ARRAY_BUFFER_BINDING,

 TEXTURE_COORD_ARRAY,
 TEXTURE_COORD_ARRAY_SIZE,
 TEXTURE_COORD_ARRAY_TYPE,
 TEXTURE_COORD_ARRAY_STRIDE,
 TEXTURE_COORD_ARRAY_POINTER,
 TEXTURE_COORD_ARRAY_BUFFER_BINDING,

 POINT_SIZE_ARRAY_OES,
 POINT_SIZE_ARRAY_TYPE_OES,
 POINT_SIZE_ARRAY_STRIDE_OES,
 POINT_SIZE_ARRAY_POINTER_OES,
 POINT_SIZE_ARRAY_BUFFER_BINDING_OES,

 ELEMENT_ARRAY_BUFFER_BINDING.

 BindVertexArrayOES may also be used to bind an existing vertex
 array object. If the binding is successful, no change is made to
 the state of the bound vertex array object, and any previous
 binding is broken.

 BindVertexArrayOES fails and an INVALID_OPERATION error is
 generated if array is not a name returned from a previous call to
 GenVertexArraysOES, or if such a name has since been deleted with
 DeleteVertexArraysOES. An INVALID_OPERATION error is generated if
 any of the *Pointer commands specifying the location and
 organization of vertex array data are called while a non-zero
 vertex array object is bound, zero is bound to the ARRAY_BUFFER
 buffer object binding point, and the pointer argument is not NULL
 [fn1].
    [fn1: This error makes it impossible to create a vertex array
     object containing client array pointers, while still allowing
     buffer objects to be unbound.]

 The currently bound vertex array object is used for all commands
 that modify vertex array state, such as
     VertexPointer,
     NormalPointer,
     ColorPointer,
     TexCoordPointer,
     PointSizePointerOES,
     EnableClientState,
     DisableClientState,
     ClientActiveTexture,
 all commands that draw from vertex arrays, such as
     DrawArrays
     DrawElements,
 and all queries of vertex array state (see Chapter 6).
  

END(ES1)

IF(ES2)

 and <array> here is the vertex array object name. The resulting
 vertex array object is a new state vector, comprising all the state
 values (listed in Table 6.2, except ARRAY_BUFFER_BINDING):

      VERTEX_ATTRIB_ARRAY_ENABLED,
      VERTEX_ATTRIB_ARRAY_SIZE,
      VERTEX_ATTRIB_ARRAY_STRIDE,
      VERTEX_ATTRIB_ARRAY_TYPE,
      VERTEX_ATTRIB_ARRAY_NORMALIZED,
      VERTEX_ATTRIB_ARRAY_POINTER,
      ELEMENT_ARRAY_BUFFER_BINDING,
      VERTEX_ATTRIB_ARRAY_BUFFER_BINDING.

 BindVertexArrayOES may also be used to bind an existing vertex
 array object. If the binding is successful, no change is made to
 the state of the bound vertex array object, and any previous
 binding is broken.

 BindVertexArrayOES fails and an INVALID_OPERATION error is
 generated if array is not a name returned from a previous call to
 GenVertexArraysOES, or if such a name has since been deleted with
 DeleteVertexArraysOES. An INVALID_OPERATION error is generated if
 VertexAttribPointer is called while a non-zero vertex array object
 is bound, zero is bound to the <ARRAY_BUFFER> buffer object binding
 point and the pointer argument is not NULL [fn1].
    [fn1: This error makes it impossible to create a vertex array
     object containing client array pointers, while still allowing
     buffer objects to be unbound.]

 The currently bound vertex array object is used for all commands
 that modify vertex array state, such as VertexAttribPointer and
 EnableVertexAttribArray; all commands that draw from vertex arrays,
 such as DrawArrays and DrawElements; and all queries of vertex
 array state (see Chapter 6).
  

END(ES2)

 And the presently attached vertex array object has the following
 impacts on the draw commands:

      While a non-zero vertex array object is bound, if any enabled
      array's buffer binding is zero, when DrawArrays or
      DrawElements is called, the result is undefined.
  

Additions to Chapter 3 (Rasterization)

None.

Additions to Chapter 4 (Per-Fragment Operations and the Framebuffer)

None.

Additions to Chapter 5 (Special Functions)

None.

Additions to Chapter 6 (State and State Requests)

IF(ES1)

Add a new paragraph at the end of Section 6.1.2: Data Conversions (Page 119).

Vertex array state variables are qualified by the value of VERTEX_ARRAY_BINDING_OES to determine which vertex array object is queried. Tables 6.4 & 6.5 define the set of state stored in a vertex array object.
Add a new Section "6.1.X Vertex Array Object Queries" after Sections "6.1.6 Buffer Object Queries" (Page 120).

The command
```
 boolean IsVertexArrayOES(uint array);
```
returns TRUE if is the name of a vertex array object. If
is zero, or a non-zero value that is not the name of a vertex array object, IsVertexArrayOES returns FALSE. No error is generated if is not a valid array object name.

END(ES1)

IF(ES2)

Add a new paragraph at the end of Section 6.1.2: Data Conversions (Page 123).

Vertex array state variables are qualified by the value of VERTEX_ARRAY_BINDING_OES to determine which vertex array object is queried. Table 6.2 defines the set of state stored in a vertex array object.
Add a new Section "6.1.X Vertex Array Object Queries" between Sections "6.1.6 Buffer Object Queries" and "6.1.7 Framebuffer Object and Renderbuffer Queries" (Page 126).

The command
```
 boolean IsVertexArrayOES(uint array);
```
returns TRUE if is the name of a vertex array object. If
is zero, or a non-zero value that is not the name of a vertex array object, IsVertexArray returns FALSE. No error is generated if is not a valid array object name.
Modify lines in Section 6.1.8: Shader and Program Queries

Page 131: replace "Note that all the queries except CURRENT_VERTEX_ATTRIB return client state." with "Note that all the queries except CURRENT_VERTEX_ATTRIB return values stored in the currently bound vertex array object (the value of VERTEX_ARRAY_BINDING). If the zero object is bound, then the queries return client state."

Page 131: add lines after " must be VERTEX_ATTRIB_ARRAY_POINTER." The value returned is queried from the currently bound vertex array object. If the zero object is bound, the value is queried from client state.

Additions to Appendix C (Deleting Shared Objects)

Add another section in C.2 Sharing objects across multiple OpenGL ES contexts (Page 163).

Objects which cannot be shared in this manner include: vertex array objects

END(ES2)

IF(ES1)

Dependencies on OES_matrix_palette

If OES_matrix_palette is supported, the language below should be
added into Chapter 2.

The vertex array object can also comprise the following state values:
    MATRIX_INDEX_ARRAY_OES,
    MATRIX_INDEX_ARRAY_SIZE_OES,
    MATRIX_INDEX_ARRAY_TYPE_OES,
    MATRIX_INDEX_ARRAY_STRIDE_OES,
    MATRIX_INDEX_ARRAY_POINTER_OES,
    MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES,

    WEIGHT_ARRAY_OES,
    WEIGHT_ARRAY_SIZE_OES,
    WEIGHT_ARRAY_TYPE_OES,
    WEIGHT_ARRAY_STRIDE_OES,
    WEIGHT_ARRAY_POINTER_OES,
    WEIGHT_ARRAY_BUFFER_BINDING_OES.

And the currently bound vertex array object can also be used for the
following commands
    WeightPointerOES,
    MatrixIndexPointerOES.
  

END(ES1)

Revision History

 Rev.      Date        Author                    Changes    -------  ----------  ------------  -----------------------------------------------------
 16      04/17/14     Jon Leech    Update wording of first issue (Bug 7847).
 15      02/05/10     Jon Leech    Update Status and assign extension number.
                                   Reflow spec text to standard widths.
 14      10/11/09     Ben Bowman   Allow VAO to employ client indices.
 13      09/11/09     Yuan Wang    Forbade VAO to employ client array indices.
 12      04/11/09     Ben Bowman   Updated EXT to OES and adopted resolutions of the
                                   OpenGL ES working group meeting on 04/11/09. (re)
                                   disallow user generated (non Gen'd) names.
 11      23/10/09     Ben Bowman   Fixed INVALID_OPERATION error for client arrays.
 10      14/10/09     Ben Bowman   Adopted resolutions of the OpenGL ES working group
                                   meeting on 14/10/09. (re) disallow client arrays to
                                   be included in VAOs. Disallow sharing of VAOs.
 9       14/10/09     Yuan Wang    Added dependencies on OES_matrix_palette
 8       14/10/09     Ben Bowman   Formatting. Reopen of shared object decision.
 7       09/09/09     Ben Bowman   Cleanup of issues list.
 6       04/09/09     Yuan Wang    Changed contact details and added contributors.
                                   Replaced IMG with EXT, added the extension for ES1
                                   specification and added revision history.
 5       20/08/09     Yuan Wang    Allowed VAO to encapsulate client attribute arrays.
 4       16/07/09     Yuan Wang    Added ELEMENT_ARRAY_BUFFER_BINDING into VAO's
                                   contained states, but took ARRAY_BUFFER_BINDING
                                   out of the states.
 3       07/07/09     Yuan Wang    Removed VERTEX_ARRAY_IMG token, and removed target
                                   param from BindVertexArrayIMG, since there is only
                                   one type of target for VAO.
 2       26/06/09     Yuan Wang    Added IMG affix and VERTEX_ARRAY target for
                                   BindVertexArrayIMG.
 1       15/06/09     Yuan Wang    Initial revision.
  