Name

glBufferData - creates and initializes the data store of a buffer object.

C Specification

void glBufferData(GLenum target,
    GLsizeiptr size,
    const GLvoid * data,
    GLenum usage)

Parameters

target

Specifies the buffer object target. Which must be GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER.

size

Specifies the size of the data store in basic machine units.

data

Specifies the source data in client memory.

usage

Specifies the expected application usage pattern of the data store. Accepted values are GL_STATIC_DRAW and GL_DYNAMIC_DRAW.

Description

glBufferData lets you create and initialize the data store of a buffer object.

If data is non-null, then the source data is copied to the buffer object’s data store. If data is null, then the contents of the buffer object’s data store are undefined.

The options for usage are:

GL_STATIC_DRAW

Where the data store contents will be specified once by the application, and used many times as the source for GL drawing commands.

GL_DYNAMIC_DRAW

Where the data store contents will be respecified repeatedly by the application, and used many times as the source for GL drawing commands.

glBufferData deletes any existing data store, and sets the values of the buffer object’s state variables thus:

GL_BUFFER_SIZE initialized to size.
GL_BUFFER_USAGE initialized to usage.
GL_BUFFER_ACCESS initialized to GL_WRITE_ONLY.

Clients must align data elements consistent with the requirements of the client platform, with an additional base-level requirement that an offset within a buffer to a datum comprising N basic machine units be a multiple of N.

Notes

usage is provided as a performance hint only. The specified usage value does not constrain the actual usage pattern of the data store.

glBufferData and glBufferSubData define two new types that will work well on 64-bit systems, analogous to C’s ”intptr t”. The new type ”GLintptrARB” should be used in place of GLint whenever it is expected that values might exceed 2 billion. The new type ”GLsizeiptrARB” should be used in place of GLsizei whenever it is expected that counts might exceed 2 billion. Both types are defined as signed integers large enough to contain any pointer value. As a result, they naturally scale to larger numbers of bits on systems with 64-bit or even larger pointers.

Errors

GL_INVALID_ENUM is generated if target is not one of the allowable values.

GL_INVALID_ENUM is generated if usage is not one of the allowable values.

GL_OUT_OF_MEMORY is generated if If the GL is unable to create a data store of the requested size.

Copyright

Copyright © 2003-2004 Silicon Graphics, Inc.

This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.

See Also

glBufferSubData, glBindBuffer, glDeleteBuffers, glGenBuffers