2005
Sams Publishing
glMapBuffer
3G

# 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_ELEMENT_ARRAY_BUFFER`, `GL_PIXEL_PACK_BUFFER`, or `GL_PIXEL_UNPACK_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_ELEMENT_ARRAY_BUFFER`, `GL_PIXEL_PACK_BUFFER`, or `GL_PIXEL_UNPACK_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 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`.

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

## Errors

`GL_INVALID_ENUM` is generated if `target` is not `GL_ARRAY_BUFFER`, `GL_ELEMENT_ARRAY_BUFFER`, `GL_PIXEL_PACK_BUFFER`, or `GL_PIXEL_UNPACK_BUFFER`.

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

`GL_INVALID_OPERATION` is generated if `glMapBuffer` or `glUnmapBuffer` is executed between the execution of glBegin and the corresponding execution of glEnd.

## Associated Gets

glGetBufferPointerv with argument `GL_BUFFER_MAP_POINTER`

glGetBufferParameteriv with argument `GL_BUFFER_MAPPED`, `GL_BUFFER_ACCESS`, or `GL_BUFFER_USAGE`

## See Also

glBindBuffer, glBufferData, glBufferSubData, glDeleteBuffers

## Copyright

Copyright 2005 Addison-Wesley. 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/.