glBufferStorage, glNamedBufferStorage — creates and initializes a buffer object's immutable data store
void glBufferStorage(
|
GLenum target, |
GLsizeiptr size, | |
const GLvoid * data, | |
GLbitfield flags) ; |
void glNamedBufferStorage(
|
GLuint buffer, |
GLsizei size, | |
const void *data, | |
GLbitfield flags) ; |
target
Specifies the target to which the buffer object is bound for
glBufferStorage
, which must be one of the
buffer binding targets in the following table:
Buffer Binding Target | Purpose |
---|---|
GL_ARRAY_BUFFER
|
Vertex attributes |
GL_ATOMIC_COUNTER_BUFFER
|
Atomic counter storage |
GL_COPY_READ_BUFFER
|
Buffer copy source |
GL_COPY_WRITE_BUFFER
|
Buffer copy destination |
GL_DISPATCH_INDIRECT_BUFFER
|
Indirect compute dispatch commands |
GL_DRAW_INDIRECT_BUFFER
|
Indirect command arguments |
GL_ELEMENT_ARRAY_BUFFER
|
Vertex array indices |
GL_PIXEL_PACK_BUFFER
|
Pixel read target |
GL_PIXEL_UNPACK_BUFFER
|
Texture data source |
GL_QUERY_BUFFER
|
Query result buffer |
GL_SHADER_STORAGE_BUFFER
|
Read-write storage for shaders |
GL_TEXTURE_BUFFER
|
Texture data buffer |
GL_TRANSFORM_FEEDBACK_BUFFER
|
Transform feedback buffer |
GL_UNIFORM_BUFFER
|
Uniform block storage |
buffer
Specifies the name of the buffer object for
glNamedBufferStorage
function.
size
Specifies the size in bytes of the buffer object's new data store.
data
Specifies a pointer to data that will be copied into the data
store for initialization, or NULL
if no data is
to be copied.
flags
Specifies the intended usage of the buffer's data store. Must
be a bitwise combination of the following flags.
GL_DYNAMIC_STORAGE_BIT
,
GL_MAP_READ_BIT
GL_MAP_WRITE_BIT
,
GL_MAP_PERSISTENT_BIT
,
GL_MAP_COHERENT_BIT
, and
GL_CLIENT_STORAGE_BIT
.
glBufferStorage
and
glNamedBufferStorage
create a new immutable data
store. For glBufferStorage
, the buffer object
currently bound to target
will be initialized. For
glNamedBufferStorage
, buffer
is the name of the buffer object that will be configured. The size of the
data store is specified by size
. If an initial data
is available, its address may be supplied in data
.
Otherwise, to create an uninitialized data store,
data
should be NULL
.
The flags
parameters specifies the intended
usage of the buffer's data store. It must be a bitwise combination of a
subset of the following flags:
GL_DYNAMIC_STORAGE_BIT
The contents of the data store may be updated after creation
through calls to
glBufferSubData.
If this bit is not set, the buffer content may
not be directly updated by the client. The data argument may be
used to specify the initial content of the buffer's data store
regardless of the presence of the
GL_DYNAMIC_STORAGE_BIT
. Regardless of the
presence of this bit, buffers may always be updated with
server-side calls such as
glCopyBufferSubData
and
glClearBufferSubData.
GL_MAP_READ_BIT
The data store may be mapped by the client for read access and a pointer in the client's address space obtained that may be read from.
GL_MAP_WRITE_BIT
The data store may be mapped by the client for write access and a pointer in the client's address space obtained that may be written through.
GL_MAP_PERSISTENT_BIT
The client may request that the server read from or write to the buffer while it is mapped. The client's pointer to the data store remains valid so long as the data store is mapped, even during execution of drawing or dispatch commands.
GL_MAP_COHERENT_BIT
Shared access to buffers that are simultaneously mapped for client access and are used by the server will be coherent, so long as that mapping is performed using glMapBufferRange. That is, data written to the store by either the client or server will be immediately visible to the other with no further action taken by the application. In particular,
If GL_MAP_COHERENT_BIT
is not set
and the client performs a write followed by a call to the
glMemoryBarrier
command with the
GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT
set,
then in subsequent commands the server will see the
writes.
If GL_MAP_COHERENT_BIT
is set and
the client performs a write, then in subsequent commands the
server will see the writes.
If GL_MAP_COHERENT_BIT
is not set
and the server performs a write, the application must call
glMemoryBarrier
with the GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT
set
and then call
glFenceSync
with GL_SYNC_GPU_COMMANDS_COMPLETE
(or glFinish
). Then the CPU will see the writes after the sync is complete.
If GL_MAP_COHERENT_BIT
is set and
the server does a write, the app must call glFenceSync
with
GL_SYNC_GPU_COMMANDS_COMPLETE
(or
glFinish).
Then the CPU will see the writes after the
sync is complete.
GL_CLIENT_STORAGE_BIT
When all other criteria for the buffer storage allocation are met, this bit may be used by an implementation to determine whether to use storage that is local to the server or to the client to serve as the backing store for the buffer.
The allowed combinations of flags are subject to certain restrictions. They are as follows:
If flags
contains
GL_MAP_PERSISTENT_BIT
, it must also contain at
least one of GL_MAP_READ_BIT
or
GL_MAP_WRITE_BIT
.
If flags
contains
GL_MAP_COHERENT_BIT
, it must also contain
GL_MAP_PERSISTENT_BIT
.
glBufferStorage
is available only if the GL
version is 4.4 or greater.
glNamedBufferStorage
is available only if the
GL version is 4.5 or greater.
If data
is NULL
, a data
store of the specified size is still created, but its contents remain
uninitialized and thus undefined.
GL_INVALID_ENUM
is generated by
glBufferStorage
if target
is
not one of the accepted buffer targets.
GL_INVALID_OPERATION
is generated by
glNamedBufferStorage
if buffer is not the name of an
existing buffer object.
GL_INVALID_VALUE
is generated if
size
is less than or equal to zero.
GL_INVALID_OPERATION
is generated by
glBufferStorage
if the reserved buffer object name 0
is bound to target
.
GL_OUT_OF_MEMORY
is generated if the GL is
unable to create a data store with the properties requested in
flags
.
GL_INVALID_VALUE
is generated if
flags
has any bits set other than those defined
above.
GL_INVALID_VALUE
error is generated if
flags
contains
GL_MAP_PERSISTENT_BIT
but does not contain at least
one of GL_MAP_READ_BIT
or
GL_MAP_WRITE_BIT
.
GL_INVALID_VALUE
is generated if
flags
contains
GL_MAP_COHERENT_BIT
, but does not also contain
GL_MAP_PERSISTENT_BIT
.
GL_INVALID_OPERATION
is generated by
glBufferStorage
if the
GL_BUFFER_IMMUTABLE_STORAGE
flag of the buffer bound
to target
is GL_TRUE
.
glGetBufferParameter
with argument GL_BUFFER_SIZE
or
GL_BUFFER_USAGE
OpenGL Version | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Function / Feature Name | 2.0 | 2.1 | 3.0 | 3.1 | 3.2 | 3.3 | 4.0 | 4.1 | 4.2 | 4.3 | 4.4 | 4.5 |
glBufferStorage
|
- | - | - | - | - | - | - | - | - | - | ✔ | ✔ |
glNamedBufferStorage
|
- | - | - | - | - | - | - | - | - | - | - | ✔ |
Copyright © 2014 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.