Difference between revisions of "GLAPI/glMapBuffer"

From OpenGL.org
Jump to: navigation, search
m (Renaming category: 'GL 4 API Buffer Objects' to 'Core API Ref Buffer Objects'.)
m (Bot: Adding better formatting.)
 
(11 intermediate revisions by 2 users not shown)
Line 8: Line 8:
 
== Function Definition ==
 
== Function Definition ==
  
   void * '''glMapBuffer'''(GLenum ''target'', GLenum ''access'');
+
   void * '''glMapBuffer'''(GLenum {{param|target}}, GLenum {{param|access}});
  
; target
+
{{glapi buffertargets}}
: Specifies the target buffer object being mapped. The symbolic constant must be {{code|GL_ARRAY_BUFFER}}, {{code|GL_ATOMIC_COUNTER_BUFFER}}, {{code|GL_COPY_READ_BUFFER}}, {{code|GL_COPY_WRITE_BUFFER}}, {{code|GL_ELEMENT_ARRAY_BUFFER}}, {{code|GL_PIXEL_PACK_BUFFER}}, {{code|GL_PIXEL_UNPACK_BUFFER}}, {{code|GL_TEXTURE_BUFFER}}, {{code|GL_TRANSFORM_FEEDBACK_BUFFER}} or {{code|GL_UNIFORM_BUFFER}}.
+
 
; access
 
; 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 {{code|GL_READ_ONLY}}, {{code|GL_WRITE_ONLY}}, or {{code|GL_READ_WRITE}}.
+
: 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 {{enum|GL_READ_ONLY}}, {{enum|GL_WRITE_ONLY}}, or {{enum|GL_READ_WRITE}}.
  
 
== Function Definition ==
 
== Function Definition ==
  
   GLboolean '''glUnmapBuffer'''(GLenum ''target'');
+
   GLboolean '''glUnmapBuffer'''(GLenum {{param|target}});
  
 
; target
 
; target
: Specifies the target buffer object being unmapped. The symbolic constant must be {{code|GL_ARRAY_BUFFER}}, {{code|GL_COPY_READ_BUFFER}}, {{code|GL_COPY_WRITE_BUFFER}}, {{code|GL_ELEMENT_ARRAY_BUFFER}}, {{code|GL_PIXEL_PACK_BUFFER}}, {{code|GL_PIXEL_UNPACK_BUFFER}}, {{code|GL_TEXTURE_BUFFER}}, {{code|GL_TRANSFORM_FEEDBACK_BUFFER}} or {{code|GL_UNIFORM_BUFFER}}.
+
: Specifies the target buffer object being unmapped. The symbolic constant must be {{enum|GL_ARRAY_BUFFER}}, {{enum|GL_ATOMIC_COUNTER_BUFFER}}, {{enum|GL_COPY_READ_BUFFER}}, {{enum|GL_COPY_WRITE_BUFFER}}, {{enum|GL_DRAW_INDIRECT_BUFFER}}, {{enum|GL_DISPATCH_INDIRECT_BUFFER}}, {{enum|GL_ELEMENT_ARRAY_BUFFER}}, {{enum|GL_PIXEL_PACK_BUFFER}}, {{enum|GL_PIXEL_UNPACK_BUFFER}}, {{enum|GL_SHADER_STORAGE_BUFFER}}, {{enum|GL_TEXTURE_BUFFER}}, {{enum|GL_TRANSFORM_FEEDBACK_BUFFER}} or {{enum|GL_UNIFORM_BUFFER}}.
  
 
== Description ==
 
