'\" t
.\"     Title: glMapBufferRange
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 05/30/2012
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "GLMAPBUFFERRANGE" "3G" "05/30/2012" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glMapBufferRange \- map a section of a buffer object\*(Aqs data store
.SH "C SPECIFICATION"
.HP \w'void\ *glMapBufferRange('u
.BI "void *glMapBufferRange(GLenum\ " "target" ", GLintptr\ " "offset" ", GLsizeiptr\ " "length" ", GLbitfield\ " "access" ");"
.SH "PARAMETERS"
.PP
\fItarget\fR
.RS 4
Specifies a binding to which the target buffer is bound\&.
.RE
.PP
\fIoffset\fR
.RS 4
Specifies a the starting offset within the buffer of the range to be mapped\&.
.RE
.PP
\fIlength\fR
.RS 4
Specifies a length of the range to be mapped\&.
.RE
.PP
\fIaccess\fR
.RS 4
Specifies a combination of access flags indicating the desired access to the range\&.
.RE
.SH "DESCRIPTION"
.PP

\fBglMapBufferRange\fR
maps all or part of the data store of a buffer object into the client\*(Aqs address space\&.
\fItarget\fR
specifies the target to which the buffer is bound and must be one of
\fBGL_ARRAY_BUFFER\fR,
\fBGL_ATOMIC_COUNTER_BUFFER\fR,
\fBGL_COPY_READ_BUFFER\fR,
\fBGL_COPY_WRITE_BUFFER\fR,
\fBGL_ELEMENT_ARRAY_BUFFER\fR,
\fBGL_PIXEL_PACK_BUFFER\fR,
\fBGL_PIXEL_UNPACK_BUFFER\fR,
\fBGL_TEXTURE_BUFFER\fR,
\fBGL_TRANSFORM_FEEDBACK_BUFFER\fR, or
\fBGL_UNIFORM_BUFFER\fR\&.
\fIoffset\fR
and
\fIlength\fR
indicate the range of data in the buffer object htat is to be mapped, in terms of basic machine units\&.
\fIaccess\fR
is a bitfield containing flags which describe the requested mapping\&. These flags are described below\&.
.PP
If no error occurs, a pointer to the beginning of the mapped range is returned once all pending operations on that buffer have completed, and may be used to modify and/or query the corresponding range of the buffer, according to the following flag bits set in
\fIaccess\fR:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_READ_BIT\fR
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_WRITE_BIT\fR
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\&.
.RE
.PP
Furthermore, the following
\fIoptional\fR
flag bits in
\fIaccess\fR
may be used to modify the mapping:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_INVALIDATE_RANGE_BIT\fR
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
\fBGL_MAP_READ_BIT\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_INVALIDATE_BUFFER_BIT\fR
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
\fBGL_MAP_READ_BIT\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_FLUSH_EXPLICIT_BIT\fR
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
\fBglFlushMappedBufferRange\fR()\&. 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
\fBGL_MAP_WRITE_BIT\fR\&. When this option is selected, flushing is strictly limited to regions that are explicitly indicated with calls to
\fBglFlushMappedBufferRange\fR()
prior to unmap; if this option is not selected
\fBglUnmapBuffer\fR()
will automatically flush the entire mapped range when called\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_UNSYNCHRONIZED_BIT\fR
indicates that the GL should not attempt to synchronize pending operations on the buffer prior to returning from
\fBglMapBufferRange\fR\&. 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\&.
.RE
.PP
If an error occurs,
\fBglMapBufferRange\fR
returns a
NULL
pointer\&. If no error occurs, the returned pointer will reflect an alignment of at least
\fBGL_MIN_MAP_BUFFER_ALIGNMENT\fR
basic machine units\&. The value of
\fBGL_MIN_MAP_BUFFER_ALIGNMENT\fR
can be retrieved by calling
\fBglGet\fR()
with
\fIpname\fR
set to
\fBGL_MIN_MAP_BUFFER_ALIGNMENT\fR
and must be a power of two that is at least 64\&. Subtracting
\fIoffset\fR
from this returned pointed will always produce a multiple of
\fBGL_MIN_MAP_BUFFER_ALINMENT\fR\&.
.SH "NOTES"
.PP
Alignment of the returned pointer is guaranteed only if the version of the GL version is 4\&.2 or greater\&. Also, the
\fBGL_ATOMIC_COUNTER_BUFFER\fR
target is accepted only if the GL version is 4\&.2 or greater\&.
.SH "ERRORS"
.PP

\fBGL_INVALID_VALUE\fR
is generated if either of
\fIoffset\fR
or
\fIlength\fR
is negative, or if
\fIoffset\fR
+
\fIlength\fR
is greater than the value of
\fBGL_BUFFER_SIZE\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIaccess\fR
has any bits set other than those defined above\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated for any of the following conditions:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The buffer is already in a mapped state\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Neither
\fBGL_MAP_READ_BIT\fR
or
\fBGL_MAP_WRITE_BIT\fR
is set\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_READ_BIT\fR
is set and any of
\fBGL_MAP_INVALIDATE_RANGE_BIT\fR,
\fBGL_MAP_INVALIDATE_BUFFER_BIT\fR, or
\fBGL_MAP_UNSYNCHRONIZED_BIT\fR
is set\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBGL_MAP_FLUSH_EXPLICIT_BIT\fR
is set and
\fBGL_MAP_WRITE_BIT\fR
is not set\&.
.RE
.PP

\fBGL_OUT_OF_MEMORY\fR
is generated if
\fBglMapBufferRange\fR
fails because memory for the mapping could not be obtained\&.
.SH "SEE ALSO"
.PP

\fBglMapBuffer\fR(),
\fBglFlushMappedBufferRange\fR(),
\fBglBindBuffer\fR()
.SH "COPYRIGHT"
.PP
Copyright
\(co
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\&.
\m[blue]\fBhttp://opencontent\&.org/openpub/\fR\m[]\&.