table of contents
other versions
GLMAPBUFFERRANGE(3G) | [FIXME: manual] | GLMAPBUFFERRANGE(3G) |
NAME¶
glMapBufferRange - map a section of a buffer object's data storeC SPECIFICATION¶
void
*glMapBufferRange(GLenum target,
GLintptr offset, GLsizeiptr length,
GLbitfield access);
PARAMETERS¶
targetSpecifies a binding to which the target buffer
is bound.
offset
Specifies a the starting offset within the
buffer of the range to be mapped.
length
Specifies a length of the range to be
mapped.
access
Specifies a combination of access flags
indicating the desired access to the range.
DESCRIPTION¶
•
GL_MAP_READ_BIT indicates that the returned pointer may be used to read
buffer object data. No GL error is generated if the pointer is used to query a
mapping which excludes this flag, but the result is undefined and system
errors (possibly including program termination) may occur.
•
GL_MAP_WRITE_BIT indicates that the returned pointer may be used to
modify buffer object data. No GL error is generated if the pointer is used to
modify a mapping which excludes this flag, but the result is undefined and
system errors (possibly including program termination) may occur.
Furthermore, the following optional flag bits in access may be
used to modify the mapping:
•
GL_MAP_INVALIDATE_RANGE_BIT indicates that the previous contents of the
specified range may be discarded. Data within this range are undefined with
the exception of subsequently written data. No GL error is generated if sub-
sequent GL operations access unwritten data, but the result is undefined and
system errors (possibly including program termination) may occur. This flag
may not be used in combination with GL_MAP_READ_BIT.
•
GL_MAP_INVALIDATE_BUFFER_BIT indicates that the previous contents of the
entire buffer may be discarded. Data within the entire buffer are undefined
with the exception of subsequently written data. No GL error is generated if
subsequent GL operations access unwritten data, but the result is undefined
and system errors (possibly including program termination) may occur. This
flag may not be used in combination with GL_MAP_READ_BIT.
•
GL_MAP_FLUSH_EXPLICIT_BIT indicates that one or more discrete subranges
of the mapping may be modified. When this flag is set, modifications to each
subrange must be explicitly flushed by calling
glFlushMappedBufferRange(). No GL error is set if a subrange of the
mapping is modified and not flushed, but data within the corresponding
subrange of the buffer are undefined. This flag may only be used in
conjunction with GL_MAP_WRITE_BIT. When this option is selected,
flushing is strictly limited to regions that are explicitly indicated with
calls to glFlushMappedBufferRange() prior to unmap; if this option is
not selected glUnmapBuffer() will automatically flush the entire mapped
range when called.
•
GL_MAP_UNSYNCHRONIZED_BIT indicates that the GL should not attempt to
synchronize pending operations on the buffer prior to returning from
glMapBufferRange. No GL error is generated if pending operations which
source or modify the buffer overlap the mapped region, but the result of such
previous and any subsequent operations is undefined.
If an error occurs, glMapBufferRange returns a NULL pointer. If no error
occurs, the returned pointer will reflect 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. Subtracting offset from this returned
pointed will always produce a multiple of GL_MIN_MAP_BUFFER_ALINMENT.
NOTES¶
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¶
•The buffer is already in a mapped
state.
•Neither GL_MAP_READ_BIT or
GL_MAP_WRITE_BIT is set.
•
GL_MAP_READ_BIT is set and any of GL_MAP_INVALIDATE_RANGE_BIT,
GL_MAP_INVALIDATE_BUFFER_BIT, or GL_MAP_UNSYNCHRONIZED_BIT is
set.
•
GL_MAP_FLUSH_EXPLICIT_BIT is set and GL_MAP_WRITE_BIT is not
set.
SEE ALSO¶
COPYRIGHT¶
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/.05/30/2012 | [FIXME: source] |