'\" t .\" Title: glMapBuffer .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 05/30/2012 .\" Manual: [FIXME: manual] .\" Source: [FIXME: source] .\" Language: English .\" .TH "GLMAPBUFFER" "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" glMapBuffer \- map a buffer object\*(Aqs data store .SH "C SPECIFICATION" .HP \w'void\ *\ glMapBuffer('u .BI "void * glMapBuffer(GLenum\ " "target" ", GLenum\ " "access" ");" .SH "PARAMETERS" .PP \fItarget\fR .RS 4 Specifies the target buffer object being mapped\&. The symbolic constant must be \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\&. .RE .PP \fIaccess\fR .RS 4 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\*(Aqs mapped data store\&. The symbolic constant must be \fBGL_READ_ONLY\fR, \fBGL_WRITE_ONLY\fR, or \fBGL_READ_WRITE\fR\&. .RE .SH "C SPECIFICATION" .HP \w'GLboolean\ glUnmapBuffer('u .BI "GLboolean glUnmapBuffer(GLenum\ " "target" ");" .SH "PARAMETERS" .PP \fItarget\fR .RS 4 Specifies the target buffer object being unmapped\&. The symbolic constant must be \fBGL_ARRAY_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\&. .RE .SH "DESCRIPTION" .PP \fBglMapBuffer\fR maps to the client\*(Aqs address space the entire data store of the buffer object currently bound to \fItarget\fR\&. The data can then be directly read and/or written relative to the returned pointer, depending on the specified \fIaccess\fR policy\&. If the GL is unable to map the buffer object\*(Aqs data store, \fBglMapBuffer\fR generates an error and returns \fBNULL\fR\&. 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 \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\&. .PP If a mapped data store is accessed in a way inconsistent with the specified \fIaccess\fR policy, no error is generated, but performance may be negatively impacted and system errors, including program termination, may result\&. Unlike the \fIusage\fR parameter of \fBglBufferData\fR, \fIaccess\fR 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\*(Aqs data store should be used in ways consistent with both its specified \fIusage\fR and \fIaccess\fR parameters\&. .PP A mapped data store must be unmapped with \fBglUnmapBuffer\fR before its buffer object is used\&. Otherwise an error will be generated by any GL command that attempts to dereference the buffer object\*(Aqs data store\&. When a data store is unmapped, the pointer to its data store becomes invalid\&. \fBglUnmapBuffer\fR returns \fBGL_TRUE\fR 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, \fBGL_FALSE\fR is returned and the data store contents are undefined\&. An application must detect this rare condition and reinitialize the data store\&. .PP A buffer object\*(Aqs mapped data store is automatically unmapped when the buffer object is deleted or its data store is recreated with \fBglBufferData\fR\&. .SH "NOTES" .PP If an error is generated, \fBglMapBuffer\fR returns \fBNULL\fR, and \fBglUnmapBuffer\fR returns \fBGL_FALSE\fR\&. .PP 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\&. .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_ENUM\fR is generated if \fItarget\fR is not one of the accepted targets\&. .PP \fBGL_INVALID_ENUM\fR is generated if \fIaccess\fR is not \fBGL_READ_ONLY\fR, \fBGL_WRITE_ONLY\fR, or \fBGL_READ_WRITE\fR\&. .PP \fBGL_OUT_OF_MEMORY\fR is generated when \fBglMapBuffer\fR is executed if the GL is unable to map the buffer object\*(Aqs data store\&. This may occur for a variety of system\-specific reasons, such as the absence of sufficient remaining virtual memory\&. .PP \fBGL_INVALID_OPERATION\fR is generated if the reserved buffer object name 0 is bound to \fItarget\fR\&. .PP \fBGL_INVALID_OPERATION\fR is generated if \fBglMapBuffer\fR is executed for a buffer object whose data store is already mapped\&. .PP \fBGL_INVALID_OPERATION\fR is generated if \fBglUnmapBuffer\fR is executed for a buffer object whose data store is not currently mapped\&. .SH "ASSOCIATED GETS" .PP \fBglGetBufferPointerv\fR() with argument \fBGL_BUFFER_MAP_POINTER\fR .PP \fBglGetBufferParameter\fR() with argument \fBGL_BUFFER_MAPPED\fR, \fBGL_BUFFER_ACCESS\fR, or \fBGL_BUFFER_USAGE\fR .SH "SEE ALSO" .PP \fBglBindBuffer\fR(), \fBglBindBufferBase\fR(), \fBglBindBufferRange\fR(), \fBglBufferData\fR(), \fBglBufferSubData\fR(), \fBglDeleteBuffers\fR() .SH "COPYRIGHT" .PP Copyright \(co 2005 Addison\-Wesley\&. 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[]\&.