GLES3.0中文API--glMapBufferRange
名称
glMapBufferRange — 映射缓冲区对象的数据存储区的一部分
C 规范
void *glMapBufferRange( GLenum target,
GLintptr offset,
GLsizeiptr length,
GLbitfield access);
GLboolean glUnmapBuffer( GLenum target);
glMapBufferRange的参数
target
指定glMapBufferRange缓冲区对象绑定到的目标，该对象必须是下表中的缓冲区绑定目标之一：
| 缓冲区绑定目标 | 用途 |
|---|---|
| GL_ARRAY_BUFFER | Vertex attributes |
| GL_ATOMIC_COUNTER_BUFFER | Atomic counter storage |
| GL_COPY_READ_BUFFER | Buffer copy source |
| GL_COPY_WRITE_BUFFER | Buffer copy destination |
| GL_DISPATCH_INDIRECT_BUFFER | Indirect compute dispatch commands |
| GL_DRAW_INDIRECT_BUFFER | Indirect command arguments |
| GL_ELEMENT_ARRAY_BUFFER | Vertex array indices |
| GL_PIXEL_PACK_BUFFER | Pixel read target |
| GL_PIXEL_UNPACK_BUFFER | Texture data source |
| GL_SHADER_STORAGE_BUFFER | Read-write storage for shaders |
| GL_TEXTURE_BUFFER | Texture data buffer |
| GL_TRANSFORM_FEEDBACK_BUFFER | Transform feedback buffer |
| GL_UNIFORM_BUFFER | Uniform block storage |
offset
指定要映射范围的缓冲区内的起始偏移量。
length
指定要映射的范围的长度。
access
指定访问标志的组合，以指示对该范围的所需访问。
glUnmapBuffer的参数
target
指定绑定目标缓冲区的绑定。
描述
glMapBufferRange将缓冲区对象的全部或部分数据存储区映射到客户端的地址空间。目标指定了缓冲必然且必须GL_ARRAY_BUFFER，GL_ATOMIC_COUNTER_BUFFER，GL_COPY_READ_BUFFER，GL_COPY_WRITE_BUFFER，GL_DISPATCH_INDIRECT_BUFFER，GL_DRAW_INDIRECT_BUFFER，GL_ELEMENT_ARRAY_BUFFER，GL_PIXEL_PACK_BUFFER，GL_PIXEL_UNPACK_BUFFER，GL_SHADER_STORAGE_BUFFER，GL_TRANSFORM_FEEDBACK_BUFFER或GL_UNIFORM_BUFFER之一的目标。 offset和length表示要映射的缓冲区对象中的数据范围（以基本机器单位为单位）。访问是一个包含描述请求映射的标志的位域。这些标志描述如下。
如果没有错误发生，则在该缓冲区上的所有未完成操作完成后，将返回指向映射范围开头的指针，并且可以根据以下标志位将其用于修改和/或查询缓冲区的相应范围。访问中：
GL_MAP_READ_BIT指示返回的指针可用于读取缓冲区对象数据。如果使用指针查询不包含该标志的映射，则不会产生GL错误，但是结果是不确定的，并且可能发生系统错误（可能包括程序终止）。
GL_MAP_WRITE_BIT指示返回的指针可用于修改缓冲区对象数据。如果使用指针修改不包含该标志的映射，则不会产生GL错误，但是结果是不确定的，并且可能发生系统错误（可能包括程序终止）。
此外，访问中的以下可选标志位可用于修改映射：
GL_MAP_INVALIDATE_RANGE_BIT表示指定范围的先前内容可能会被丢弃。除随后写入的数据外，未定义此范围内的数据。如果后续的GL操作访问未写入的数据，则不会产生GL错误，但是结果是不确定的，并且可能发生系统错误（可能包括程序终止）。该标志不能与GL_MAP_READ_BIT结合使用。
GL_MAP_INVALIDATE_BUFFER_BIT指示可以丢弃整个缓冲区的先前内容。除随后写入的数据外，整个缓冲区内的数据均未定义。如果后续的GL操作访问未写入的数据，则不会产生GL错误，但是结果是不确定的，并且可能发生系统错误（可能包括程序终止）。该标志不能与GL_MAP_READ_BIT结合使用。
GL_MAP_FLUSH_EXPLICIT_BIT指示可以修改映射的一个或多个离散子范围。设置此标志后，必须通过调用glFlushMappedBufferRange显式清除对每个子范围的修改。如果修改了映射的子范围并且未刷新，则不会设置GL错误，但是未定义缓冲区相应子范围内的数据。该标志只能与GL_MAP_WRITE_BIT一起使用。当选择此选项时，刷新将严格限于取消映射之前对glFlushMappedBufferRange的调用明确指示的区域；如果未选择此选项，则glUnmapBuffer会在调用时自动刷新整个映射范围。
GL_MAP_UNSYNCHRONIZED_BIT指示GL在从glMapBufferRange返回之前，不应尝试对缓冲区上的未决操作进行同步。如果源或修改缓冲区的挂起操作与映射区域重叠，但是未定义此类先前操作和任何后续操作的结果，则不会生成GL错误。
如果发生错误，则glMapBufferRange返回NULL指针。
必须先使用glUnmapBuffer将映射的数据存储区取消映射，然后再使用其缓冲区对象。否则，任何试图取消引用缓冲区对象数据存储区的GL命令都会产生错误。取消映射数据存储区时，指向其数据存储区的指针将变为无效。 glUnmapBuffer返回GL_TRUE，除非在映射数据存储期间数据存储的内容已损坏。发生这种情况的原因可能是系统特定的原因，这些原因会影响图形内存的可用性，例如屏幕模式更改。在这种情况下，将返回GL_FALSE且数据存储内容未定义。应用程序必须检测到这种罕见情况并重新初始化数据存储。
当删除缓冲区对象或使用glBufferData重新创建缓冲区对象的数据存储区时，缓冲区对象的映射数据存储区将自动取消映射。
注意
到缓冲区对象的数据存储区的映射可能具有非标准的性能特征。例如，这样的映射可能被标记为内存的不可缓存区域，在这种情况下，从它们的读取可能非常慢。为了确保最佳性能，客户端应以与GL_BUFFER_USAGE和access的值一致的方式使用映射。以与这些值不一致的方式使用映射可能会比使用普通内存慢多个数量级。
仅当GL ES版本为3.1或更高版本时，GL_ATOMIC_COUNTER_BUFFER，GL_DISPATCH_INDIRECT_BUFFER，GL_DRAW_INDIRECT_BUFFER和GL_SHADER_STORAGE_BUFFER目标才可用。
仅当GL ES版本为3.2或更高版本时，GL_TEXTURE_BUFFER目标才可用。
错误
如果offset或length均为负数，或者offset + length大于GL_BUFFER_SIZE的值，则生成GL_INVALID_VALUE。
如果访问具有除上述定义之外的任何其他位，则生成GL_INVALID_VALUE。
GL_INVALID_OPERATION是为以下任何条件生成的：
缓冲区已处于映射状态。
GL_MAP_READ_BIT或GL_MAP_WRITE_BIT均未设置。
设置了GL_MAP_READ_BIT，并且设置了GL_MAP_INVALIDATE_RANGE_BIT，GL_MAP_INVALIDATE_BUFFER_BIT或GL_MAP_UNSYNCHRONIZED_BIT中的任何一个。
设置了GL_MAP_FLUSH_EXPLICIT_BIT，未设置GL_MAP_WRITE_BIT。
如果glMapBufferRange因为无法获取映射的内存而失败，则生成GL_OUT_OF_MEMORY。
API支持版本
函数名| 2.0 |3.0| 3.1| 3.2
glMapBufferRange| -| ✔| ✔| ✔|
glUnmapBuffer| -| ✔| ✔| ✔|
另见
glBindBuffer glFlushMappedBufferRange, glUnmapBuffer,
版权
https://www.khronos.org/registry/OpenGL-Refpages/es3/html/glMapBufferRange.xhtml
Copyright © 2010-2015 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/.