Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> | |
4 | <refentry id="glMapBufferRange"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>2012</year> | |
9 | <holder>Khronos Group</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>glMapBufferRange</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>glMapBufferRange</refname> | |
17 | <refpurpose>map a section of a buffer object's data store</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void *<function>glMapBufferRange</function></funcdef> | |
23 | <paramdef>GLenum <parameter>target</parameter></paramdef> | |
24 | <paramdef>GLintptr <parameter>offset</parameter></paramdef> | |
25 | <paramdef>GLsizeiptr <parameter>length</parameter></paramdef> | |
26 | <paramdef>GLbitfield <parameter>access</parameter></paramdef> | |
27 | </funcprototype> | |
28 | </funcsynopsis> | |
29 | </refsynopsisdiv> | |
30 | <refsect1 id="parameters"><title>Parameters</title> | |
31 | <variablelist> | |
32 | <varlistentry> | |
33 | <term><parameter>target</parameter></term> | |
34 | <listitem> | |
35 | <para> | |
36 | Specifies a binding to which the target buffer is bound. | |
37 | </para> | |
38 | </listitem> | |
39 | </varlistentry> | |
40 | <varlistentry> | |
41 | <term><parameter>offset</parameter></term> | |
42 | <listitem> | |
43 | <para> | |
44 | Specifies a the starting offset within the buffer of the range to be mapped. | |
45 | </para> | |
46 | </listitem> | |
47 | </varlistentry> | |
48 | <varlistentry> | |
49 | <term><parameter>length</parameter></term> | |
50 | <listitem> | |
51 | <para> | |
52 | Specifies a length of the range to be mapped. | |
53 | </para> | |
54 | </listitem> | |
55 | </varlistentry> | |
56 | <varlistentry> | |
57 | <term><parameter>access</parameter></term> | |
58 | <listitem> | |
59 | <para> | |
60 | Specifies a combination of access flags indicating the desired access to the range. | |
61 | </para> | |
62 | </listitem> | |
63 | </varlistentry> | |
64 | </variablelist> | |
65 | </refsect1> | |
66 | <refsect1 id="description"><title>Description</title> | |
67 | <para> | |
68 | <function>glMapBufferRange</function> maps all or part of the data store of a buffer object into the client's address | |
69 | space. <parameter>target</parameter> specifies the target to which the buffer is bound and must be one of <constant>GL_ARRAY_BUFFER</constant>, | |
70 | <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, | |
71 | <constant>GL_COPY_READ_BUFFER</constant>, <constant>GL_COPY_WRITE_BUFFER</constant>, <constant>GL_DRAW_INDIRECT_BUFFER</constant>, | |
72 | <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>, | |
73 | <constant>GL_PIXEL_PACK_BUFFER</constant>, <constant>GL_PIXEL_UNPACK_BUFFER</constant>, <constant>GL_TEXTURE_BUFFER</constant>, | |
74 | <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant>, <constant>GL_UNIFORM_BUFFER</constant> or <constant>GL_SHADER_STORAGE_BUFFER</constant>. <parameter>offset</parameter> and | |
75 | <parameter>length</parameter> indicate the range of data in the buffer object htat is to be mapped, in terms of basic machine units. | |
76 | <parameter>access</parameter> is a bitfield containing flags which describe the requested mapping. These flags are described below. | |
77 | </para> | |
78 | <para> | |
79 | If no error occurs, a pointer to the beginning of the mapped range is returned once all pending operations on that buffer have | |
80 | completed, and may be used to modify and/or query the corresponding range of the buffer, according to the following flag bits set | |
81 | in <parameter>access</parameter>: | |
82 | <itemizedlist> | |
83 | <listitem> | |
84 | <para> | |
85 | <constant>GL_MAP_READ_BIT</constant> indicates that the returned pointer may be used to read | |
86 | buffer object data. No GL error is generated if the pointer is used to query | |
87 | a mapping which excludes this flag, but the result is undefined and system | |
88 | errors (possibly including program termination) may occur. | |
89 | </para> | |
90 | </listitem> | |
91 | <listitem> | |
92 | <para> | |
93 | <constant>GL_MAP_WRITE_BIT</constant> indicates that the returned pointer may be used to modify | |
94 | buffer object data. No GL error is generated if the pointer is used to modify | |
95 | a mapping which excludes this flag, but the result is undefined and system | |
96 | errors (possibly including program termination) may occur. | |
97 | </para> | |
98 | </listitem> | |
99 | </itemizedlist> | |
100 | </para> | |
101 | <para> | |
102 | Furthermore, the following <emphasis>optional</emphasis> flag bits in <parameter>access</parameter> may be used to modify the mapping: | |
103 | <itemizedlist> | |
104 | <listitem> | |
105 | <para> | |
106 | <constant>GL_MAP_INVALIDATE_RANGE_BIT</constant> indicates that the previous contents of the | |
107 | specified range may be discarded. Data within this range are undefined with | |
108 | the exception of subsequently written data. No GL error is generated if sub- | |
109 | sequent GL operations access unwritten data, but the result is undefined and | |
110 | system errors (possibly including program termination) may occur. This flag | |
111 | may not be used in combination with <constant>GL_MAP_READ_BIT</constant>. | |
112 | </para> | |
113 | </listitem> | |
114 | <listitem> | |
115 | <para> | |
116 | <constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant> indicates that the previous contents of the | |
117 | entire buffer may be discarded. Data within the entire buffer are undefined | |
118 | with the exception of subsequently written data. No GL error is generated if | |
119 | subsequent GL operations access unwritten data, but the result is undefined | |
120 | and system errors (possibly including program termination) may occur. This | |
121 | flag may not be used in combination with <constant>GL_MAP_READ_BIT</constant>. | |
122 | </para> | |
123 | </listitem> | |
124 | <listitem> | |
125 | <para> | |
126 | <constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> indicates that one or more discrete subranges | |
127 | of the mapping may be modified. When this flag is set, modifications to | |
128 | each subrange must be explicitly flushed by calling <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>. | |
129 | No GL error is set if a subrange of the mapping is modified and | |
130 | not flushed, but data within the corresponding subrange of the buffer are undefined. | |
131 | This flag may only be used in conjunction with <constant>GL_MAP_WRITE_BIT</constant>. | |
132 | When this option is selected, flushing is strictly limited to regions that are | |
133 | explicitly indicated with calls to <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry> | |
134 | prior to unmap; if this option is not selected <citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry> | |
135 | will automatically flush the entire mapped range when called. | |
136 | </para> | |
137 | </listitem> | |
138 | <listitem> | |
139 | <para> | |
140 | <constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> indicates that the GL should not attempt to | |
141 | synchronize pending operations on the buffer prior to returning from <function>glMapBufferRange</function>. | |
142 | No GL error is generated if pending operations which source or modify the buffer overlap the mapped region, | |
143 | but the result of such previous and any subsequent operations is undefined. | |
144 | </para> | |
145 | </listitem> | |
146 | </itemizedlist> | |
147 | </para> | |
148 | <para> | |
149 | If an error occurs, <function>glMapBufferRange</function> returns a <code>NULL</code> pointer. | |
150 | If no error occurs, the returned pointer will reflect an alignment of at least <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> | |
151 | basic machine units. The value of <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> can be retrieved by calling | |
152 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with <parameter>pname</parameter> set to | |
153 | <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> and must be a power of two that is at least 64. Subtracting <parameter>offset</parameter> | |
154 | from this returned pointed will always produce a multiple of <constant>GL_MIN_MAP_BUFFER_ALINMENT</constant>. | |
155 | </para> | |
156 | </refsect1> | |
157 | <refsect1 id="notes"><title>Notes</title> | |
158 | <para> | |
159 | Alignment of the returned pointer is guaranteed only if the version | |
160 | of the GL version is 4.2 or greater. Also, the <constant>GL_ATOMIC_COUNTER_BUFFER</constant> | |
161 | target is accepted only if the GL version is 4.2 or greater. | |
162 | </para> | |
163 | <para> | |
164 | The <constant>GL_DISPATCH_INDIRECT_BUFFER</constant> and <constant>GL_SHADER_STORAGE_BUFFER</constant> targets are accepted only if the | |
165 | GL version is 4.3 or greater. | |
166 | </para> | |
167 | </refsect1> | |
168 | <refsect1 id="errors"><title>Errors</title> | |
169 | <para> | |
170 | <constant>GL_INVALID_VALUE</constant> is generated if either of <parameter>offset</parameter> or <parameter>length</parameter> is negative, | |
171 | or if <parameter>offset</parameter> + <parameter>length</parameter> is greater than the value of <constant>GL_BUFFER_SIZE</constant>. | |
172 | </para> | |
173 | <para> | |
174 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>access</parameter> has any bits set other than those defined above. | |
175 | </para> | |
176 | <para> | |
177 | <constant>GL_INVALID_OPERATION</constant> is generated for any of the following conditions: | |
178 | <itemizedlist> | |
179 | <listitem> | |
180 | <para> | |
181 | The buffer is already in a mapped state. | |
182 | </para> | |
183 | </listitem> | |
184 | <listitem> | |
185 | <para> | |
186 | Neither <constant>GL_MAP_READ_BIT</constant> or <constant>GL_MAP_WRITE_BIT</constant> is set. | |
187 | </para> | |
188 | </listitem> | |
189 | <listitem> | |
190 | <para> | |
191 | <constant>GL_MAP_READ_BIT</constant> is set and any of <constant>GL_MAP_INVALIDATE_RANGE_BIT</constant>, | |
192 | <constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant>, or <constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> is set. | |
193 | </para> | |
194 | </listitem> | |
195 | <listitem> | |
196 | <para> | |
197 | <constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> is set and <constant>GL_MAP_WRITE_BIT</constant> is not set. | |
198 | </para> | |
199 | </listitem> | |
200 | </itemizedlist> | |
201 | </para> | |
202 | <para> | |
203 | <constant>GL_OUT_OF_MEMORY</constant> is generated if <function>glMapBufferRange</function> fails because memory for the | |
204 | mapping could not be obtained. | |
205 | </para> | |
206 | </refsect1> | |
207 | <refsect1 id="seealso"><title>See Also</title> | |
208 | <para> | |
209 | <citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>, | |
210 | <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>, | |
211 | <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry> | |
212 | </para> | |
213 | </refsect1> | |
214 | <refsect1 id="Copyright"><title>Copyright</title> | |
215 | <para> | |
216 | Copyright <trademark class="copyright"></trademark> 2010-2012 Khronos Group. | |
217 | This material may be distributed subject to the terms and conditions set forth in | |
218 | the Open Publication License, v 1.0, 8 June 1999. | |
219 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. | |
220 | </para> | |
221 | </refsect1> | |
222 | </refentry> |