upstream-doc/manglsl/imageAtomicCompSwap.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="imageAtomicCompSwap">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2011</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>imageAtomicCompSwap</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>imageAtomicCompSwap</refname>
  17         <refpurpose>atomically compares supplied data with that in memory and conditionally stores it to memory</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>Declaration</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  23                 <paramdef>gimage1D <parameter>image</parameter></paramdef>
  24                 <paramdef>int <parameter>P</parameter></paramdef>
  25                 <paramdef>uint <parameter>compare</parameter></paramdef>
  26                 <paramdef>uint <parameter>data</parameter></paramdef>
  27             </funcprototype>
  28             <funcprototype>
  29                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  30                 <paramdef>gimage2D <parameter>image</parameter></paramdef>
  31                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
  32                 <paramdef>uint <parameter>compare</parameter></paramdef>
  33                 <paramdef>uint <parameter>data</parameter></paramdef>
  34             </funcprototype>
  35             <funcprototype>
  36                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  37                 <paramdef>gimage3D <parameter>image</parameter></paramdef>
  38                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
  39                 <paramdef>uint <parameter>compare</parameter></paramdef>
  40                 <paramdef>uint <parameter>data</parameter></paramdef>
  41             </funcprototype>
  42             <funcprototype>
  43                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  44                 <paramdef>gimage2DRect <parameter>image</parameter></paramdef>
  45                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
  46                 <paramdef>uint <parameter>compare</parameter></paramdef>
  47                 <paramdef>uint <parameter>data</parameter></paramdef>
  48             </funcprototype>
  49             <funcprototype>
  50                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  51                 <paramdef>gimageCube <parameter>image</parameter></paramdef>
  52                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
  53                 <paramdef>uint <parameter>compare</parameter></paramdef>
  54                 <paramdef>uint <parameter>data</parameter></paramdef>
  55             </funcprototype>
  56             <funcprototype>
  57                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  58                 <paramdef>gbufferImage <parameter>image</parameter></paramdef>
  59                 <paramdef>int <parameter>P</parameter></paramdef>
  60                 <paramdef>uint <parameter>compare</parameter></paramdef>
  61                 <paramdef>uint <parameter>data</parameter></paramdef>
  62             </funcprototype>
  63             <funcprototype>
  64                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  65                 <paramdef>gimage1DArray <parameter>image</parameter></paramdef>
  66                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
  67                 <paramdef>uint <parameter>compare</parameter></paramdef>
  68                 <paramdef>uint <parameter>data</parameter></paramdef>
  69             </funcprototype>
  70             <funcprototype>
  71                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  72                 <paramdef>gimage2DArray <parameter>image</parameter></paramdef>
  73                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
  74                 <paramdef>uint <parameter>compare</parameter></paramdef>
  75                 <paramdef>uint <parameter>data</parameter></paramdef>
  76             </funcprototype>
  77             <funcprototype>
  78                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  79                 <paramdef>gimageCubeArray <parameter>image</parameter></paramdef>
  80                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
  81                 <paramdef>uint <parameter>compare</parameter></paramdef>
  82                 <paramdef>uint <parameter>data</parameter></paramdef>
  83             </funcprototype>
  84             <funcprototype>
  85                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  86                 <paramdef>gimage2DMS <parameter>image</parameter></paramdef>
  87                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
  88                 <paramdef>int <parameter>sample</parameter></paramdef>
  89                 <paramdef>uint <parameter>compare</parameter></paramdef>
  90                 <paramdef>uint <parameter>data</parameter></paramdef>
  91             </funcprototype>
  92             <funcprototype>
  93                 <funcdef>uint <function>imageAtomicCompSwap</function></funcdef>
  94                 <paramdef>gimage2DMSArray <parameter>image</parameter></paramdef>
  95                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
  96                 <paramdef>int <parameter>sample</parameter></paramdef>
  97                 <paramdef>uint <parameter>compare</parameter></paramdef>
  98                 <paramdef>uint <parameter>data</parameter></paramdef>
  99             </funcprototype>
 100             <funcprototype>
 101                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 102                 <paramdef>gimage1D <parameter>image</parameter></paramdef>
 103                 <paramdef>int <parameter>P</parameter></paramdef>
 104                 <paramdef>int <parameter>compare</parameter></paramdef>
 105                 <paramdef>int <parameter>data</parameter></paramdef>
 106             </funcprototype>
 107             <funcprototype>
 108                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 109                 <paramdef>gimage2D <parameter>image</parameter></paramdef>
 110                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
 111                 <paramdef>int <parameter>compare</parameter></paramdef>
 112                 <paramdef>int <parameter>data</parameter></paramdef>
 113             </funcprototype>
 114             <funcprototype>
 115                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 116                 <paramdef>gimage3D <parameter>image</parameter></paramdef>
 117                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
 118                 <paramdef>int <parameter>compare</parameter></paramdef>
 119                 <paramdef>int <parameter>data</parameter></paramdef>
 120             </funcprototype>
 121             <funcprototype>
 122                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 123                 <paramdef>gimage2DRect <parameter>image</parameter></paramdef>
 124                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
 125                 <paramdef>int <parameter>compare</parameter></paramdef>
 126                 <paramdef>int <parameter>data</parameter></paramdef>
 127             </funcprototype>
 128             <funcprototype>
 129                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 130                 <paramdef>gimageCube <parameter>image</parameter></paramdef>
 131                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
 132                 <paramdef>int <parameter>compare</parameter></paramdef>
 133                 <paramdef>int <parameter>data</parameter></paramdef>
 134             </funcprototype>
 135             <funcprototype>
 136                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 137                 <paramdef>gbufferImage <parameter>image</parameter></paramdef>
 138                 <paramdef>int <parameter>P</parameter></paramdef>
 139                 <paramdef>int <parameter>compare</parameter></paramdef>
 140                 <paramdef>int <parameter>data</parameter></paramdef>
 141             </funcprototype>
 142             <funcprototype>
 143                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 144                 <paramdef>gimage1DArray <parameter>image</parameter></paramdef>
 145                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
 146                 <paramdef>int <parameter>compare</parameter></paramdef>
 147                 <paramdef>int <parameter>data</parameter></paramdef>
 148             </funcprototype>
 149             <funcprototype>
 150                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 151                 <paramdef>gimage2DArray <parameter>image</parameter></paramdef>
 152                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
 153                 <paramdef>int <parameter>compare</parameter></paramdef>
 154                 <paramdef>int <parameter>data</parameter></paramdef>
 155             </funcprototype>
 156             <funcprototype>
 157                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 158                 <paramdef>gimageCubeArray <parameter>image</parameter></paramdef>
 159                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
 160                 <paramdef>int <parameter>compare</parameter></paramdef>
 161                 <paramdef>int <parameter>data</parameter></paramdef>
 162             </funcprototype>
 163             <funcprototype>
 164                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 165                 <paramdef>gimage2DMS <parameter>image</parameter></paramdef>
 166                 <paramdef>ivec2 <parameter>P</parameter></paramdef>
 167                 <paramdef>int <parameter>sample</parameter></paramdef>
 168                 <paramdef>int <parameter>compare</parameter></paramdef>
 169                 <paramdef>int <parameter>data</parameter></paramdef>
 170             </funcprototype>
 171             <funcprototype>
 172                 <funcdef>int <function>imageAtomicCompSwap</function></funcdef>
 173                 <paramdef>gimage2DMSArray <parameter>image</parameter></paramdef>
 174                 <paramdef>ivec3 <parameter>P</parameter></paramdef>
 175                 <paramdef>int <parameter>sample</parameter></paramdef>
 176                 <paramdef>int <parameter>compare</parameter></paramdef>
 177                 <paramdef>int <parameter>data</parameter></paramdef>
 178             </funcprototype>
 179         </funcsynopsis>
 180     </refsynopsisdiv>
 181     <refsect1 id="parameters"><title>Parameters</title>
 182         <variablelist>
 183         <varlistentry>
 184             <term><parameter>image</parameter></term>
 185             <listitem>
 186                 <para>
 187                     Specify the image unit into which to compare and conditionally store <parameter>data</parameter>.
 188                 </para>
 189             </listitem>
 190         </varlistentry>
 191         <varlistentry>
 192             <term><parameter>P</parameter></term>
 193             <listitem>
 194                 <para>
 195                     Specify the coordinate at which to compare and conditionally store the data.
 196                 </para>
 197             </listitem>
 198         </varlistentry>
 199         <varlistentry>
 200             <term><parameter>sample</parameter></term>
 201             <listitem>
 202                 <para>
 203                     When present, specifies the sample within the image to compare and conditionally store into.
 204                 </para>
 205             </listitem>
 206         </varlistentry>
 207         <varlistentry>
 208             <term><parameter>compare</parameter></term>
 209             <listitem>
 210                 <para>
 211                     Specifies the value to compare with the content of the image.
 212                 </para>
 213             </listitem>
 214         </varlistentry>
 215         <varlistentry>
 216             <term><parameter>data</parameter></term>
 217             <listitem>
 218                 <para>
 219                     Specifies the value to store in the image if <parameter>compare</parameter> is equal to the existing image content.
 220                 </para>
 221             </listitem>
 222         </varlistentry>
 223         </variablelist>
 224     </refsect1>
 225     <refsect1 id="description"><title>Description</title>
 226         <para>
 227             <function>imageAtomicCompSwap</function> atomically compares the value of <parameter>compare</parameter>
 228             with that of the texel at coordinate <parameter>P</parameter> and <parameter>sample</parameter> (for multisampled forms) in the
 229             image bound to uint <parameter>image</parameter>. If the values are equal, <parameter>data</parameter> is
 230             stored into the texel, otherwise it is discarded. It returns the original value of the texel regardless of
 231             the result of the comparison operation.
 232         </para>
 233     </refsect1>
 234     <refsect1 id="versions"><title>Version Support</title>
 235         <informaltable frame="topbot">
 236             #VARTABLECOLS#
 237                 <thead>
 238                     #FUNCTABLEHEADER#
 239                     <row>
 240                         <entry>imageAtomicCompSwap</entry>#newin42#
 241                     </row>
 242                 </thead>
 243             </tgroup>
 244         </informaltable>
 245     </refsect1>
 246     <refsect1 id="seealso"><title>See Also</title>
 247         <para>
 248             <citerefentry><refentrytitle>imageLoad</refentrytitle></citerefentry>,
 249             <citerefentry><refentrytitle>imageStore</refentrytitle></citerefentry>,
 250             <citerefentry><refentrytitle>imageAtomicAdd</refentrytitle></citerefentry>,
 251             <citerefentry><refentrytitle>imageAtomicMin</refentrytitle></citerefentry>,
 252             <citerefentry><refentrytitle>imageAtomicMax</refentrytitle></citerefentry>,
 253             <citerefentry><refentrytitle>imageAtomicXor</refentrytitle></citerefentry>,
 254             <citerefentry><refentrytitle>imageAtomicOr</refentrytitle></citerefentry>,
 255             <citerefentry><refentrytitle>imageAtomicAnd</refentrytitle></citerefentry>,
 256             <citerefentry><refentrytitle>imageAtomicCompSwap</refentrytitle></citerefentry>
 257         </para>
 258     </refsect1>
 259     <refsect1 id="Copyright"><title>Copyright</title>
 260         <para>
 261             Copyright <trademark class="copyright"></trademark> 2011-2012 Khronos Group.
 262             This material may be distributed subject to the terms and conditions set forth in
 263             the Open Publication License, v 1.0, 8 June 1999.
 264             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 265         </para>
 266     </refsect1>
 267 </refentry>