blob: 25c377c56dd57523e2e23734ed256fa643d86199 [file] [log] [blame]
Name
AMD_shader_atomic_counter_ops
Name Strings
GL_AMD_shader_atomic_counter_ops
Contact
Daniel Rakos (daniel.rakos 'at' amd.com)
Contributors
Daniel Rakos, AMD
Graham Sellers, AMD
Status
Shipping
Version
Last Modified Date: 02/01/2013
Author Revision: 2
Number
OpenGL Extension #435
Dependencies
OpenGL 4.2 or ARB_shader_atomic_counters is required.
This extension is written against the OpenGL 4.3 (core) specification
and the GLSL 4.30.7 specification.
Overview
The ARB_shader_atomic_counters extension introduced atomic counters, but
it limits list of potential operations that can be performed on them to
increment, decrement, and query. This extension extends the list of GLSL
built-in functions that can operate on atomic counters. The list of new
operations include:
* Increment and decrement with wrap
* Addition and subtraction
* Minimum and maximum
* Bitwise operators (AND, OR, XOR, etc.)
* Masked OR operator
* Exchange, and compare and exchange operators
New Procedures and Functions
None.
New Tokens
None.
Additions to Chapter 8 of the GLSL 4.30.7 Specification (Built-in Functions)
Modify Section 8.10, Atomic-Counter Functions
Remove second paragraph ("The value returned by...")
Modify third paragraph ("The underlying...")
The underlying counter is a 32-bit unsigned integer. The result of
operations will wrap to [0, 2^32-1].
Additions to the table listing atomic counter built-in functions:
Syntax Description
------------------------------------ ------------------------------------------------------------------
uint atomicCounterIncWrap( Atomically
atomic_uint c, 1. increments the counter for c, then forces it to zero if and
uint wrap only if the incremented value is greater than or equal to
) <wrap>, and
2. returns its value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterDecWrap( Atomically
atomic_uint c, 1. decrements the counter for c, then forces it to <wrap>-1 if
uint wrap and only if the original value of the counter was either
) zero or greater than <wrap>, and
2. returns its value resulting from the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterAdd( Atomically
atomic_uint c, 1. adds the value of <data> to the counter for c, and
uint data 2. returns its value prior to the operation.
) These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterSubtract( Atomically
atomic_uint c, 1. subtracts the value of <data> from the counter for c, and
uint data 2. returns the value resulting from the operation.
) These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterReverseSubtract( Atomically
atomic_uint c, 1. subtracts the value of the counter for c from the value of
uint data <data> and sets the counter for c to the result of the
) operation, and
2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterMin( Atomically
atomic_uint c, 1. sets the counter for c to the minimum of the value of the
uint data counter and the value of <data>, and
) 2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterMax( Atomically
atomic_uint c, 1. sets the counter for c to the maximum of the value of the
uint data counter and the value of <data>, and
) 2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterAnd( Atomically
atomic_uint c, 1. sets the counter for c to the result of the bitwise AND of
uint data the value of the counter and the value of <data>, and
) 2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterOr( Atomically
atomic_uint c, 1. sets the counter for c to the result of the bitwise OR of
uint data the value of the counter and the value of <data>, and
) 2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterXor( Atomically
atomic_uint c, 1. sets the counter for c to the result of the bitwise XOR of
uint data the value of the counter and the value of <data>, and
) 2. returns the value prior to the operation.
These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterMaskOr( Atomically
atomic_uint c, 1. sets the counter for c to the result of the operation:
uint mask, (counter ^ ~mask) | data
uint data 2. returns the value prior to the operation.
) These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterExchange( Atomically
atomic_uint c, 1. sets the counter value for c to the value of <data>, and
uint data 2. returns its value prior to the operation.
) These two steps are done atomically with respect to the atomic
counter functions in this table.
uint atomicCounterCompSwap( Atomically
atomic_uint c, 1. compares the value of <compare> and the counter value for c,
uint compare, 2. if the values are equal, sets the counter value for c to
uint data the value of <data>, and
) 3. returns its value prior to the operation.
These three steps are done atomically with respect to the atomic
counter functions in this table.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
None.
Errors
None.
New State
None.
New Implementation Dependent State
None.
Usage Examples
Example 1: Appending/consuming data to/from a ring buffer using a compute shader
// Here we use increment/decrement with wrap to account for the wrapping at the
// end of the ring buffer.
// Using regular increment/decrement and performing a modulo manually is not
// satisfactory for non-power-of-two sized buffers as when the 32-bit counter
// wraps around we get incorrect results.
// Append shader
layout(binding=0, offset=0) uniform atomic_uint ringCounter;
layout(binding=0, r32ui) uniform imageBuffer ringBuffer;
void main()
{
uint myBufferData = ...;
imageStore(ringBuffer,
atomicCounterIncWrap(ringCounter, imageSize(ringBuffer)),
myBufferData);
}
// Consume shader
layout(binding=0, offset=0) uniform atomic_uint ringCounter;
layout(binding=0, r32ui) uniform imageBuffer ringBuffer;
void main()
{
uint myBufferData =
imageLoad(ringBuffer,
atomicCounterDecWrap(ringCounter, imageSize(ringBuffer))).x;
}
Example 2: Appending variable length records to a buffer using a compute shader
// Here we use atomicCounterAdd to ensure that we "allocate" a contiguous list of
// elements in the buffer.
// Using atomicCounterIncrement cannot mimic this behavior as there is no guarantee
// that subsequent calls to atomicCounterIncrement return subsequent counter values.
layout(binding=0, offset=0) uniform atomic_uint vlrCounter;
layout(binding=0, r32ui) uniform imageBuffer vlrBuffer;
void main()
{
uint data[...] = ...;
uint recordLength = ...;
uint recordStart = atomicCounterAdd(vlrCounter, recordLength);
for (uint i = 0; i < recordLength; ++i)
{
imageStore(vlrBuffer, recordStart + i, data[i]);
}
}
Issues
1) Should the new decrement with wrap and subtract operators match the
behavior of the existing decrement operator and return the post-operation
value of the counter?
RESOLVED: Yes, for consistency with the existing functionality.
2) Most of the new operations introduced by this extension are already
supported on load/store images and shader storage buffers. What benefit
the application developer could get from using this extension?
DISCUSSION: Atomic counter operations can have different performance
characteristics than load/store images or shader storage buffers. It is
expected that implementations can do atomic counter operations faster.
Also, there is no increment/decrement with wrap, reverse subtract and
mask-or operation for these storages (though the EXT version of load/store
image extension does provide a increment/decrement with wrap operators).
RESOLVED: It enables existing operations for atomic counters and also
adds completely new operations that are not available for load/store
images and shader storage buffers.
3) What should be the result of the increment/decrement with wrap
operations if the original counter value is greater than the <wrap>
parameter?
RESOLVED: Increment with wrap will force the value of the counter to zero,
decrement with wrap will force the value of the counter to <wrap>-1.
Revision History
Rev. Date Author Changes
---- -------- -------- ---------------------------------------------
2 02/01/2013 drakos Added issue #2 and #3
Cleaned up naming convention
1 11/13/2012 drakos Initial revision