== 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 {{code|NULL}}. 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 {{code|GL_MIN_MAP_BUFFER_ALIGNMENT}} basic machine units. The value of {{code|GL_MIN_MAP_BUFFER_ALIGNMENT}} can be retrieved by calling [[GLAPI/glGet|glGet]] with ''pname'' set to {{code|GL_MIN_MAP_BUFFER_ALIGNMENT}} and must be a power of two that is at least 64.
+
'''glMapBuffer''' maps to the client's address space the entire data store of the buffer object currently bound to {{param|target}}. The data can then be directly read and/or written relative to the returned pointer, depending on the specified {{param|access}} policy. If the GL is unable to map the buffer object's data store, '''glMapBuffer''' generates an error and returns {{code|NULL}}. 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 {{enum|GL_MIN_MAP_BUFFER_ALIGNMENT}} basic machine units. The value of {{enum|GL_MIN_MAP_BUFFER_ALIGNMENT}} can be retrieved by calling {{apifunc|glGet}} with {{param|pname}} set to {{enum|GL_MIN_MAP_BUFFER_ALIGNMENT}} and must be a power of two that is at least 64.
  
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.
+
If a mapped data store is accessed in a way inconsistent with the specified {{param|access}} policy, no error is generated, but performance may be negatively impacted and system errors, including program termination, may result. Unlike the {{param|usage}} parameter of '''glBufferData''', {{param|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 {{param|usage}} and {{param|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 {{code|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, {{code|GL_FALSE}} is returned and the data store contents are undefined. An application must detect this rare condition and reinitialize the data store.
+
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 {{enum|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, {{enum|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'''.
 
A buffer object's mapped data store is automatically unmapped when the buffer object is deleted or its data store is recreated with '''glBufferData'''.
Line 34: Line 33:
 
== Notes ==
 
== Notes ==
  
If an error is generated, '''glMapBuffer''' returns {{code|NULL}}, and '''glUnmapBuffer''' returns {{code|GL_FALSE}}.
+
If an error is generated, '''glMapBuffer''' returns {{code|NULL}}, and '''glUnmapBuffer''' returns {{enum|GL_FALSE}}.
  
 
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.
 
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.
  
Alignment of the returned pointer is guaranteed only if the version of the GL version is 4.2 or greater. Also, the {{code|GL_ATOMIC_COUNTER_BUFFER}} target is accepted only if the GL version is 4.2 or greater.
+
Alignment of the returned pointer is guaranteed only if the version of the GL version is 4.2 or greater. Also, the {{enum|GL_ATOMIC_COUNTER_BUFFER}} target is accepted only if the GL version is 4.2 or greater.
 +
 
 +
The {{enum|GL_DISPATCH_INDIRECT_BUFFER}} and {{enum|GL_SHADER_STORAGE_BUFFER}} targets are available only if the GL version is 4.3 or greater.
 +
 
 +
The {{enum|GL_QUERY_BUFFER}} target is available only if the GL version is 4.4 or greater.
  
 
== Errors ==
 
== Errors ==
  
{{code|GL_INVALID_ENUM}} is generated if ''target'' is not one of the accepted targets.
+
{{enum|GL_INVALID_ENUM}} is generated if {{param|target}} is not one of the accepted targets.
  
{{code|GL_INVALID_ENUM}} is generated if ''access'' is not {{code|GL_READ_ONLY}}, {{code|GL_WRITE_ONLY}}, or {{code|GL_READ_WRITE}}.
+
{{enum|GL_INVALID_ENUM}} is generated if {{param|access}} is not {{enum|GL_READ_ONLY}}, {{enum|GL_WRITE_ONLY}}, or {{enum|GL_READ_WRITE}}.
  
{{code|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.
+
{{enum|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.
  
{{code|GL_INVALID_OPERATION}} is generated if the reserved buffer object name 0 is bound to ''target''.
+
{{enum|GL_INVALID_OPERATION}} is generated if the reserved buffer object name 0 is bound to {{param|target}}.
  
{{code|GL_INVALID_OPERATION}} is generated if '''glMapBuffer''' is executed for a buffer object whose data store is already mapped.
+
{{enum|GL_INVALID_OPERATION}} is generated if '''glMapBuffer''' is executed for a buffer object whose data store is already mapped.
  
{{code|GL_INVALID_OPERATION}} is generated if '''glUnmapBuffer''' is executed for a buffer object whose data store is not currently mapped.
+
{{enum|GL_INVALID_OPERATION}} is generated if '''glUnmapBuffer''' is executed for a buffer object whose data store is not currently mapped.
  
 
== Associated Gets ==
 
== Associated Gets ==
  
[[GLAPI/glGetBufferPointerv|glGetBufferPointerv]] with argument {{code|GL_BUFFER_MAP_POINTER}}
+
{{apifunc|glGetBufferPointerv}} with argument {{enum|GL_BUFFER_MAP_POINTER}}
  
[[GLAPI/glGetBufferParameter|glGetBufferParameter]] with argument {{code|GL_BUFFER_MAPPED}}, {{code|GL_BUFFER_ACCESS}}, or {{code|GL_BUFFER_USAGE}}
+
{{apifunc|glGetBufferParameter}} with argument {{enum|GL_BUFFER_MAPPED}}, {{enum|GL_BUFFER_ACCESS}}, or {{enum|GL_BUFFER_USAGE}}
  
 
== See Also ==
 
== See Also ==
  
[[GLAPI/glBindBuffer|glBindBuffer]], [[GLAPI/glBindBufferBase|glBindBufferBase]], [[GLAPI/glBindBufferRange|glBindBufferRange]], [[GLAPI/glBufferData|glBufferData]], [[GLAPI/glBufferSubData|glBufferSubData]], [[GLAPI/glDeleteBuffers|glDeleteBuffers]]
+
{{apifunc|glBindBuffer}}, {{apifunc|glMapBufferRange}}, {{apifunc|glBufferData}}, {{apifunc|glFlushMappedBufferRange}}
  
 
== Copyright ==
 
== Copyright ==
Line 68: Line 71:
 
Copyright © 2005 Addison-Wesley. 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/ http://opencontent.org/openpub/].
 
Copyright © 2005 Addison-Wesley. 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/ http://opencontent.org/openpub/].
  
[[Category:API Reference 4|MapBuffer]]
 
 
[[Category:Core API Ref Buffer Objects|MapBuffer]]
 
[[Category:Core API Ref Buffer Objects|MapBuffer]]
 +
[[Category:Core API Reference|MapBuffer]]
 +
[[Category:Buffer Object API State Functions|MapBuffer]]

Latest revision as of 06:02, 15 August 2013

glMapBuffer
Core in version 4.5
Core since version 1.5

glMapBuffer: map a buffer object's data store

Function Definition

 void * glMapBuffer(GLenum target​, GLenum access​);
target
Specifies the target buffer object. The symbolic constant must be GL_ARRAY_BUFFER, GL_ATOMIC_COUNTER_BUFFER, GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER, GL_DRAW_INDIRECT_BUFFER, GL_DISPATCH_INDIRECT_BUFFER, GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER, GL_PIXEL_UNPACK_BUFFER, GL_QUERY_BUFFER, GL_SHADER_STORAGE_BUFFER, GL_TEXTURE_BUFFER, GL_TRANSFORM_FEEDBACK_BUFFER, or GL_UNIFORM_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.

Function Definition

 GLboolean glUnmapBuffer(GLenum target​);
target
Specifies the target buffer object being unmapped. The symbolic constant must be GL_ARRAY_BUFFER, GL_ATOMIC_COUNTER_BUFFER, GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER, GL_DRAW_INDIRECT_BUFFER, GL_DISPATCH_INDIRECT_BUFFER, GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER, GL_PIXEL_UNPACK_BUFFER, GL_SHADER_STORAGE_BUFFER, GL_TEXTURE_BUFFER, GL_TRANSFORM_FEEDBACK_BUFFER or GL_UNIFORM_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 no error occurs, the returned pointer will have 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.

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.

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.

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.

The GL_DISPATCH_INDIRECT_BUFFER and GL_SHADER_STORAGE_BUFFER targets are available only if the GL version is 4.3 or greater.

The GL_QUERY_BUFFER target is available only if the GL version is 4.4 or greater.

Errors

GL_INVALID_ENUM is generated if target​ is not one of the accepted targets.

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.

Associated Gets

glGetBufferPointerv with argument GL_BUFFER_MAP_POINTER

glGetBufferParameter with argument GL_BUFFER_MAPPED, GL_BUFFER_ACCESS, or GL_BUFFER_USAGE

See Also

glBindBuffer, glMapBufferRange, glBufferData, glFlushMappedBufferRange

Copyright

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