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>glMemoryBarrier - 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="glMemoryBarrier"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glMemoryBarrier — defines a barrier ordering memory transactions</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">glMemoryBarrier</b>(</code>GLbitfield <var class="pdparam">barriers</var><code>)</code>;</p></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>barriers</code></em></span></dt><dd><p> | |
5 | Specifies the barriers to insert. Must be a bitwise combination of <code class="constant">GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</code>, | |
6 | <code class="constant">GL_ELEMENT_ARRAY_BARRIER_BIT</code>, <code class="constant">GL_UNIFORM_BARRIER_BIT</code>, <code class="constant">GL_TEXTURE_FETCH_BARRIER_BIT</code>, | |
7 | <code class="constant">GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</code>, <code class="constant">GL_COMMAND_BARRIER_BIT</code>, <code class="constant">GL_PIXEL_BUFFER_BARRIER_BIT</code>, | |
8 | <code class="constant">GL_TEXTURE_UPDATE_BARRIER_BIT</code>, <code class="constant">GL_BUFFER_UPDATE_BARRIER_BIT</code>, | |
9 | <code class="constant">GL_FRAMEBUFFER_BARRIER_BIT</code>, <code class="constant">GL_TRANSFORM_FEEDBACK_BARRIER_BIT</code>, <code class="constant">GL_ATOMIC_COUNTER_BARRIER_BIT</code>, | |
10 | or <code class="constant">GL_SHADER_STORAGE_BARRIER_BIT</code>. | |
11 | If the special value <code class="constant">GL_ALL_BARRIER_BITS</code> is specified, all supported barriers will be inserted. | |
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">glMemoryBarrier</code> defines a barrier ordering the memory transactions issued prior to the | |
14 | command relative to those issued after the barrier. For the purposes of | |
15 | this ordering, memory transactions performed by shaders are considered to | |
16 | be issued by the rendering command that triggered the execution of the | |
17 | shader. <em class="parameter"><code>barriers</code></em> is a bitfield indicating the set of operations that | |
18 | are synchronized with shader stores; the bits used in <em class="parameter"><code>barriers</code></em> are as | |
19 | follows: | |
20 | </p><p> | |
21 | </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</code></span></dt><dd><p> | |
22 | If set, vertex data sourced from | |
23 | buffer objects after the barrier will reflect data written by shaders | |
24 | prior to the barrier. The set of buffer objects affected by this bit | |
25 | is derived from the buffer object bindings used for | |
26 | generic vertex attributes derived from the <code class="constant">GL_VERTEX_ATTRIB_ARRAY_BUFFER</code> bindings. | |
27 | </p></dd><dt><span class="term"><code class="constant">GL_ELEMENT_ARRAY_BARRIER_BIT</code></span></dt><dd><p> | |
28 | If set, vertex array indices sourced from | |
29 | buffer objects after the barrier will reflect data written by shaders | |
30 | prior to the barrier. The buffer objects affected by this bit are | |
31 | derived from the <code class="constant">GL_ELEMENT_ARRAY_BUFFER</code> binding. | |
32 | </p></dd><dt><span class="term"><code class="constant">GL_UNIFORM_BARRIER_BIT</code></span></dt><dd><p> | |
33 | Shader uniforms sourced from buffer objects after the barrier will reflect data | |
34 | written by shaders prior to the barrier. | |
35 | </p></dd><dt><span class="term"><code class="constant">GL_TEXTURE_FETCH_BARRIER_BIT</code></span></dt><dd><p> | |
36 | Texture fetches from shaders, including | |
37 | fetches from buffer object memory via buffer textures, after the | |
38 | barrier will reflect data written by shaders prior to the barrier. | |
39 | </p></dd><dt><span class="term"><code class="constant">GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</code></span></dt><dd><p> | |
40 | Memory accesses using shader image | |
41 | load, store, and atomic built-in functions issued after the barrier | |
42 | will reflect data written by shaders prior to the barrier. | |
43 | Additionally, image stores and atomics issued after the barrier will | |
44 | not execute until all memory accesses (e.g., loads, stores, texture | |
45 | fetches, vertex fetches) initiated prior to the barrier complete. | |
46 | </p></dd><dt><span class="term"><code class="constant">GL_COMMAND_BARRIER_BIT</code></span></dt><dd><p> | |
47 | Command data sourced from buffer objects by | |
48 | Draw*Indirect commands after the barrier will reflect data written by | |
49 | shaders prior to the barrier. The buffer objects affected by this bit | |
50 | are derived from the <code class="constant">GL_DRAW_INDIRECT_BUFFER</code> binding. | |
51 | </p></dd><dt><span class="term"><code class="constant">GL_PIXEL_BUFFER_BARRIER_BIT</code></span></dt><dd><p> | |
52 | Reads and writes of buffer objects via the | |
53 | <code class="constant">GL_PIXEL_PACK_BUFFER</code> and <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> | |
54 | bindings (via <a href="glReadPixels.xml"><span class="citerefentry"><span class="refentrytitle">glReadPixels</span></span></a>, | |
55 | <a href="glTexSubImage.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage</span></span></a>, etc.) after the | |
56 | barrier will reflect data written by shaders prior to the barrier. | |
57 | Additionally, buffer object writes issued after the barrier will wait | |
58 | on the completion of all shader writes initiated prior to the barrier. | |
59 | </p></dd><dt><span class="term"><code class="constant">GL_TEXTURE_UPDATE_BARRIER_BIT</code></span></dt><dd><p> | |
60 | Writes to a texture via <code class="function">glTex(Sub)Image*</code>, | |
61 | <code class="function">glCopyTex(Sub)Image*</code>, <code class="function">glCompressedTex(Sub)Image*</code>, and reads via | |
62 | <a href="glGetTexImage.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a> after the barrier will reflect data written by shaders | |
63 | prior to the barrier. Additionally, texture writes from these | |
64 | commands issued after the barrier will not execute until all shader | |
65 | writes initiated prior to the barrier complete. | |
66 | </p></dd><dt><span class="term"><code class="constant">GL_BUFFER_UPDATE_BARRIER_BIT</code></span></dt><dd><p> | |
67 | Reads or writes via <a href="glBufferSubData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferSubData</span></span></a>, | |
68 | <a href="glCopyBufferSubData.xml"><span class="citerefentry"><span class="refentrytitle">glCopyBufferSubData</span></span></a>, | |
69 | or <a href="glGetBufferSubData.xml"><span class="citerefentry"><span class="refentrytitle">glGetBufferSubData</span></span></a>, or | |
70 | to buffer object memory mapped by <a href="glMapBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glMapBuffer</span></span></a> | |
71 | or <a href="glMapBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glMapBufferRange</span></span></a> after the barrier | |
72 | will reflect data written by shaders prior to the barrier. | |
73 | Additionally, writes via these commands issued after the barrier will | |
74 | wait on the completion of any shader writes to the same memory | |
75 | initiated prior to the barrier. | |
76 | </p></dd><dt><span class="term"><code class="constant">GL_FRAMEBUFFER_BARRIER_BIT</code></span></dt><dd><p> | |
77 | Reads and writes via framebuffer object | |
78 | attachments after the barrier will reflect data written by shaders | |
79 | prior to the barrier. Additionally, framebuffer writes issued after | |
80 | the barrier will wait on the completion of all shader writes issued | |
81 | prior to the barrier. | |
82 | </p></dd><dt><span class="term"><code class="constant">GL_TRANSFORM_FEEDBACK_BARRIER_BIT</code></span></dt><dd><p> | |
83 | Writes via transform feedback | |
84 | bindings after the barrier will reflect data written by shaders prior | |
85 | to the barrier. Additionally, transform feedback writes issued after | |
86 | the barrier will wait on the completion of all shader writes issued | |
87 | prior to the barrier. | |
88 | </p></dd><dt><span class="term"><code class="constant">GL_ATOMIC_COUNTER_BARRIER_BIT</code></span></dt><dd><p> | |
89 | Accesses to atomic counters after the | |
90 | barrier will reflect writes prior to the barrier. | |
91 | </p></dd><dt><span class="term"><code class="constant">GL_SHADER_STORAGE_BARRIER_BIT</code></span></dt><dd><p> | |
92 | Accesses to shader storage blocks after the | |
93 | barrier will reflect writes prior to the barrier. | |
94 | </p></dd></dl></div><p> | |
95 | </p><p> | |
96 | If <em class="parameter"><code>barriers</code></em> is <code class="constant">GL_ALL_BARRIER_BITS</code>, shader memory accesses | |
97 | will be synchronized relative to all the operations described above. | |
98 | </p><p> | |
99 | Implementations may cache buffer object and texture image memory that | |
100 | could be written by shaders in multiple caches; for example, there may be | |
101 | separate caches for texture, vertex fetching, and one or more caches for | |
102 | shader memory accesses. Implementations are not required to keep these | |
103 | caches coherent with shader memory writes. Stores issued by one | |
104 | invocation may not be immediately observable by other pipeline stages or | |
105 | other shader invocations because the value stored may remain in a cache | |
106 | local to the processor executing the store, or because data overwritten by | |
107 | the store is still in a cache elsewhere in the system. When <code class="function">glMemoryBarrier</code> | |
108 | is called, the GL flushes and/or invalidates any caches relevant to the | |
109 | operations specified by the <em class="parameter"><code>barriers</code></em> parameter to ensure consistent | |
110 | ordering of operations across the barrier. | |
111 | </p><p> | |
112 | To allow for independent shader invocations to communicate by reads and | |
113 | writes to a common memory address, image variables in the OpenGL Shading | |
114 | Language may be declared as "coherent". Buffer object or texture image | |
115 | memory accessed through such variables may be cached only if caches are | |
116 | automatically updated due to stores issued by any other shader invocation. | |
117 | If the same address is accessed using both coherent and non-coherent | |
118 | variables, the accesses using variables declared as coherent will observe | |
119 | the results stored using coherent variables in other invocations. Using | |
120 | variables declared as "coherent" guarantees only that the results of | |
121 | stores will be immediately visible to shader invocations using | |
122 | similarly-declared variables; calling <code class="function">glMemoryBarrier</code> is required to ensure | |
123 | that the stores are visible to other operations. | |
124 | </p><p> | |
125 | The following guidelines may be helpful in choosing when to use coherent | |
126 | memory accesses and when to use barriers. | |
127 | </p><p> | |
128 | </p><div class="itemizedlist"><ul type="disc"><li><p>Data that are read-only or constant may be accessed without using | |
129 | coherent variables or calling MemoryBarrier(). Updates to the | |
130 | read-only data via API calls such as BufferSubData will invalidate | |
131 | shader caches implicitly as required.</p></li><li><p>Data that are shared between shader invocations at a fine granularity | |
132 | (e.g., written by one invocation, consumed by another invocation) should | |
133 | use coherent variables to read and write the shared data.</p></li><li><p>Data written by one shader invocation and consumed by other shader | |
134 | invocations launched as a result of its execution ("dependent | |
135 | invocations") should use coherent variables in the producing shader | |
136 | invocation and call memoryBarrier() after the last write. The consuming | |
137 | shader invocation should also use coherent variables.</p></li><li><p>Data written to image variables in one rendering pass and read by the | |
138 | shader in a later pass need not use coherent variables or | |
139 | memoryBarrier(). Calling MemoryBarrier() with the | |
140 | SHADER_IMAGE_ACCESS_BARRIER_BIT set in <em class="parameter"><code>barriers</code></em> between passes is | |
141 | necessary.</p></li><li><p>Data written by the shader in one rendering pass and read by another | |
142 | mechanism (e.g., vertex or index buffer pulling) in a later pass need | |
143 | not use coherent variables or memoryBarrier(). Calling | |
144 | <code class="function">glMemoryBarrier</code> with the appropriate bits set in <em class="parameter"><code>barriers</code></em> between | |
145 | passes is necessary.</p></li></ul></div><p> | |
146 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p> | |
147 | <code class="function">glMemoryBarrier</code> is available only if the GL version is 4.2 or higher. | |
148 | </p><p> | |
149 | <code class="constant">GL_SHADER_STORAGE_BARRIER_BIT</code> is available only if the GL version is 4.3 or higher. | |
150 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p> | |
151 | <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>barriers</code></em> contains any bits | |
152 | other than those listed above, or is not the special value <code class="constant">GL_ALL_BARRIER_BITS</code>. | |
153 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p> | |
154 | <a href="glBindImageTexture.xml"><span class="citerefentry"><span class="refentrytitle">glBindImageTexture</span></span></a>, | |
155 | <a href="glBufferData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferData</span></span></a>, | |
156 | <a href="glMapBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glMapBuffer</span></span></a>, | |
157 | <a href="glMapBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glMapBufferRange</span></span></a>, | |
158 | <a href="glFlushMappedBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glFlushMappedBufferRange</span></span></a> | |
159 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
160 | Copyright <span class="trademark"></span>© 2011 Khronos Group. | |
161 | This material may be distributed subject to the terms and conditions set forth in | |
162 | the Open Publication License, v 1.0, 8 June 1999. | |
163 | <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>. | |
164 | </p></div></div></body></html> |