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="glMapBuffer"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>2005</year> | |
9 | <holder>Sams Publishing</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>glMapBuffer</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>glMapBuffer</refname> | |
17 | <refpurpose>map a buffer object's data store</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void * <function>glMapBuffer</function></funcdef> | |
23 | <paramdef>GLenum <parameter>target</parameter></paramdef> | |
24 | <paramdef>GLenum <parameter>access</parameter></paramdef> | |
25 | </funcprototype> | |
26 | </funcsynopsis> | |
27 | </refsynopsisdiv> | |
28 | <refsect1 id="parameters"><title>Parameters</title> | |
29 | <variablelist> | |
30 | <varlistentry> | |
31 | <term><parameter>target</parameter></term> | |
32 | <listitem> | |
33 | <para> | |
34 | Specifies the target buffer object being mapped. | |
35 | The symbolic constant must be | |
36 | <constant>GL_ARRAY_BUFFER</constant>, | |
37 | <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, | |
38 | <constant>GL_COPY_READ_BUFFER</constant>, | |
39 | <constant>GL_COPY_WRITE_BUFFER</constant>, | |
40 | <constant>GL_DRAW_INDIRECT_BUFFER</constant>, | |
41 | <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>, | |
42 | <constant>GL_ELEMENT_ARRAY_BUFFER</constant>, | |
43 | <constant>GL_PIXEL_PACK_BUFFER</constant>, | |
44 | <constant>GL_PIXEL_UNPACK_BUFFER</constant>, | |
45 | <constant>GL_SHADER_STORAGE_BUFFER</constant>, | |
46 | <constant>GL_TEXTURE_BUFFER</constant>, | |
47 | <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant> or | |
48 | <constant>GL_UNIFORM_BUFFER</constant>. | |
49 | </para> | |
50 | </listitem> | |
51 | </varlistentry> | |
52 | <varlistentry> | |
53 | <term><parameter>access</parameter></term> | |
54 | <listitem> | |
55 | <para> | |
56 | Specifies the access policy, indicating whether it will be possible to read from, write to, | |
57 | or both read from and write to the buffer object's mapped data store. The symbolic constant must be | |
58 | <constant>GL_READ_ONLY</constant>, <constant>GL_WRITE_ONLY</constant>, or <constant>GL_READ_WRITE</constant>. | |
59 | </para> | |
60 | </listitem> | |
61 | </varlistentry> | |
62 | </variablelist> | |
63 | </refsect1> | |
64 | <refsynopsisdiv><title>C Specification</title> | |
65 | <funcsynopsis> | |
66 | <funcprototype> | |
67 | <funcdef>GLboolean <function>glUnmapBuffer</function></funcdef> | |
68 | <paramdef>GLenum <parameter>target</parameter></paramdef> | |
69 | </funcprototype> | |
70 | </funcsynopsis> | |
71 | </refsynopsisdiv> | |
72 | <!-- eqn: ignoring delim $$ --> | |
73 | <refsect1 id="parameters2"><title>Parameters</title> | |
74 | <variablelist> | |
75 | <varlistentry> | |
76 | <term><parameter>target</parameter></term> | |
77 | <listitem> | |
78 | <para> | |
79 | Specifies the target buffer object being unmapped. | |
80 | The symbolic constant must be | |
81 | <constant>GL_ARRAY_BUFFER</constant>, | |
82 | <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, | |
83 | <constant>GL_COPY_READ_BUFFER</constant>, | |
84 | <constant>GL_COPY_WRITE_BUFFER</constant>, | |
85 | <constant>GL_DRAW_INDIRECT_BUFFER</constant>, | |
86 | <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>, | |
87 | <constant>GL_ELEMENT_ARRAY_BUFFER</constant>, | |
88 | <constant>GL_PIXEL_PACK_BUFFER</constant>, | |
89 | <constant>GL_PIXEL_UNPACK_BUFFER</constant>, | |
90 | <constant>GL_SHADER_STORAGE_BUFFER</constant>, | |
91 | <constant>GL_TEXTURE_BUFFER</constant>, | |
92 | <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant> or | |
93 | <constant>GL_UNIFORM_BUFFER</constant>. | |
94 | </para> | |
95 | </listitem> | |
96 | </varlistentry> | |
97 | </variablelist> | |
98 | </refsect1> | |
99 | <refsect1 id="description"><title>Description</title> | |
100 | <para> | |
101 | <function>glMapBuffer</function> maps to the client's address space the entire data store of the buffer object | |
102 | currently bound to <parameter>target</parameter>. The data can then be directly read and/or written relative to | |
103 | the returned pointer, depending on the specified <parameter>access</parameter> policy. If the GL is unable to | |
104 | map the buffer object's data store, <function>glMapBuffer</function> generates an error and returns | |
105 | <constant>NULL</constant>. This may occur for system-specific reasons, such as low virtual memory availability. | |
106 | If no error occurs, the returned pointer will have an alignment of at least <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> | |
107 | basic machine units. The value of <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> can be retrieved by calling | |
108 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with <parameter>pname</parameter> set to | |
109 | <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> and must be a power of two that is at least 64. | |
110 | </para> | |
111 | <para> | |
112 | If a mapped data store is accessed in a way inconsistent with the specified <parameter>access</parameter> policy, | |
113 | no error is generated, but performance may be negatively impacted and system errors, including program | |
114 | termination, may result. Unlike the <parameter>usage</parameter> parameter of <function>glBufferData</function>, | |
115 | <parameter>access</parameter> is not a hint, and does in fact constrain the usage of the mapped data store on | |
116 | some GL implementations. In order to achieve the highest performance available, a buffer object's data store | |
117 | should be used in ways consistent with both its specified <parameter>usage</parameter> and | |
118 | <parameter>access</parameter> parameters. | |
119 | </para> | |
120 | <para> | |
121 | A mapped data store must be unmapped with <function>glUnmapBuffer</function> before its buffer object is used. | |
122 | Otherwise an error will be generated by any GL command that attempts to dereference the buffer object's data store. | |
123 | When a data store is unmapped, the pointer to its data store becomes invalid. <function>glUnmapBuffer</function> | |
124 | returns <constant>GL_TRUE</constant> unless the data store contents have become corrupt during the time | |
125 | the data store was mapped. This can occur for system-specific reasons that affect the availability of graphics | |
126 | memory, such as screen mode changes. In such situations, <constant>GL_FALSE</constant> is returned and the | |
127 | data store contents are undefined. An application must detect this rare condition and reinitialize the data store. | |
128 | </para> | |
129 | <para> | |
130 | A buffer object's mapped data store is automatically unmapped when the buffer object is deleted or its data store | |
131 | is recreated with <function>glBufferData</function>. | |
132 | </para> | |
133 | </refsect1> | |
134 | <refsect1 id="notes"><title>Notes</title> | |
135 | <para> | |
136 | If an error is generated, <function>glMapBuffer</function> returns <constant>NULL</constant>, and | |
137 | <function>glUnmapBuffer</function> returns <constant>GL_FALSE</constant>. | |
138 | </para> | |
139 | <para> | |
140 | Parameter values passed to GL commands may not be sourced from the returned pointer. No error will be generated, | |
141 | but results will be undefined and will likely vary across GL implementations. | |
142 | </para> | |
143 | <para> | |
144 | Alignment of the returned pointer is guaranteed only if the version | |
145 | of the GL version is 4.2 or greater. Also, the <constant>GL_ATOMIC_COUNTER_BUFFER</constant> | |
146 | target is accepted only if the GL version is 4.2 or greater. | |
147 | </para> | |
148 | <para> | |
149 | The <constant>GL_DISPATCH_INDIRECT_BUFFER</constant> and <constant>GL_SHADER_STORAGE_BUFFER</constant> targets are available only if the GL version | |
150 | is 4.3 or greater. | |
151 | </para> | |
152 | </refsect1> | |
153 | <refsect1 id="errors"><title>Errors</title> | |
154 | <para> | |
155 | <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not | |
156 | one of the accepted targets. | |
157 | </para> | |
158 | <para> | |
159 | <constant>GL_INVALID_ENUM</constant> is generated if <parameter>access</parameter> is not | |
160 | <constant>GL_READ_ONLY</constant>, <constant>GL_WRITE_ONLY</constant>, or <constant>GL_READ_WRITE</constant>. | |
161 | </para> | |
162 | <para> | |
163 | <constant>GL_OUT_OF_MEMORY</constant> is generated when <function>glMapBuffer</function> is executed | |
164 | if the GL is unable to map the buffer object's data store. This may occur for a variety of system-specific | |
165 | reasons, such as the absence of sufficient remaining virtual memory. | |
166 | </para> | |
167 | <para> | |
168 | <constant>GL_INVALID_OPERATION</constant> is generated if the reserved buffer object name 0 is bound to <parameter>target</parameter>. | |
169 | </para> | |
170 | <para> | |
171 | <constant>GL_INVALID_OPERATION</constant> is generated if <function>glMapBuffer</function> is executed for | |
172 | a buffer object whose data store is already mapped. | |
173 | </para> | |
174 | <para> | |
175 | <constant>GL_INVALID_OPERATION</constant> is generated if <function>glUnmapBuffer</function> is executed for | |
176 | a buffer object whose data store is not currently mapped. | |
177 | </para> | |
178 | </refsect1> | |
179 | <refsect1 id="associatedgets"><title>Associated Gets</title> | |
180 | <para> | |
181 | <citerefentry><refentrytitle>glGetBufferPointerv</refentrytitle></citerefentry> with argument <constant>GL_BUFFER_MAP_POINTER</constant> | |
182 | </para> | |
183 | <para> | |
184 | <citerefentry><refentrytitle>glGetBufferParameter</refentrytitle></citerefentry> with argument <constant>GL_BUFFER_MAPPED</constant>, <constant>GL_BUFFER_ACCESS</constant>, or <constant>GL_BUFFER_USAGE</constant> | |
185 | </para> | |
186 | </refsect1> | |
187 | <refsect1 id="seealso"><title>See Also</title> | |
188 | <para> | |
189 | <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>, | |
190 | <citerefentry><refentrytitle>glBindBufferBase</refentrytitle></citerefentry>, | |
191 | <citerefentry><refentrytitle>glBindBufferRange</refentrytitle></citerefentry>, | |
192 | <citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>, | |
193 | <citerefentry><refentrytitle>glBufferSubData</refentrytitle></citerefentry>, | |
194 | <citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry> | |
195 | </para> | |
196 | </refsect1> | |
197 | <refsect1 id="Copyright"><title>Copyright</title> | |
198 | <para> | |
199 | Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley. | |
200 | Copyright <trademark class="copyright"></trademark> 2010-2011 Khronos Group. | |
201 | This material may be distributed subject to the terms and conditions set forth in | |
202 | the Open Publication License, v 1.0, 8 June 1999. | |
203 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. | |
204 | </para> | |
205 | </refsect1> | |
206 | </refentry> |