Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> | |
3 | <!-- saved from url=(0013)about:internet --> | |
4 | <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glMapBufferRange - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glMapBufferRange"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glMapBufferRange — map a section of a buffer object's data store</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void *<b class="fsfunc">glMapBufferRange</b>(</code></td><td>GLenum </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLintptr </td><td><var class="pdparam">offset</var>, </td></tr><tr><td> </td><td>GLsizeiptr </td><td><var class="pdparam">length</var>, </td></tr><tr><td> </td><td>GLbitfield </td><td><var class="pdparam">access</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p> | |
5 | Specifies a binding to which the target buffer is bound. | |
6 | </p></dd><dt><span class="term"><em class="parameter"><code>offset</code></em></span></dt><dd><p> | |
7 | Specifies a the starting offset within the buffer of the range to be mapped. | |
8 | </p></dd><dt><span class="term"><em class="parameter"><code>length</code></em></span></dt><dd><p> | |
9 | Specifies a length of the range to be mapped. | |
10 | </p></dd><dt><span class="term"><em class="parameter"><code>access</code></em></span></dt><dd><p> | |
11 | Specifies a combination of access flags indicating the desired access to the range. | |
12 | </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p> | |
13 | <code class="function">glMapBufferRange</code> maps all or part of the data store of a buffer object into the client's address | |
14 | space. <em class="parameter"><code>target</code></em> specifies the target to which the buffer is bound and must be one of <code class="constant">GL_ARRAY_BUFFER</code>, | |
15 | <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>, | |
16 | <code class="constant">GL_COPY_READ_BUFFER</code>, <code class="constant">GL_COPY_WRITE_BUFFER</code>, <code class="constant">GL_DRAW_INDIRECT_BUFFER</code>, | |
17 | <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>, <code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>, | |
18 | <code class="constant">GL_PIXEL_PACK_BUFFER</code>, <code class="constant">GL_PIXEL_UNPACK_BUFFER</code>, <code class="constant">GL_TEXTURE_BUFFER</code>, | |
19 | <code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code>, <code class="constant">GL_UNIFORM_BUFFER</code> or <code class="constant">GL_SHADER_STORAGE_BUFFER</code>. <em class="parameter"><code>offset</code></em> and | |
20 | <em class="parameter"><code>length</code></em> indicate the range of data in the buffer object htat is to be mapped, in terms of basic machine units. | |
21 | <em class="parameter"><code>access</code></em> is a bitfield containing flags which describe the requested mapping. These flags are described below. | |
22 | </p><p> | |
23 | If no error occurs, a pointer to the beginning of the mapped range is returned once all pending operations on that buffer have | |
24 | completed, and may be used to modify and/or query the corresponding range of the buffer, according to the following flag bits set | |
25 | in <em class="parameter"><code>access</code></em>: | |
26 | </p><div class="itemizedlist"><ul type="disc"><li><p> | |
27 | <code class="constant">GL_MAP_READ_BIT</code> indicates that the returned pointer may be used to read | |
28 | buffer object data. No GL error is generated if the pointer is used to query | |
29 | a mapping which excludes this flag, but the result is undefined and system | |
30 | errors (possibly including program termination) may occur. | |
31 | </p></li><li><p> | |
32 | <code class="constant">GL_MAP_WRITE_BIT</code> indicates that the returned pointer may be used to modify | |
33 | buffer object data. No GL error is generated if the pointer is used to modify | |
34 | a mapping which excludes this flag, but the result is undefined and system | |
35 | errors (possibly including program termination) may occur. | |
36 | </p></li></ul></div><p> | |
37 | </p><p> | |
38 | Furthermore, the following <span class="emphasis"><em>optional</em></span> flag bits in <em class="parameter"><code>access</code></em> may be used to modify the mapping: | |
39 | </p><div class="itemizedlist"><ul type="disc"><li><p> | |
40 | <code class="constant">GL_MAP_INVALIDATE_RANGE_BIT</code> indicates that the previous contents of the | |
41 | specified range may be discarded. Data within this range are undefined with | |
42 | the exception of subsequently written data. No GL error is generated if sub- | |
43 | sequent GL operations access unwritten data, but the result is undefined and | |
44 | system errors (possibly including program termination) may occur. This flag | |
45 | may not be used in combination with <code class="constant">GL_MAP_READ_BIT</code>. | |
46 | </p></li><li><p> | |
47 | <code class="constant">GL_MAP_INVALIDATE_BUFFER_BIT</code> indicates that the previous contents of the | |
48 | entire buffer may be discarded. Data within the entire buffer are undefined | |
49 | with the exception of subsequently written data. No GL error is generated if | |
50 | subsequent GL operations access unwritten data, but the result is undefined | |
51 | and system errors (possibly including program termination) may occur. This | |
52 | flag may not be used in combination with <code class="constant">GL_MAP_READ_BIT</code>. | |
53 | </p></li><li><p> | |
54 | <code class="constant">GL_MAP_FLUSH_EXPLICIT_BIT</code> indicates that one or more discrete subranges | |
55 | of the mapping may be modified. When this flag is set, modifications to | |
56 | each subrange must be explicitly flushed by calling <a href="glFlushMappedBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glFlushMappedBufferRange</span></span></a>. | |
57 | No GL error is set if a subrange of the mapping is modified and | |
58 | not flushed, but data within the corresponding subrange of the buffer are undefined. | |
59 | This flag may only be used in conjunction with <code class="constant">GL_MAP_WRITE_BIT</code>. | |
60 | When this option is selected, flushing is strictly limited to regions that are | |
61 | explicitly indicated with calls to <a href="glFlushMappedBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glFlushMappedBufferRange</span></span></a> | |
62 | prior to unmap; if this option is not selected <a href="glUnmapBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glUnmapBuffer</span></span></a> | |
63 | will automatically flush the entire mapped range when called. | |
64 | </p></li><li><p> | |
65 | <code class="constant">GL_MAP_UNSYNCHRONIZED_BIT</code> indicates that the GL should not attempt to | |
66 | synchronize pending operations on the buffer prior to returning from <code class="function">glMapBufferRange</code>. | |
67 | No GL error is generated if pending operations which source or modify the buffer overlap the mapped region, | |
68 | but the result of such previous and any subsequent operations is undefined. | |
69 | </p></li></ul></div><p> | |
70 | </p><p> | |
71 | If an error occurs, <code class="function">glMapBufferRange</code> returns a <code class="code">NULL</code> pointer. | |
72 | If no error occurs, the returned pointer will reflect an alignment of at least <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> | |
73 | basic machine units. The value of <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> can be retrieved by calling | |
74 | <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with <em class="parameter"><code>pname</code></em> set to | |
75 | <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> and must be a power of two that is at least 64. Subtracting <em class="parameter"><code>offset</code></em> | |
76 | from this returned pointed will always produce a multiple of <code class="constant">GL_MIN_MAP_BUFFER_ALINMENT</code>. | |
77 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p> | |
78 | Alignment of the returned pointer is guaranteed only if the version | |
79 | of the GL version is 4.2 or greater. Also, the <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code> | |
80 | target is accepted only if the GL version is 4.2 or greater. | |
81 | </p><p> | |
82 | The <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code> and <code class="constant">GL_SHADER_STORAGE_BUFFER</code> targets are accepted only if the | |
83 | GL version is 4.3 or greater. | |
84 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p> | |
85 | <code class="constant">GL_INVALID_VALUE</code> is generated if either of <em class="parameter"><code>offset</code></em> or <em class="parameter"><code>length</code></em> is negative, | |
86 | or if <em class="parameter"><code>offset</code></em> + <em class="parameter"><code>length</code></em> is greater than the value of <code class="constant">GL_BUFFER_SIZE</code>. | |
87 | </p><p> | |
88 | <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>access</code></em> has any bits set other than those defined above. | |
89 | </p><p> | |
90 | <code class="constant">GL_INVALID_OPERATION</code> is generated for any of the following conditions: | |
91 | </p><div class="itemizedlist"><ul type="disc"><li><p> | |
92 | The buffer is already in a mapped state. | |
93 | </p></li><li><p> | |
94 | Neither <code class="constant">GL_MAP_READ_BIT</code> or <code class="constant">GL_MAP_WRITE_BIT</code> is set. | |
95 | </p></li><li><p> | |
96 | <code class="constant">GL_MAP_READ_BIT</code> is set and any of <code class="constant">GL_MAP_INVALIDATE_RANGE_BIT</code>, | |
97 | <code class="constant">GL_MAP_INVALIDATE_BUFFER_BIT</code>, or <code class="constant">GL_MAP_UNSYNCHRONIZED_BIT</code> is set. | |
98 | </p></li><li><p> | |
99 | <code class="constant">GL_MAP_FLUSH_EXPLICIT_BIT</code> is set and <code class="constant">GL_MAP_WRITE_BIT</code> is not set. | |
100 | </p></li></ul></div><p> | |
101 | </p><p> | |
102 | <code class="constant">GL_OUT_OF_MEMORY</code> is generated if <code class="function">glMapBufferRange</code> fails because memory for the | |
103 | mapping could not be obtained. | |
104 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p> | |
105 | <a href="glMapBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glMapBuffer</span></span></a>, | |
106 | <a href="glFlushMappedBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glFlushMappedBufferRange</span></span></a>, | |
107 | <a href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a> | |
108 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
109 | Copyright <span class="trademark"></span>© 2010-2012 Khronos Group. | |
110 | This material may be distributed subject to the terms and conditions set forth in | |
111 | the Open Publication License, v 1.0, 8 June 1999. | |
112 | <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>. | |
113 | </p></div></div></body></html> |