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="glMemoryBarrier"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>2011</year> | |
9 | <holder>Khronos Group</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>glMemoryBarrier</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>glMemoryBarrier</refname> | |
17 | <refpurpose>defines a barrier ordering memory transactions</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void <function>glMemoryBarrier</function></funcdef> | |
23 | <paramdef>GLbitfield <parameter>barriers</parameter></paramdef> | |
24 | </funcprototype> | |
25 | </funcsynopsis> | |
26 | </refsynopsisdiv> | |
27 | <refsect1 id="parameters"><title>Parameters</title> | |
28 | <variablelist> | |
29 | <varlistentry> | |
30 | <term><parameter>barriers</parameter></term> | |
31 | <listitem> | |
32 | <para> | |
33 | Specifies the barriers to insert. Must be a bitwise combination of <constant>GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</constant>, | |
34 | <constant>GL_ELEMENT_ARRAY_BARRIER_BIT</constant>, <constant>GL_UNIFORM_BARRIER_BIT</constant>, <constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant>, | |
35 | <constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant>, <constant>GL_COMMAND_BARRIER_BIT</constant>, <constant>GL_PIXEL_BUFFER_BARRIER_BIT</constant>, | |
36 | <constant>GL_TEXTURE_UPDATE_BARRIER_BIT</constant>, <constant>GL_BUFFER_UPDATE_BARRIER_BIT</constant>, | |
37 | <constant>GL_FRAMEBUFFER_BARRIER_BIT</constant>, <constant>GL_TRANSFORM_FEEDBACK_BARRIER_BIT</constant>, <constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant>, | |
38 | or <constant>GL_SHADER_STORAGE_BARRIER_BIT</constant>. | |
39 | If the special value <constant>GL_ALL_BARRIER_BITS</constant> is specified, all supported barriers will be inserted. | |
40 | </para> | |
41 | </listitem> | |
42 | </varlistentry> | |
43 | </variablelist> | |
44 | </refsect1> | |
45 | <refsect1 id="description"><title>Description</title> | |
46 | <para> | |
47 | <function>glMemoryBarrier</function> defines a barrier ordering the memory transactions issued prior to the | |
48 | command relative to those issued after the barrier. For the purposes of | |
49 | this ordering, memory transactions performed by shaders are considered to | |
50 | be issued by the rendering command that triggered the execution of the | |
51 | shader. <parameter>barriers</parameter> is a bitfield indicating the set of operations that | |
52 | are synchronized with shader stores; the bits used in <parameter>barriers</parameter> are as | |
53 | follows: | |
54 | </para> | |
55 | <para> | |
56 | <variablelist> | |
57 | <varlistentry> | |
58 | <term><constant>GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</constant></term> | |
59 | <listitem> | |
60 | <para> | |
61 | If set, vertex data sourced from | |
62 | buffer objects after the barrier will reflect data written by shaders | |
63 | prior to the barrier. The set of buffer objects affected by this bit | |
64 | is derived from the buffer object bindings used for | |
65 | generic vertex attributes derived from the <constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER</constant> bindings. | |
66 | </para> | |
67 | </listitem> | |
68 | </varlistentry> | |
69 | <varlistentry> | |
70 | <term><constant>GL_ELEMENT_ARRAY_BARRIER_BIT</constant></term> | |
71 | <listitem> | |
72 | <para> | |
73 | If set, vertex array indices sourced from | |
74 | buffer objects after the barrier will reflect data written by shaders | |
75 | prior to the barrier. The buffer objects affected by this bit are | |
76 | derived from the <constant>GL_ELEMENT_ARRAY_BUFFER</constant> binding. | |
77 | </para> | |
78 | </listitem> | |
79 | </varlistentry> | |
80 | <varlistentry> | |
81 | <term><constant>GL_UNIFORM_BARRIER_BIT</constant></term> | |
82 | <listitem> | |
83 | <para> | |
84 | Shader uniforms sourced from buffer objects after the barrier will reflect data | |
85 | written by shaders prior to the barrier. | |
86 | </para> | |
87 | </listitem> | |
88 | </varlistentry> | |
89 | <varlistentry> | |
90 | <term><constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant></term> | |
91 | <listitem> | |
92 | <para> | |
93 | Texture fetches from shaders, including | |
94 | fetches from buffer object memory via buffer textures, after the | |
95 | barrier will reflect data written by shaders prior to the barrier. | |
96 | </para> | |
97 | </listitem> | |
98 | </varlistentry> | |
99 | <varlistentry> | |
100 | <term><constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant></term> | |
101 | <listitem> | |
102 | <para> | |
103 | Memory accesses using shader image | |
104 | load, store, and atomic built-in functions issued after the barrier | |
105 | will reflect data written by shaders prior to the barrier. | |
106 | Additionally, image stores and atomics issued after the barrier will | |
107 | not execute until all memory accesses (e.g., loads, stores, texture | |
108 | fetches, vertex fetches) initiated prior to the barrier complete. | |
109 | </para> | |
110 | </listitem> | |
111 | </varlistentry> | |
112 | <varlistentry> | |
113 | <term><constant>GL_COMMAND_BARRIER_BIT</constant></term> | |
114 | <listitem> | |
115 | <para> | |
116 | Command data sourced from buffer objects by | |
117 | Draw*Indirect commands after the barrier will reflect data written by | |
118 | shaders prior to the barrier. The buffer objects affected by this bit | |
119 | are derived from the <constant>GL_DRAW_INDIRECT_BUFFER</constant> binding. | |
120 | </para> | |
121 | </listitem> | |
122 | </varlistentry> | |
123 | <varlistentry> | |
124 | <term><constant>GL_PIXEL_BUFFER_BARRIER_BIT</constant></term> | |
125 | <listitem> | |
126 | <para> | |
127 | Reads and writes of buffer objects via the | |
128 | <constant>GL_PIXEL_PACK_BUFFER</constant> and <constant>GL_PIXEL_UNPACK_BUFFER</constant> | |
129 | bindings (via <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>, | |
130 | <citerefentry><refentrytitle>glTexSubImage</refentrytitle></citerefentry>, etc.) after the | |
131 | barrier will reflect data written by shaders prior to the barrier. | |
132 | Additionally, buffer object writes issued after the barrier will wait | |
133 | on the completion of all shader writes initiated prior to the barrier. | |
134 | </para> | |
135 | </listitem> | |
136 | </varlistentry> | |
137 | <varlistentry> | |
138 | <term><constant>GL_TEXTURE_UPDATE_BARRIER_BIT</constant></term> | |
139 | <listitem> | |
140 | <para> | |
141 | Writes to a texture via <function>glTex(Sub)Image*</function>, | |
142 | <function>glCopyTex(Sub)Image*</function>, <function>glCompressedTex(Sub)Image*</function>, and reads via | |
143 | <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry> after the barrier will reflect data written by shaders | |
144 | prior to the barrier. Additionally, texture writes from these | |
145 | commands issued after the barrier will not execute until all shader | |
146 | writes initiated prior to the barrier complete. | |
147 | </para> | |
148 | </listitem> | |
149 | </varlistentry> | |
150 | <varlistentry> | |
151 | <term><constant>GL_BUFFER_UPDATE_BARRIER_BIT</constant></term> | |
152 | <listitem> | |
153 | <para> | |
154 | Reads or writes via <citerefentry><refentrytitle>glBufferSubData</refentrytitle></citerefentry>, | |
155 | <citerefentry><refentrytitle>glCopyBufferSubData</refentrytitle></citerefentry>, | |
156 | or <citerefentry><refentrytitle>glGetBufferSubData</refentrytitle></citerefentry>, or | |
157 | to buffer object memory mapped by <citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry> | |
158 | or <citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry> after the barrier | |
159 | will reflect data written by shaders prior to the barrier. | |
160 | Additionally, writes via these commands issued after the barrier will | |
161 | wait on the completion of any shader writes to the same memory | |
162 | initiated prior to the barrier. | |
163 | </para> | |
164 | </listitem> | |
165 | </varlistentry> | |
166 | <varlistentry> | |
167 | <term><constant>GL_FRAMEBUFFER_BARRIER_BIT</constant></term> | |
168 | <listitem> | |
169 | <para> | |
170 | Reads and writes via framebuffer object | |
171 | attachments after the barrier will reflect data written by shaders | |
172 | prior to the barrier. Additionally, framebuffer writes issued after | |
173 | the barrier will wait on the completion of all shader writes issued | |
174 | prior to the barrier. | |
175 | </para> | |
176 | </listitem> | |
177 | </varlistentry> | |
178 | <varlistentry> | |
179 | <term><constant>GL_TRANSFORM_FEEDBACK_BARRIER_BIT</constant></term> | |
180 | <listitem> | |
181 | <para> | |
182 | Writes via transform feedback | |
183 | bindings after the barrier will reflect data written by shaders prior | |
184 | to the barrier. Additionally, transform feedback writes issued after | |
185 | the barrier will wait on the completion of all shader writes issued | |
186 | prior to the barrier. | |
187 | </para> | |
188 | </listitem> | |
189 | </varlistentry> | |
190 | <varlistentry> | |
191 | <term><constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant></term> | |
192 | <listitem> | |
193 | <para> | |
194 | Accesses to atomic counters after the | |
195 | barrier will reflect writes prior to the barrier. | |
196 | </para> | |
197 | </listitem> | |
198 | </varlistentry> | |
199 | <varlistentry> | |
200 | <term><constant>GL_SHADER_STORAGE_BARRIER_BIT</constant></term> | |
201 | <listitem> | |
202 | <para> | |
203 | Accesses to shader storage blocks after the | |
204 | barrier will reflect writes prior to the barrier. | |
205 | </para> | |
206 | </listitem> | |
207 | </varlistentry> | |
208 | </variablelist> | |
209 | </para> | |
210 | <para> | |
211 | If <parameter>barriers</parameter> is <constant>GL_ALL_BARRIER_BITS</constant>, shader memory accesses | |
212 | will be synchronized relative to all the operations described above. | |
213 | </para> | |
214 | <para> | |
215 | Implementations may cache buffer object and texture image memory that | |
216 | could be written by shaders in multiple caches; for example, there may be | |
217 | separate caches for texture, vertex fetching, and one or more caches for | |
218 | shader memory accesses. Implementations are not required to keep these | |
219 | caches coherent with shader memory writes. Stores issued by one | |
220 | invocation may not be immediately observable by other pipeline stages or | |
221 | other shader invocations because the value stored may remain in a cache | |
222 | local to the processor executing the store, or because data overwritten by | |
223 | the store is still in a cache elsewhere in the system. When <function>glMemoryBarrier</function> | |
224 | is called, the GL flushes and/or invalidates any caches relevant to the | |
225 | operations specified by the <parameter>barriers</parameter> parameter to ensure consistent | |
226 | ordering of operations across the barrier. | |
227 | </para> | |
228 | <para> | |
229 | To allow for independent shader invocations to communicate by reads and | |
230 | writes to a common memory address, image variables in the OpenGL Shading | |
231 | Language may be declared as "coherent". Buffer object or texture image | |
232 | memory accessed through such variables may be cached only if caches are | |
233 | automatically updated due to stores issued by any other shader invocation. | |
234 | If the same address is accessed using both coherent and non-coherent | |
235 | variables, the accesses using variables declared as coherent will observe | |
236 | the results stored using coherent variables in other invocations. Using | |
237 | variables declared as "coherent" guarantees only that the results of | |
238 | stores will be immediately visible to shader invocations using | |
239 | similarly-declared variables; calling <function>glMemoryBarrier</function> is required to ensure | |
240 | that the stores are visible to other operations. | |
241 | </para> | |
242 | <para> | |
243 | The following guidelines may be helpful in choosing when to use coherent | |
244 | memory accesses and when to use barriers. | |
245 | </para> | |
246 | <para> | |
247 | <itemizedlist> | |
248 | <listitem><para>Data that are read-only or constant may be accessed without using | |
249 | coherent variables or calling MemoryBarrier(). Updates to the | |
250 | read-only data via API calls such as BufferSubData will invalidate | |
251 | shader caches implicitly as required.</para></listitem> | |
252 | ||
253 | <listitem><para>Data that are shared between shader invocations at a fine granularity | |
254 | (e.g., written by one invocation, consumed by another invocation) should | |
255 | use coherent variables to read and write the shared data.</para></listitem> | |
256 | ||
257 | <listitem><para>Data written by one shader invocation and consumed by other shader | |
258 | invocations launched as a result of its execution ("dependent | |
259 | invocations") should use coherent variables in the producing shader | |
260 | invocation and call memoryBarrier() after the last write. The consuming | |
261 | shader invocation should also use coherent variables.</para></listitem> | |
262 | ||
263 | <listitem><para>Data written to image variables in one rendering pass and read by the | |
264 | shader in a later pass need not use coherent variables or | |
265 | memoryBarrier(). Calling MemoryBarrier() with the | |
266 | SHADER_IMAGE_ACCESS_BARRIER_BIT set in <parameter>barriers</parameter> between passes is | |
267 | necessary.</para></listitem> | |
268 | ||
269 | <listitem><para>Data written by the shader in one rendering pass and read by another | |
270 | mechanism (e.g., vertex or index buffer pulling) in a later pass need | |
271 | not use coherent variables or memoryBarrier(). Calling | |
272 | <function>glMemoryBarrier</function> with the appropriate bits set in <parameter>barriers</parameter> between | |
273 | passes is necessary.</para></listitem> | |
274 | </itemizedlist> | |
275 | </para> | |
276 | </refsect1> | |
277 | <refsect1 id="notes"><title>Notes</title> | |
278 | <para> | |
279 | <function>glMemoryBarrier</function> is available only if the GL version is 4.2 or higher. | |
280 | </para> | |
281 | <para> | |
282 | <constant>GL_SHADER_STORAGE_BARRIER_BIT</constant> is available only if the GL version is 4.3 or higher. | |
283 | </para> | |
284 | </refsect1> | |
285 | <refsect1 id="errors"><title>Errors</title> | |
286 | <para> | |
287 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>barriers</parameter> contains any bits | |
288 | other than those listed above, or is not the special value <constant>GL_ALL_BARRIER_BITS</constant>. | |
289 | </para> | |
290 | </refsect1> | |
291 | <refsect1 id="seealso"><title>See Also</title> | |
292 | <para> | |
293 | <citerefentry><refentrytitle>glBindImageTexture</refentrytitle></citerefentry>, | |
294 | <citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>, | |
295 | <citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>, | |
296 | <citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry>, | |
297 | <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry> | |
298 | </para> | |
299 | </refsect1> | |
300 | <refsect1 id="Copyright"><title>Copyright</title> | |
301 | <para> | |
302 | Copyright <trademark class="copyright"></trademark> 2011 Khronos Group. | |
303 | This material may be distributed subject to the terms and conditions set forth in | |
304 | the Open Publication License, v 1.0, 8 June 1999. | |
305 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. | |
306 | </para> | |
307 | </refsect1> | |
308 | </refentry> |