Opentk/Source/Bind/Specifications/Docs/glMemoryBarrier.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>