NAME¶
glMapBuffer - map a buffer object's data store
C SPECIFICATION¶
void *
glMapBuffer(GLenum target,
GLenum access);
PARAMETERS¶
target
Specifies the target buffer object being
mapped. The symbolic constant must be GL_ARRAY_BUFFER,
GL_ATOMIC_COUNTER_BUFFER, GL_COPY_READ_BUFFER,
GL_COPY_WRITE_BUFFER, GL_ELEMENT_ARRAY_BUFFER,
GL_PIXEL_PACK_BUFFER, GL_PIXEL_UNPACK_BUFFER,
GL_TEXTURE_BUFFER, GL_TRANSFORM_FEEDBACK_BUFFER or
GL_UNIFORM_BUFFER.
access
Specifies the access policy, indicating
whether it will be possible to read from, write to, or both read from and
write to the buffer object's mapped data store. The symbolic constant must be
GL_READ_ONLY, GL_WRITE_ONLY, or GL_READ_WRITE.
C SPECIFICATION¶
GLboolean
glUnmapBuffer(GLenum target);
PARAMETERS¶
target
Specifies the target buffer object being
unmapped. The symbolic constant must be GL_ARRAY_BUFFER,
GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER,
GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER,
GL_PIXEL_UNPACK_BUFFER, GL_TEXTURE_BUFFER,
GL_TRANSFORM_FEEDBACK_BUFFER or GL_UNIFORM_BUFFER.
DESCRIPTION¶
glMapBuffer maps to the client's address space the entire data store of
the buffer object currently bound to
target. The data can then be
directly read and/or written relative to the returned pointer, depending on
the specified
access policy. If the GL is unable to map the buffer
object's data store,
glMapBuffer generates an error and returns
NULL. This may occur for system-specific reasons, such as low virtual
memory availability. If no error occurs, the returned pointer will have an
alignment of at least
GL_MIN_MAP_BUFFER_ALIGNMENT basic machine units.
The value of
GL_MIN_MAP_BUFFER_ALIGNMENT can be retrieved by calling
glGet() with
pname set to
GL_MIN_MAP_BUFFER_ALIGNMENT and
must be a power of two that is at least 64.
If a mapped data store is accessed in a way inconsistent with the specified
access policy, no error is generated, but performance may be negatively
impacted and system errors, including program termination, may result. Unlike
the
usage parameter of
glBufferData,
access is not a
hint, and does in fact constrain the usage of the mapped data store on some GL
implementations. In order to achieve the highest performance available, a
buffer object's data store should be used in ways consistent with both its
specified
usage and
access parameters.
A mapped data store must be unmapped with
glUnmapBuffer before its buffer
object is used. Otherwise an error will be generated by any GL command that
attempts to dereference the buffer object's data store. When a data store is
unmapped, the pointer to its data store becomes invalid.
glUnmapBuffer
returns
GL_TRUE unless the data store contents have become corrupt
during the time the data store was mapped. This can occur for system-specific
reasons that affect the availability of graphics memory, such as screen mode
changes. In such situations,
GL_FALSE is returned and the data store
contents are undefined. An application must detect this rare condition and
reinitialize the data store.
A buffer object's mapped data store is automatically unmapped when the buffer
object is deleted or its data store is recreated with
glBufferData.
NOTES¶
If an error is generated,
glMapBuffer returns
NULL, and
glUnmapBuffer returns
GL_FALSE.
Parameter values passed to GL commands may not be sourced from the returned
pointer. No error will be generated, but results will be undefined and will
likely vary across GL implementations.
Alignment of the returned pointer is guaranteed only if the version of the GL
version is 4.2 or greater. Also, the
GL_ATOMIC_COUNTER_BUFFER target is
accepted only if the GL version is 4.2 or greater.
ERRORS¶
GL_INVALID_ENUM is generated if
target is not one of the accepted
targets.
GL_INVALID_ENUM is generated if
access is not
GL_READ_ONLY,
GL_WRITE_ONLY, or
GL_READ_WRITE.
GL_OUT_OF_MEMORY is generated when
glMapBuffer is executed if the
GL is unable to map the buffer object's data store. This may occur for a
variety of system-specific reasons, such as the absence of sufficient
remaining virtual memory.
GL_INVALID_OPERATION is generated if the reserved buffer object name 0 is
bound to
target.
GL_INVALID_OPERATION is generated if
glMapBuffer is executed for a
buffer object whose data store is already mapped.
GL_INVALID_OPERATION is generated if
glUnmapBuffer is executed for
a buffer object whose data store is not currently mapped.
ASSOCIATED GETS¶
glGetBufferPointerv() with argument
GL_BUFFER_MAP_POINTER
glGetBufferParameter() with argument
GL_BUFFER_MAPPED,
GL_BUFFER_ACCESS, or
GL_BUFFER_USAGE
SEE ALSO¶
glBindBuffer(),
glBindBufferBase(),
glBindBufferRange(),
glBufferData(),
glBufferSubData(),
glDeleteBuffers()
COPYRIGHT¶
Copyright © 2005 Addison-Wesley. Copyright © 2010-2011 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/.