upstream-doc/man4/xhtml/glMemoryBarrier.xml

   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>