upstream-doc/manglsl/atomicCompSwap.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="atomicCompSwap">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>atomicCompSwap</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>atomicCompSwap</refname>
  17         <refpurpose>perform an atomic compare-exchange operation to a variable</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>Declaration</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>int <function>atomicCompSwap</function></funcdef>
  23                 <paramdef>inout int <parameter>mem</parameter></paramdef>
  24                 <paramdef>uint <parameter>compare</parameter></paramdef>
  25                 <paramdef>uint <parameter>data</parameter></paramdef>
  26             </funcprototype>
  27             <funcprototype>
  28                 <funcdef>uint <function>atomicCompSwap</function></funcdef>
  29                 <paramdef>inout uint <parameter>mem</parameter></paramdef>
  30                 <paramdef>uint <parameter>compare</parameter></paramdef>
  31                 <paramdef>uint <parameter>data</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <refsect1 id="parameters"><title>Parameters</title>
  36         <variablelist>
  37         <varlistentry>
  38             <term><parameter>mem</parameter></term>
  39             <listitem>
  40                 <para>
  41                     The variable to use as the target of the operation.
  42                 </para>
  43             </listitem>
  44         </varlistentry>
  45         <varlistentry>
  46             <term><parameter>data</parameter></term>
  47             <listitem>
  48                 <para>
  49                     The data to be compared and potentially exchanged with <parameter>mem</parameter>.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         </variablelist>
  54     </refsect1>
  55     <refsect1 id="description"><title>Description</title>
  56         <para>
  57             <function>atomicCompSwap</function> performs an atomic comparison of <parameter>compare</parameter> with the contents of
  58             <parameter>mem</parameter>. If the content of <parameter>mem</parameter> is equal to <parameter>compare</parameter>,
  59             then the content of <parameter>data</parameter> is written into <parameter>mem</parameter> and is returned from
  60             the function. Otherwise, the original contents of <parameter>mem</parameter>
  61             are returned. The contents of the memory being updated by the atomic operation are
  62             guaranteed not to be modified by any other assignment or atomic memory function in any shader
  63             invocation between the time the original value is read and the time the new value is written.
  64         </para>
  65         <para>
  66             Atomic memory functions are supported only for a limited set of variables.  A shader will fail to compile
  67             if the value passed to the mem argument of an atomic memory function does not correspond to a buffer or
  68             shared variable. It is acceptable to pass an element of an array or a single component of a vector to the
  69             mem argument of an atomic memory function, as long as the underlying array or vector is a buffer or
  70             shared variable.
  71         </para>
  72     </refsect1>
  73     <refsect1 id="versions"><title>Version Support</title>
  74         <informaltable frame="topbot">
  75             #VARTABLECOLS#
  76                 <thead>
  77                     #FUNCTABLEHEADER#
  78                     <row>
  79                         <entry>atomicCompSwap</entry>#newin43#
  80                     </row>
  81                 </thead>
  82             </tgroup>
  83         </informaltable>
  84     </refsect1>
  85     <refsect1 id="seealso"><title>See Also</title>
  86         <para>
  87             <citerefentry><refentrytitle>atomicAdd</refentrytitle></citerefentry>,
  88             <citerefentry><refentrytitle>atomicAnd</refentrytitle></citerefentry>,
  89             <citerefentry><refentrytitle>atomicOr</refentrytitle></citerefentry>,
  90             <citerefentry><refentrytitle>atomicXor</refentrytitle></citerefentry>,
  91             <citerefentry><refentrytitle>atomicMin</refentrytitle></citerefentry>,
  92             <citerefentry><refentrytitle>atomicMax</refentrytitle></citerefentry>,
  93             <citerefentry><refentrytitle>atomicExchange</refentrytitle></citerefentry>
  94         </para>
  95     </refsect1>
  96     <refsect1 id="Copyright"><title>Copyright</title>
  97         <para>
  98             Copyright <trademark class="copyright"></trademark> 2011-2012 Khronos Group.
  99             This material may be distributed subject to the terms and conditions set forth in
 100             the Open Publication License, v 1.0, 8 June 1999.
 101             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 102         </para>
 103     </refsect1>
 104 </refentry>