File: glMemoryBarrier.xml

package info (click to toggle)
khronos-opengl-man4 1.0~svn27841-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 24,888 kB
  • ctags: 377
  • sloc: xml: 188,408; makefile: 1,153; python: 736; sh: 49; php: 7; sed: 2
file content (466 lines) | stat: -rw-r--r-- 25,169 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>

<!-- Converted by db4-upgrade version 1.1 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glMemoryBarrier">
    <info>
        <copyright>
            <year>2011-2014</year>
            <holder>Khronos Group</holder>
        </copyright>
    </info>
    <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>
            <funcprototype>
                <funcdef>void <function>glMemoryBarrierByRegion</function></funcdef>
                <paramdef>GLbitfield <parameter>barriers</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 xml:id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>barriers</parameter></term>
            <listitem>
                <para>
                    Specifies the barriers to insert. 
                </para>
                <para>
                    For <function>glMemoryBarrier</function>, must be a
                    bitwise combination of any 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>.
                </para>
                <para>
                    For <function>glMemoryBarrier</function>, must be a
                    bitwise combination of any of
                    <constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant>, or
                    <constant>GL_FRAMEBUFFER_BARRIER_BIT</constant>,
                    <constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant>,
                    <constant>GL_SHADER_STORAGE_BARRIER_BIT</constant>.
                    <constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant>, or
                    <constant>GL_UNIFORM_BARRIER_BIT</constant>.
                </para>
                <para>
                    If the special value
                    <constant>GL_ALL_BARRIER_BITS</constant> is specified,
                    all supported barriers for the corresponding command
                    will be inserted.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="description"><title>Description for <function>glMemoryBarrier</function></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
                        <function>MemoryBarrier</function>(). Updates to the
                        read-only data via API calls such as
                        <function>glBufferSubData</function> 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 (&quot;dependent invocations&quot;)
                        should use coherent variables in the producing
                        shader invocation and call
                        <function>memoryBarrier</function>() 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
                        <function>glMemoryBarrier</function> 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
                        <function>memoryBarrier</function>(). Calling
                        <function>glMemoryBarrier</function> with the
                        appropriate bits set in
                        <parameter>barriers</parameter> between passes is
                        necessary.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </refsect1>
    <refsect1 xml:id="description2"><title>Description for <function>glMemoryBarrierByRegion</function></title>
        <para>
            <function>glMemoryBarrierByRegion</function> behaves as
            described above for <function>glMemoryBarrier</function>, with
            two differences:
        </para>
        <para>
            First, it narrows the region under consideration so that only
            reads and writes of prior fragment shaders that are invoked for
            a smaller region of the framebuffer will be completed/reflected
            prior to subsequent reads and writes of following fragment
            shaders. The size of the region is implementation-dependent and
            may be as small as one framebuffer pixel.
        </para>
        <para>
            Second, it only applies to memory transactions that may be read
            by or written by a fragment shader. Therefore, only the barrier
            bits
                <itemizedlist>
                    <listitem>
                        <para><constant>GL_ATOMIC_COUNTER_BARRIER_BIT</constant></para>
                    </listitem>
                    <listitem>
                        <para><constant>GL_FRAMEBUFFER_BARRIER_BIT</constant></para>
                    </listitem>
                    <listitem>
                        <para><constant>GL_SHADER_IMAGE_ACCESS_BARRIER_BIT</constant></para>
                    </listitem>
                    <listitem>
                        <para><constant>GL_SHADER_STORAGE_BARRIER_BIT</constant></para>
                    </listitem>
                    <listitem>
                        <para><constant>GL_TEXTURE_FETCH_BARRIER_BIT</constant></para>
                    </listitem>
                    <listitem>
                        <para><constant>GL_UNIFORM_BARRIER_BIT</constant></para>
                    </listitem>
                </itemizedlist>
            are supported.
        </para>
        <para>
            When <parameter>barriers</parameter> is
            <constant>GL_ALL_BARRIER_BITS</constant>, shader memory accesses
            will be synchronized relative to all these barrier bits, but not
            to other barrier bits specific to
            <function>glMemoryBarrier</function>. This implies that reads
            and writes for scatter/gather-like algorithms may or may not be
            completed/reflected after a
            <function>glMemoryBarrierByRegion</function> command. However,
            for uses such as deferred shading, where a linked list of 
            visible surfaces with the head at a framebuffer address may be
            constructed, and the entirety of the list is only dependent on
            previous executions at that framebuffer address,
            <function>glMemoryBarrierByRegion</function> may be
            significantly more efficient than
            <function>glMemoryBarrier</function>.
        </para>
    </refsect1>
    <refsect1 xml:id="notes"><title>Notes</title>
        <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 xml:id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if
            <parameter>barriers</parameter> is not the special value
            <constant>GL_ALL_BARRIER_BITS</constant>, and has any bits set
            other than those described above for
            <function>glMemoryBarrier</function> or
            <function>glMemoryBarrierByRegion</function> respectively.
        </para>
    </refsect1>
    <refsect1 xml:id="versions"><title>Version Support</title>
        <informaltable>
            <tgroup cols="13" align="left">
                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
                <tbody>
                    <row>
                        <entry><function>glMemoryBarrier</function></entry>
                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='42']/*)"/>
                    </row>
                    <row>
                        <entry><function>glMemoryBarrierByRegion</function></entry>
                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='45']/*)"/>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect1>
    <refsect1 xml: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>,
            <citerefentry><refentrytitle>memoryBarrier</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 xml:id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"/> 2011-2014 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.
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
        </para>
    </refsect1>
</refentry>