upstream-man-pages/man4/glMemoryBarrier.xml

   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>