glMapBuffer

glMapBuffer: man2/glMapBuffer.xml

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 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.

If an error is generated, glMapBuffer returns null, and glUnmapBuffer returns GL_FALSE. glMapBuffer and glUnmapBuffer are available only if the GL version is 1.5 or greater. GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER are available only if the GL version is 2.1 or greater. 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.