| |
| Name |
| |
| ATI_vertex_array_object |
| |
| |
| Name Strings |
| |
| GL_ATI_vertex_array_object |
| |
| |
| Contact |
| |
| Rick Hammerstone, AMD (rick.hammerstone 'at' amd.com) |
| |
| |
| Version |
| |
| 1.11 - 11/04/06 |
| Updated contact info after ATI/AMD merger. |
| |
| 1.1 - 01/08/02 |
| Changed DeleteObjectBufferATI to FreeObjectBufferATI to match the |
| glati.h header file. Removed objbuf attribute. |
| |
| 1.01 - 09/18/01 |
| Added clarification that ArrayObectATI and VariantArrayObjectATI |
| are not allowed between Begin/End but may not return an error. |
| |
| 1.0 - 09/06/01 |
| Changed references to ATI_vertex_shader to EXT_vertex_shader. |
| |
| 0.9 - 08/15/01 |
| Added support for variant arrays. |
| |
| 0.8 - 07/06/01 |
| Added table of new state. |
| |
| 0.7 - 07/02/01 |
| Added official enumerants. |
| |
| 0.6 - 05/07/01 |
| Chopped out most of the new entry points. Back to just object |
| buffers and one call to define vertex arrays in an object buffer. |
| |
| 0.5 - 04/18/01 |
| The great renaming. Added sample usage section. Expanded issues |
| section. |
| |
| 0.4 - 04/09/01 |
| Rewrote to use new entry points. |
| |
| 0.3 - 04/06/01 |
| Changed Allocate and Free to New and Delete. |
| |
| 0.2 - 03/26/01 |
| Added error description, additions to section 5 and 6 of the spec. |
| |
| 0.1 |
| Original version |
| |
| Number |
| |
| 247 |
| |
| Dependencies |
| |
| This extension is written against the OpenGL 1.2.1 Specification. |
| OpenGL 1.1 is required. GL_EXT_vertex_shader affects the |
| definition of this extension. |
| |
| |
| Overview |
| |
| This extension defines an interface that allows multiple sets of |
| vertex array data to be cached in persistent server-side memory. |
| It is intended to allow client data to be stored in memory that |
| can be directly accessed by graphics hardware. |
| |
| |
| Issues |
| |
| Should this extension include support for allowing vertex indices |
| to be stored on the server? |
| |
| RESOLUTION: NO. This might not be universally supported, and |
| seems simple enough to layer on top of this extension. |
| |
| Is there a better name for this extension? |
| |
| RESOLUTION: YES. The ArrayStore vs. StoredArray terminology |
| was confusing. StoredArrays have been changed to be |
| ArrayObjects. Since any type of object could be stored in the |
| ArrayStore, these have been changed to ObjectBuffers. |
| |
| Should the layout of an array store be defined at array store |
| creation time? |
| |
| RESOLUTION: NO. This could provide better performance if the |
| client specifies a data type that the hardware doesn't |
| support, but this isn't a performance path anyways, and it |
| adds a cumbersome interface on top of the extension. |
| |
| Should the client be able to retrieve a pointer to the array store |
| instead of a handle? |
| |
| RESOLUTION: NO. For now, it doesn't seem like this is a big |
| win, and it presents problems on certain OS's. It also |
| requires using an explicit synchronization mechanism. This |
| would be pretty trivial to add, however. |
| |
| Should this just sit on top of the existing vertex array |
| implementation, instead of introducing a new set of API calls? |
| |
| RESOLUTION: NO. Trying to fit something on top existing vertex |
| arrays introduces a lot of confusion as to where the data is |
| stored (on the client side vs. on the server side). Adding new |
| API that mirrors traditional vertex arrays doesn't seem to |
| cumbersome. |
| |
| |
| New Procedures and Functions |
| |
| For creating, updating, and querying object buffers: |
| |
| uint NewObjectBufferATI(sizei size, const void *pointer, enum usage) |
| |
| boolean IsObjectBufferATI(uint buffer) |
| |
| void UpdateObjectBufferATI(uint buffer, uint offset, sizei size, |
| const void *pointer, enum preserve) |
| |
| void GetObjectBufferfvATI(uint buffer, enum pname, float *params) |
| |
| void GetObjectBufferivATI(uint buffer, enum pname, int *params) |
| |
| void FreeObjectBufferATI(uint buffer) |
| |
| |
| For defining vertex arrays inside an object buffer: |
| |
| void ArrayObjectATI(enum array, int size, enum type, |
| sizei stride, uint buffer, uint offset) |
| |
| For querying vertex arrays inside an object buffer: |
| |
| void GetArrayObjectfvATI(enum array, enum pname, float *params) |
| |
| void GetArrayObjectivATI(enum array, enum pname, int *params) |
| |
| If EXT_vertex_shader is defined, for defining variant arrays inside |
| an object buffer: |
| |
| void VariantArrayObjectATI(uint id, enum type, sizei stride, |
| uint buffer, uint offset) |
| |
| If EXT_vertex_shader is defined, for querying variant arrays inside |
| an object buffer: |
| |
| void GetVariantArrayObjectfvATI(uint id, enum pname, |
| float *params) |
| |
| void GetVariantArrayObjectivATI(uint id, enum pname, |
| int *params) |
| |
| |
| New Tokens |
| |
| Accepted by the <usage> parameter of NewObjectBufferATI: |
| |
| STATIC_ATI 0x8760 |
| DYNAMIC_ATI 0x8761 |
| |
| Accepted by the <preserve> parameter of UpdateObjectBufferATI: |
| |
| PRESERVE_ATI 0x8762 |
| DISCARD_ATI 0x8763 |
| |
| Accepted by the <pname> parameter of GetObjectBufferivATI and |
| GetObjectBufferfvATI: |
| |
| OBJECT_BUFFER_SIZE_ATI 0x8764 |
| OBJECT_BUFFER_USAGE_ATI 0x8765 |
| |
| Accepted by the <pname> parameter of GetArrayObjectivATI and |
| GetArrayObjectfvATI: |
| |
| ARRAY_OBJECT_BUFFER_ATI 0x8766 |
| ARRAY_OBJECT_OFFSET_ATI 0x8767 |
| |
| |
| Additions to Chapter 2 of the GL Specification (OpenGL Operation) |
| |
| In section 2.6.3, GL Commands within Begin/End, add ArrayObjectATI |
| to the list of commands that are not allowed within any Begin/End |
| pair, but may or may not generate an error. If EXT_vertex_shader |
| is defined, add VariantArrayObjectATI to the list of commands that |
| are not allowed within any Begin/End pair, but may or may not |
| generate an error. |
| |
| |
| Inserted between section 2.8, Vertex Arrays, and section 2.9, |
| Rectangles, a new section titled Vertex Array Objects. |
| |
| In order to provide more a more efficient mechanism for storing |
| frequently used vertex array data on the server side, a client may |
| use the command |
| |
| uint NewObjectBufferATI(sizei size, const void *pointer, |
| enum usage); |
| |
| to allocate a persistent buffer in which client data may be |
| stored. <size> specifies the size of the allocation in machine |
| units (hereafter assumed to be unsigned bytes). <pointer> |
| specifies a region of client memory that contains data to |
| initialize the object buffer. If <pointer> is null, then the |
| object buffer is created but not initialized. |
| |
| <usage> provides a hint to the implementation of whether the |
| contents of the object buffer will be static or dynamic. <usage> |
| must be either STATIC_ATI or DYNAMIC_ATI. If the client specifies |
| an object buffer as static, its contents may still be updated, |
| however this may result in reduced performance. |
| |
| The return value is a positive integer that uniquely identifies |
| the object buffer. If the object buffer cannot be allocated, the |
| return value is zero. |
| |
| When the client creates an object buffer using NewObjectBufferATI, |
| the implementation can provide more efficient transfers of data |
| between the client and the graphics controller by allocating the |
| object buffer in memory that can be directly addressed by the |
| graphics controller. In addition, because the object buffer is |
| persistent across multiple drawing commands, static data must only |
| be copied to the object buffer once. |
| |
| To modify the data contained in the object buffer, the client may |
| use the command |
| |
| void UpdateObjectBufferATI(uint buffer, uint offset, |
| sizei size, const void *pointer, |
| enum preserve); |
| |
| <buffer> identifies the object buffer to be updated. <offset> and |
| <size> indicate the range of data in the object buffer that is to |
| be updated. <pointer> specifies a region of client memory that |
| contains data to update the object buffer. |
| |
| The client can use the <preserve> parameter of |
| UpdateObjectBufferATI to indicate whether data outside the region |
| being updated must be preserved. <preserve> must be one of |
| PRESERVE_ATI or DISCARD_ATI. If a client specifies that data |
| outside the range being updated may be discarded, the |
| implementation may be able process updates in a more optimal |
| fashion. |
| |
| Whenever UpdateObjectBufferATI is called, the byte values in the |
| object buffer from <offset> to <offset> + <size> - 1 are updated |
| with the data referenced by <pointer>. If the client specifies |
| PRESERVE_ATI, all other byte values in the object buffer remain |
| unchanged. If the client specifies DISCARD_ATI, then all byte |
| values outside the range that has been updated become undefined. |
| |
| Once created, an object buffer remains available for use until it |
| is destroyed by calling |
| |
| void FreeObjectBufferATI(uint buffer); |
| |
| <buffer> identifies the object buffer to be destroyed. |
| |
| After creating an object buffer, the client can use the command |
| |
| void ArrayObjectATI(enum array, int size, enum type, |
| sizei stride, uint buffer, uint offset); |
| |
| to allow a portion of the object buffer to be used as a vertex |
| array. <array> specifies the array to be defined. This must match |
| one of the allowable enumerants accepted by EnableClientState and |
| DisableClientState. <size>, <type>, and <stride> specify the |
| format and packing of the data stored in the array in the same |
| manner as the corresponding vertex array pointer command. <size> |
| and <type> must match the allowed sizes and types given for the |
| corresponding commands in table 2.4. |
| |
| <buffer> specifies the object buffer that contains the data to be |
| used as a vertex array. <offset> specifies the offset in machine |
| units into the object buffer at which the vertex array data |
| begins. When a vertex array is specified in this manner, the |
| memory pointer that is part of the client state for the vertex |
| array is set to null to indicate that the vertex array has been |
| defined using ArrayObjectATI instead of one of the pointer |
| commands. |
| |
| Vertex arrays that are defined to reside within an object buffer |
| function in the same manner as normal vertex arrays. They are |
| enabled and disabled by using the commands EnableClientState and |
| DisableClientState. Primitives can be constructed using |
| ArrayElement, DrawArrays, DrawElements, and DrawRangeElements. |
| Clients may use mix of traditional vertex arrays and vertex array |
| objects to specify geometry. |
| |
| There is no explicit mechanism to define interleaved vertex arrays |
| in an object buffer. This can be implicitly done by storing the |
| arrays in an interleaved fashion during NewObjectBufferATI or |
| UpdateObjectBufferATI. |
| |
| If EXT_vertex_shader is defined, then a client can define an array |
| of variant data using the command: |
| |
| void VariantArrayObjectATI(uint id, enum type, sizei stride, |
| uint buffer, uint offset); |
| |
| <id> indicates the variant that this array should be associated |
| with. The <type>, <stride>, <buffer>, and <offset> parameters |
| have the same meaning as the corresponding parameters of |
| ArrayObjectATI. As always, variant arrays have a fixed size of 4 |
| components. |
| |
| Variant arrays defined by VariantArrayObjectATI are enabled and |
| disabled in the same way as variant arrays defined by |
| VariantPointerATI, by using EnableVariantClientStateATI and |
| DisableVariantClientStateATI. |
| |
| |
| Additions to Chapter 3 of the 1.2.1 Specification (Rasterization) |
| |
| None |
| |
| |
| Additions to Chapter 4 of the 1.2.1 Specification (Per-Fragment |
| Operations and the Frame Buffer) |
| |
| None |
| |
| |
| Additions to Chapter 5 of the 1.2.1 Specification (Special Functions) |
| |
| Added to section 5.4, as part of the discussion of what commands |
| are compiled into display lists: |
| |
| The commands defined by this extension function in the same manner |
| as the traditional vertex array commands when they are compiled |
| into a display list. |
| |
| Commands that are used to create and manage memory for stored |
| arrays are not included in display lists, but are executed |
| immediately. These include NewObjectBufferATI, IsObjectBufferATI, |
| UpdateObjectBufferATI, GetObjectBufferfvATI, GetObjectBufferivATI, |
| and FreeObjectBufferATI. |
| |
| Commands that are used to define and query vertex arrays within an |
| object buffer are not included in display lists, but are executed |
| immediately. These include ArrayObjectATI, GetArrayObjectfvATI, |
| and GetArrayObjectivATI. |
| |
| |
| Additions to Chapter 6 of the 1.2.1 Specification (State and State |
| Requests) |
| |
| Added to section 6.1 in a subsection titled Object Buffer Queries: |
| |
| The command |
| |
| boolean IsObjectBufferATI(uint buffer) |
| |
| returns TRUE if <buffer> is the name of an object buffer. If |
| <buffer> is zero, or if <buffer> is a non-zero value that is not |
| the name of an object buffer, IsObjectBufferATI return FALSE. |
| |
| Added to the list of queries in section 6.1.3, Enumerated Queries: |
| |
| void GetObjectBuffer{if}vATI(uint buffer, enum value, T data); |
| void GetArrayObject{if}vATI(enum array, enum value, T data); |
| |
| If EXT_vertex_shader is defined: |
| |
| void GetVariantArrayObject{if}vATI(uint id, enum value, T data); |
| |
| Appended to the description of the queries in section 6.1.3, |
| Enumerated Queries: |
| |
| GetObjectBuffer is used to retrieve information about an object |
| buffer. <buffer> must identify a valid object buffer. <value> must |
| be one of OBJECT_BUFFER_SIZE_ATI or OBJECT_BUFFER_USAGE_ATI. |
| |
| If <value> is OBJECT_BUFFER_SIZE_ATI, then the size of the object |
| buffer in bytes is returned in <data>. The exact size of the |
| object buffer is an implementation dependent value, but is |
| guaranteed to be at least as large as the value specified by the |
| <size> parameter of NewObjectBufferATI. If <value> is |
| OBJECT_BUFFER_USAGE_ATI, then the value returned in <data> will be |
| either STATIC_ATI or DYNAMIC_ATI. The return value will match the |
| value specified by the <usage> parameter of NewObjectBufferATI. |
| |
| GetArrayObjectATI is used to retrieve information on a vertex |
| array located in an object buffer. <array> indicates the vertex |
| array that is to be queried. It must match one of the allowable |
| enumerants accepted by EnableClientState and DisableClientState. |
| |
| If EXT_vertex_shader is defined, GetVariantArrayObjectATI is used |
| to retrieve information on a variant array located in an object |
| buffer. <id> indicates the variant that is to be queried. |
| |
| For both queries, <value> must be one of ARRAY_OBJECT_BUFFER_ATI, |
| or ARRAY_OBJECT_OFFSET_ATI. For each of these enumerants, the |
| value returned in <data> represents the object buffer that |
| contains the vertex data, or the byte offset from the object |
| buffer at which the first vertex starts, respectively. If the |
| specified vertex array or variant array has not been defined to |
| reside in an object buffer, GetArrayObjectATI will return zero for |
| both enumerants. |
| |
| |
| Errors |
| |
| INVALID_ENUM is generated if the <usage> parameter of |
| NewObjectBufferATI is not STATIC_ATI or DYNAMIC_ATI. |
| |
| OUT_OF_MEMORY may be generated if an object buffer cannot be |
| allocated because the <size> argument of NewObjectBufferATI is |
| too large. |
| |
| INVALID_VALUE is generated if the <buffer> argument of |
| UpdateObjectBufferATI, GetObjectBufferfvATI, GetObjectBufferivATI, |
| FreeObjectBufferATI, and ArrayObjectATI does not identify a |
| valid object buffer. |
| |
| INVALID_VALUE is generated if the <offset> and <size> parameters |
| of UpdateObjectBufferATI would reference a region of memory |
| outside that allocated by the call to NewObjectBufferATI. |
| |
| INVALID_ENUM is generated if the <pname> parameter of |
| GetObjectBufferfvATI and GetObjectBufferivATI is not |
| OBJECT_BUFFER_SIZE_ATI or OBJECT_BUFFER_USAGE_ATI. |
| |
| INVALID_ENUM is generated if the <array> parameter of |
| ArrayObjectATI, GetArrayObjectfvATI, and GetArrayObjectivATI does |
| not match one of the enumerants allowed by EnableClientState and |
| DisableClientState. |
| |
| INVALID_VALUE is generated if the <id> parameter of |
| VariantArrayObjectATI, GetVariantArrayObjectfvATI, and |
| GetVariantArrayObjectivATI does not correspond to a previously |
| defined variant. |
| |
| INVALID_VALUE is generated if the <size> and <type> parameters of |
| ArrayObjectATI do not match the allowable sizes and types given |
| for the pointer command corresponding to the <array> parameter. |
| |
| INVALID_VALUE is generated if the <offset> parameter of |
| ArrayObjectATI is larger than the size of the object buffer as |
| specified by NewObjectBufferATI. |
| |
| INVALID_ENUM is generated if the <pname> parameter of |
| GetArrayObjectfvATI and GetArrayObjectivATI is not |
| ARRAY_OBJECT_BUFFER_ATI or ARRAY_OBJECT_OFFSET_ATI. |
| |
| |
| New State |
| |
| In a new table, Object Buffers |
| |
| Get Value Get Command Type Initial Value Attrib |
| --------- ----------- ---- ------------- ------ |
| OBJECT_BUFFER_SIZE_ATI GetIntegerv Z+ 0 - |
| OBJECT_BUFFER_USAGE_ATI GetIntegerv Z4 STATIC_ATI - |
| |
| ARRAY_OBJECT_BUFFER_ATI GetIntegerv Z+ 0 - |
| ARRAY_OBJECT_OFFSET_ATI GetIntegerv Z+ 0 - |
| |
| |
| Usage Example |
| |
| Here is a simple example that demonstrates usage of the extension. |
| The example provides a comparison between traditional vertex |
| arrays and vertex array objects. Note that this is not a |
| particularly efficient use of vertex array objects, since the |
| array object are only used once before being destroyed. Typically |
| the client will create many array objects and transfer all of its |
| vertex data to the server before beginning any rendering. |
| |
| Traditional vertex arrays: |
| |
| // Define |
| VertexPointer(4, FLOAT, 16, data); |
| ColorPointer(4, UNSIGNED_BYTE, 4, data + 256); |
| |
| // Enable |
| EnableClientState(VERTEX_ARRAY); |
| EnableClientState(COLOR_ARRAY); |
| |
| // Draw |
| DrawArrays(TRIANGLES, 0, 16); |
| |
| // Disable |
| DisableClientState(VERTEX_ARRAY); |
| DisableClientState(COLOR_ARRAY); |
| |
| Vertex array objects: |
| |
| // Create object buffer |
| buffer = NewObjectBufferATI(320, data, STATIC_ATI); |
| |
| // Define |
| ArrayObjectATI(VERTEX_ARRAY, 4, FLOAT, 16, buffer, 0); |
| ArrayObjectATI(COLOR_ARRAY, 4, UNSIGNED_BYTE, 4, buffer, 256); |
| |
| // Enable |
| EnableClientState(VERTEX_ARRAY); |
| EnableClientState(COLOR_ARRAY); |
| |
| // Draw |
| DrawArrays(TRIANGLES, 0, 16); |
| |
| // Disable |
| DisableClientState(VERTEX_ARRAY); |
| DisableClientState(COLOR_ARRAY); |
| |
| // Free object buffer |
| FreeObjectBufferATI(buffer); |
| |
| |
| Implementation Notes |
| |
| For maximum hardware performance, all vertex arrays except for |
| color and secondary color should always be specified to use float |
| as the component type. Color and secondary color arrays may be |
| specified to use either float or 4-component unsigned byte as the |
| component type. |
| |
| Typically, an object buffer will contain all of the vertex |
| information associated with a given object in a scene. This can |
| include multiple arrays of geometry, color, and texture data. If |
| portions of this data are static, and portions are dynamic, |
| greater performance can be achieved by placing the dynamic vertex |
| data in a separate object buffer and updating the entire object |
| buffer at once. |
| |
