upstream-doc/man2/glLogicOp.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="glLogicOp">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glLogicOp</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glLogicOp</refname>
  17         <refpurpose>specify a logical pixel operation for color index rendering</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glLogicOp</function></funcdef>
  23                 <paramdef>GLenum <parameter>opcode</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29         <varlistentry>
  30             <term><parameter>opcode</parameter></term>
  31             <listitem>
  32                 <para>
  33                     Specifies a symbolic constant that selects a logical operation.
  34                     The following symbols are accepted:
  35                     <constant>GL_CLEAR</constant>,
  36                     <constant>GL_SET</constant>,
  37                     <constant>GL_COPY</constant>,
  38                     <constant>GL_COPY_INVERTED</constant>,
  39                     <constant>GL_NOOP</constant>,
  40                     <constant>GL_INVERT</constant>,
  41                     <constant>GL_AND</constant>,
  42                     <constant>GL_NAND</constant>,
  43                     <constant>GL_OR</constant>,
  44                     <constant>GL_NOR</constant>,
  45                     <constant>GL_XOR</constant>,
  46                     <constant>GL_EQUIV</constant>,
  47                     <constant>GL_AND_REVERSE</constant>,
  48                     <constant>GL_AND_INVERTED</constant>,
  49                     <constant>GL_OR_REVERSE</constant>, and
  50                     <constant>GL_OR_INVERTED</constant>. The initial value is <constant>GL_COPY</constant>.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         </variablelist>
  55     </refsect1>
  56     <refsect1 id="description"><title>Description</title>
  57         <para>
  58             <function>glLogicOp</function> specifies a logical operation that,
  59             when enabled,
  60             is applied between the incoming color index or RGBA color
  61             and the color index or RGBA color at the corresponding location in the
  62             frame buffer.
  63             To enable or disable the logical operation, call
  64             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
  65             using the symbolic constant <constant>GL_COLOR_LOGIC_OP</constant> for RGBA mode or
  66             <constant>GL_INDEX_LOGIC_OP</constant> for color index mode. The initial value is
  67             disabled for both operations.
  68         </para>
  69         <para>
  70         </para>
  71         <informaltable frame="topbot">
  72             <tgroup cols="2" align="left">
  73                 <colspec/>
  74                 <colspec/>
  75                 <thead>
  76                     <row>
  77                         <entry rowsep="1" align="left"><emphasis role="bold">
  78                         Opcode
  79                         </emphasis></entry>
  80                         <entry rowsep="1" align="left"><emphasis role="bold">
  81                         Resulting Operation
  82                         </emphasis></entry>
  83                     </row>
  84                 </thead>
  85                 <tbody>
  86                     <row>
  87                         <entry align="left">
  88                         <constant>GL_CLEAR</constant>
  89                         </entry>
  90                         <entry align="center">
  91                         0
  92                         </entry>
  93                     </row>
  94                     <row>
  95                         <entry align="left">
  96                         <constant>GL_SET</constant>
  97                         </entry>
  98                         <entry align="center">
  99                         1
 100                         </entry>
 101                     </row>
 102                     <row>
 103                         <entry align="left">
 104                         <constant>GL_COPY</constant>
 105                         </entry>
 106                         <entry align="center">
 107                         s
 108                         </entry>
 109                     </row>
 110                     <row>
 111                         <entry align="left">
 112                         <constant>GL_COPY_INVERTED</constant>
 113                         </entry>
 114                         <entry align="center">
 115                         ~s
 116                         </entry>
 117                     </row>
 118                     <row>
 119                         <entry align="left">
 120                         <constant>GL_NOOP</constant>
 121                         </entry>
 122                         <entry align="center">
 123                         d
 124                         </entry>
 125                     </row>
 126                     <row>
 127                         <entry align="left">
 128                         <constant>GL_INVERT</constant>
 129                         </entry>
 130                         <entry align="center">
 131                         ~d
 132                         </entry>
 133                     </row>
 134                     <row>
 135                         <entry align="left">
 136                         <constant>GL_AND</constant>
 137                         </entry>
 138                         <entry align="center">
 139                         s &amp; d
 140                         </entry>
 141                     </row>
 142                     <row>
 143                         <entry align="left">
 144                         <constant>GL_NAND</constant>
 145                         </entry>
 146                         <entry align="center">
 147                         ~(s &amp; d)
 148                         </entry>
 149                     </row>
 150                     <row>
 151                         <entry align="left">
 152                         <constant>GL_OR</constant>
 153                         </entry>
 154                         <entry align="center">
 155                         s | d
 156                         </entry>
 157                     </row>
 158                     <row>
 159                         <entry align="left">
 160                         <constant>GL_NOR</constant>
 161                         </entry>
 162                         <entry align="center">
 163                         ~(s | d)
 164                         </entry>
 165                     </row>
 166                     <row>
 167                         <entry align="left">
 168                         <constant>GL_XOR</constant>
 169                         </entry>
 170                         <entry align="center">
 171                         s ^ d
 172                         </entry>
 173                     </row>
 174                     <row>
 175                         <entry align="left">
 176                         <constant>GL_EQUIV</constant>
 177                         </entry>
 178                         <entry align="center">
 179                         ~(s ^ d)
 180                         </entry>
 181                     </row>
 182                     <row>
 183                         <entry align="left">
 184                         <constant>GL_AND_REVERSE</constant>
 185                         </entry>
 186                         <entry align="center">
 187                         s &amp; ~d
 188                         </entry>
 189                     </row>
 190                     <row>
 191                         <entry align="left">
 192                         <constant>GL_AND_INVERTED</constant>
 193                         </entry>
 194                         <entry align="center">
 195                         ~s &amp; d
 196                         </entry>
 197                     </row>
 198                     <row>
 199                         <entry align="left">
 200                         <constant>GL_OR_REVERSE</constant>
 201                         </entry>
 202                         <entry align="center">
 203                         s | ~d
 204                         </entry>
 205                     </row>
 206                     <row>
 207                         <entry align="left">
 208                         <constant>GL_OR_INVERTED</constant>
 209                         </entry>
 210                         <entry align="center">
 211                         ~s | d
 212                         </entry>
 213                     </row>
 214                 </tbody>
 215             </tgroup>
 216         </informaltable>
 217         <para>
 218             <parameter>opcode</parameter> is a symbolic constant chosen from the list above.
 219             In the explanation of the logical operations,
 220             <emphasis>s</emphasis> represents the incoming color index and
 221             <emphasis>d</emphasis> represents the index in the frame buffer.
 222             Standard C-language operators are used.
 223             As these bitwise operators suggest,
 224             the logical operation is applied independently to each bit pair of the
 225             source and destination indices or colors.
 226         </para>
 227     </refsect1>
 228     <refsect1 id="notes"><title>Notes</title>
 229         <para>
 230             Color index logical operations are always supported. RGBA logical
 231             operations are supported only if the GL version is 1.1 or greater.
 232         </para>
 233         <para>
 234             When more than one RGBA color or index buffer is enabled for drawing,
 235             logical operations are performed separately for each enabled buffer,
 236             using for the destination value the contents of that buffer
 237             (see <citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>).
 238         </para>
 239     </refsect1>
 240     <refsect1 id="errors"><title>Errors</title>
 241         <para>
 242             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>opcode</parameter> is not an accepted value.
 243         </para>
 244         <para>
 245             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glLogicOp</function>
 246             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 247             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 248         </para>
 249     </refsect1>
 250     <refsect1 id="associatedgets"><title>Associated Gets</title>
 251         <para>
 252             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LOGIC_OP_MODE</constant>.
 253         </para>
 254         <para>
 255             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_COLOR_LOGIC_OP</constant> or <constant>GL_INDEX_LOGIC_OP</constant>.
 256         </para>
 257     </refsect1>
 258     <refsect1 id="seealso"><title>See Also</title>
 259         <para>
 260             <citerefentry><refentrytitle>glAlphaFunc</refentrytitle></citerefentry>,
 261             <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 262             <citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
 263             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 264             <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>
 265         </para>
 266     </refsect1>
 267     <refsect1 id="Copyright"><title>Copyright</title>
 268         <para>
 269             Copyright <trademark class="copyright"></trademark> 1991-2006
 270             Silicon Graphics, Inc. This document is licensed under the SGI
 271             Free Software B License. For details, see
 272             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 273         </para>
 274     </refsect1>
 275 </refentry>