323 lines
18 KiB
XML
323 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
|
<refentry id="glMemoryBarrier">
|
|
<refentryinfo>
|
|
<copyright>
|
|
<year>2011-2013</year>
|
|
<holder>Khronos Group</holder>
|
|
</copyright>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>glMemoryBarrier</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glMemoryBarrier</refname>
|
|
<refpurpose>defines a barrier ordering memory transactions</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glMemoryBarrier</function></funcdef>
|
|
<paramdef>GLbitfield <parameter>barriers</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>barriers</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the barriers to insert. Must be a bitwise combination of <constant>GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</constant>,
|
|
<constant>GL_ELEMENT_ARRAY_BARRIER_BIT</constant>, <constant>GL_UNIFORM_BARRIER_BIT</constant>, <constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant>,
|
|
<constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant>, <constant>GL_COMMAND_BARRIER_BIT</constant>, <constant>GL_PIXEL_BUFFER_BARRIER_BIT</constant>,
|
|
<constant>GL_TEXTURE_UPDATE_BARRIER_BIT</constant>, <constant>GL_BUFFER_UPDATE_BARRIER_BIT</constant>,
|
|
<constant>GL_FRAMEBUFFER_BARRIER_BIT</constant>, <constant>GL_TRANSFORM_FEEDBACK_BARRIER_BIT</constant>, <constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant>,
|
|
or <constant>GL_SHADER_STORAGE_BARRIER_BIT</constant>.
|
|
If the special value <constant>GL_ALL_BARRIER_BITS</constant> is specified, all supported barriers will be inserted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
<function>glMemoryBarrier</function> defines a barrier ordering the memory transactions issued prior to the
|
|
command relative to those issued after the barrier. For the purposes of
|
|
this ordering, memory transactions performed by shaders are considered to
|
|
be issued by the rendering command that triggered the execution of the
|
|
shader. <parameter>barriers</parameter> is a bitfield indicating the set of operations that
|
|
are synchronized with shader stores; the bits used in <parameter>barriers</parameter> are as
|
|
follows:
|
|
</para>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
If set, vertex data sourced from
|
|
buffer objects after the barrier will reflect data written by shaders
|
|
prior to the barrier. The set of buffer objects affected by this bit
|
|
is derived from the buffer object bindings used for
|
|
generic vertex attributes derived from the <constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER</constant> bindings.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_ELEMENT_ARRAY_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
If set, vertex array indices sourced from
|
|
buffer objects after the barrier will reflect data written by shaders
|
|
prior to the barrier. The buffer objects affected by this bit are
|
|
derived from the <constant>GL_ELEMENT_ARRAY_BUFFER</constant> binding.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_UNIFORM_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Shader uniforms sourced from buffer objects after the barrier will reflect data
|
|
written by shaders prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Texture fetches from shaders, including
|
|
fetches from buffer object memory via buffer textures, after the
|
|
barrier will reflect data written by shaders prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Memory accesses using shader image
|
|
load, store, and atomic built-in functions issued after the barrier
|
|
will reflect data written by shaders prior to the barrier.
|
|
Additionally, image stores and atomics issued after the barrier will
|
|
not execute until all memory accesses (e.g., loads, stores, texture
|
|
fetches, vertex fetches) initiated prior to the barrier complete.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_COMMAND_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Command data sourced from buffer objects by
|
|
Draw*Indirect commands after the barrier will reflect data written by
|
|
shaders prior to the barrier. The buffer objects affected by this bit
|
|
are derived from the <constant>GL_DRAW_INDIRECT_BUFFER</constant> binding.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_PIXEL_BUFFER_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Reads and writes of buffer objects via the
|
|
<constant>GL_PIXEL_PACK_BUFFER</constant> and <constant>GL_PIXEL_UNPACK_BUFFER</constant>
|
|
bindings (via <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glTexSubImage</refentrytitle></citerefentry>, etc.) after the
|
|
barrier will reflect data written by shaders prior to the barrier.
|
|
Additionally, buffer object writes issued after the barrier will wait
|
|
on the completion of all shader writes initiated prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_TEXTURE_UPDATE_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Writes to a texture via <function>glTex(Sub)Image*</function>,
|
|
<function>glCopyTex(Sub)Image*</function>, <function>glCompressedTex(Sub)Image*</function>, and reads via
|
|
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry> after the barrier will reflect data written by shaders
|
|
prior to the barrier. Additionally, texture writes from these
|
|
commands issued after the barrier will not execute until all shader
|
|
writes initiated prior to the barrier complete.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_BUFFER_UPDATE_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Reads or writes via <citerefentry><refentrytitle>glBufferSubData</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glCopyBufferSubData</refentrytitle></citerefentry>,
|
|
or <citerefentry><refentrytitle>glGetBufferSubData</refentrytitle></citerefentry>, or
|
|
to buffer object memory mapped by <citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>
|
|
or <citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry> after the barrier
|
|
will reflect data written by shaders prior to the barrier.
|
|
Additionally, writes via these commands issued after the barrier will
|
|
wait on the completion of any shader writes to the same memory
|
|
initiated prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_FRAMEBUFFER_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Reads and writes via framebuffer object
|
|
attachments after the barrier will reflect data written by shaders
|
|
prior to the barrier. Additionally, framebuffer writes issued after
|
|
the barrier will wait on the completion of all shader writes issued
|
|
prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_TRANSFORM_FEEDBACK_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Writes via transform feedback
|
|
bindings after the barrier will reflect data written by shaders prior
|
|
to the barrier. Additionally, transform feedback writes issued after
|
|
the barrier will wait on the completion of all shader writes issued
|
|
prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Accesses to atomic counters after the
|
|
barrier will reflect writes prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_SHADER_STORAGE_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Accesses to shader storage blocks after the
|
|
barrier will reflect writes prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_QUERY_BUFFER_BARRIER_BIT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Writes of buffer objects via the <constant>GL_QUERY_BUFFER</constant>
|
|
binding after the barrier will reflect data written
|
|
by shaders prior to the barrier. Additionally, buffer object writes
|
|
issued after the barrier will wait on the completion of all shader
|
|
writes initiated prior to the barrier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If <parameter>barriers</parameter> is <constant>GL_ALL_BARRIER_BITS</constant>, shader memory accesses
|
|
will be synchronized relative to all the operations described above.
|
|
</para>
|
|
<para>
|
|
Implementations may cache buffer object and texture image memory that
|
|
could be written by shaders in multiple caches; for example, there may be
|
|
separate caches for texture, vertex fetching, and one or more caches for
|
|
shader memory accesses. Implementations are not required to keep these
|
|
caches coherent with shader memory writes. Stores issued by one
|
|
invocation may not be immediately observable by other pipeline stages or
|
|
other shader invocations because the value stored may remain in a cache
|
|
local to the processor executing the store, or because data overwritten by
|
|
the store is still in a cache elsewhere in the system. When <function>glMemoryBarrier</function>
|
|
is called, the GL flushes and/or invalidates any caches relevant to the
|
|
operations specified by the <parameter>barriers</parameter> parameter to ensure consistent
|
|
ordering of operations across the barrier.
|
|
</para>
|
|
<para>
|
|
To allow for independent shader invocations to communicate by reads and
|
|
writes to a common memory address, image variables in the OpenGL Shading
|
|
Language may be declared as "coherent". Buffer object or texture image
|
|
memory accessed through such variables may be cached only if caches are
|
|
automatically updated due to stores issued by any other shader invocation.
|
|
If the same address is accessed using both coherent and non-coherent
|
|
variables, the accesses using variables declared as coherent will observe
|
|
the results stored using coherent variables in other invocations. Using
|
|
variables declared as "coherent" guarantees only that the results of
|
|
stores will be immediately visible to shader invocations using
|
|
similarly-declared variables; calling <function>glMemoryBarrier</function> is required to ensure
|
|
that the stores are visible to other operations.
|
|
</para>
|
|
<para>
|
|
The following guidelines may be helpful in choosing when to use coherent
|
|
memory accesses and when to use barriers.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem><para>Data that are read-only or constant may be accessed without using
|
|
coherent variables or calling MemoryBarrier(). Updates to the
|
|
read-only data via API calls such as BufferSubData will invalidate
|
|
shader caches implicitly as required.</para></listitem>
|
|
|
|
<listitem><para>Data that are shared between shader invocations at a fine granularity
|
|
(e.g., written by one invocation, consumed by another invocation) should
|
|
use coherent variables to read and write the shared data.</para></listitem>
|
|
|
|
<listitem><para>Data written by one shader invocation and consumed by other shader
|
|
invocations launched as a result of its execution ("dependent
|
|
invocations") should use coherent variables in the producing shader
|
|
invocation and call memoryBarrier() after the last write. The consuming
|
|
shader invocation should also use coherent variables.</para></listitem>
|
|
|
|
<listitem><para>Data written to image variables in one rendering pass and read by the
|
|
shader in a later pass need not use coherent variables or
|
|
memoryBarrier(). Calling MemoryBarrier() with the
|
|
SHADER_IMAGE_ACCESS_BARRIER_BIT set in <parameter>barriers</parameter> between passes is
|
|
necessary.</para></listitem>
|
|
|
|
<listitem><para>Data written by the shader in one rendering pass and read by another
|
|
mechanism (e.g., vertex or index buffer pulling) in a later pass need
|
|
not use coherent variables or memoryBarrier(). Calling
|
|
<function>glMemoryBarrier</function> with the appropriate bits set in <parameter>barriers</parameter> between
|
|
passes is necessary.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
<function>glMemoryBarrier</function> is available only if the GL version is 4.2 or higher.
|
|
</para>
|
|
<para>
|
|
<constant>GL_SHADER_STORAGE_BARRIER_BIT</constant> is available only if the GL version is 4.3 or higher.
|
|
</para>
|
|
<para>
|
|
<constant>GL_QUERY_BUFFER_BARRIER_BIT</constant> is available only if the GL version is 4.4 or higher.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>barriers</parameter> contains any unsupported
|
|
bits, or is not the special value <constant>GL_ALL_BARRIER_BITS</constant>.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glBindImageTexture</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright <trademark class="copyright"></trademark> 2011-2013 Khronos Group.
|
|
This material may be distributed subject to the terms and conditions set forth in
|
|
the Open Publication License, v 1.0, 8 June 1999.
|
|
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|