upstream-man-pages/man2/glConvolutionFilter2D.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="glConvolutionFilter2D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glConvolutionFilter2D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glConvolutionFilter2D</refname>
  17         <refpurpose>define a two-dimensional convolution filter</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glConvolutionFilter2D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
  25                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  27                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  28                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  29                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  30             </funcprototype>
  31         </funcsynopsis>
  32     </refsynopsisdiv>
  33     <refsect1 id="parameters"><title>Parameters</title>
  34         <variablelist>
  35         <varlistentry>
  36             <term><parameter>target</parameter></term>
  37             <listitem>
  38                 <para>
  39                     Must be <constant>GL_CONVOLUTION_2D</constant>.
  40                 </para>
  41             </listitem>
  42         </varlistentry>
  43         <varlistentry>
  44             <term><parameter>internalformat</parameter></term>
  45             <listitem>
  46                 <para>
  47                     The internal format of the convolution filter kernel.
  48                     The allowable values are
  49                     <constant>GL_ALPHA</constant>,
  50                     <constant>GL_ALPHA4</constant>,
  51                     <constant>GL_ALPHA8</constant>,
  52                     <constant>GL_ALPHA12</constant>,
  53                     <constant>GL_ALPHA16</constant>,
  54                     <constant>GL_LUMINANCE</constant>,
  55                     <constant>GL_LUMINANCE4</constant>,
  56                     <constant>GL_LUMINANCE8</constant>,
  57                     <constant>GL_LUMINANCE12</constant>,
  58                     <constant>GL_LUMINANCE16</constant>,
  59                     <constant>GL_LUMINANCE_ALPHA</constant>,
  60                     <constant>GL_LUMINANCE4_ALPHA4</constant>,
  61                     <constant>GL_LUMINANCE6_ALPHA2</constant>,
  62                     <constant>GL_LUMINANCE8_ALPHA8</constant>,
  63                     <constant>GL_LUMINANCE12_ALPHA4</constant>,
  64                     <constant>GL_LUMINANCE12_ALPHA12</constant>,
  65                     <constant>GL_LUMINANCE16_ALPHA16</constant>,
  66                     <constant>GL_INTENSITY</constant>,
  67                     <constant>GL_INTENSITY4</constant>,
  68                     <constant>GL_INTENSITY8</constant>,
  69                     <constant>GL_INTENSITY12</constant>,
  70                     <constant>GL_INTENSITY16</constant>,
  71                     <constant>GL_R3_G3_B2</constant>,
  72                     <constant>GL_RGB</constant>,
  73                     <constant>GL_RGB4</constant>,
  74                     <constant>GL_RGB5</constant>,
  75                     <constant>GL_RGB8</constant>,
  76                     <constant>GL_RGB10</constant>,
  77                     <constant>GL_RGB12</constant>,
  78                     <constant>GL_RGB16</constant>,
  79                     <constant>GL_RGBA</constant>,
  80                     <constant>GL_RGBA2</constant>,
  81                     <constant>GL_RGBA4</constant>,
  82                     <constant>GL_RGB5_A1</constant>,
  83                     <constant>GL_RGBA8</constant>,
  84                     <constant>GL_RGB10_A2</constant>,
  85                     <constant>GL_RGBA12</constant>, or
  86                     <constant>GL_RGBA16</constant>.
  87                 </para>
  88             </listitem>
  89         </varlistentry>
  90         <varlistentry>
  91             <term><parameter>width</parameter></term>
  92             <listitem>
  93                 <para>
  94                     The width of the pixel array referenced by <parameter>data</parameter>.
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98         <varlistentry>
  99             <term><parameter>height</parameter></term>
 100             <listitem>
 101                 <para>
 102                     The height of the pixel array referenced by <parameter>data</parameter>.
 103                 </para>
 104             </listitem>
 105         </varlistentry>
 106         <varlistentry>
 107             <term><parameter>format</parameter></term>
 108             <listitem>
 109                 <para>
 110                     The format of the pixel data in <parameter>data</parameter>.
 111                     The allowable values are
 112                     <constant>GL_RED</constant>,
 113                     <constant>GL_GREEN</constant>,
 114                     <constant>GL_BLUE</constant>,
 115                     <constant>GL_ALPHA</constant>,
 116                     <constant>GL_RGB</constant>,
 117                     <constant>GL_BGR</constant>,
 118                     <constant>GL_RGBA</constant>,
 119                     <constant>GL_BGRA</constant>,
 120                     <constant>GL_LUMINANCE</constant>, and
 121                     <constant>GL_LUMINANCE_ALPHA</constant>.
 122                 </para>
 123             </listitem>
 124         </varlistentry>
 125         <varlistentry>
 126             <term><parameter>type</parameter></term>
 127             <listitem>
 128                 <para>
 129                     The type of the pixel data in <parameter>data</parameter>.
 130                     Symbolic constants
 131                     <constant>GL_UNSIGNED_BYTE</constant>,
 132                     <constant>GL_BYTE</constant>,
 133                     <constant>GL_BITMAP</constant>,
 134                     <constant>GL_UNSIGNED_SHORT</constant>,
 135                     <constant>GL_SHORT</constant>,
 136                     <constant>GL_UNSIGNED_INT</constant>,
 137                     <constant>GL_INT</constant>,
 138                     <constant>GL_FLOAT</constant>,
 139                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 140                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 141                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 142                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 143                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 144                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 145                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 146                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 147                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 148                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 149                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 150                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 151                     are accepted.
 152                 </para>
 153             </listitem>
 154         </varlistentry>
 155         <varlistentry>
 156             <term><parameter>data</parameter></term>
 157             <listitem>
 158                 <para>
 159                     Pointer to a two-dimensional array of pixel data that is processed to
 160                     build the convolution filter kernel.
 161                 </para>
 162             </listitem>
 163         </varlistentry>
 164         </variablelist>
 165     </refsect1>
 166     <refsect1 id="description"><title>Description</title>
 167         <para>
 168             <function>glConvolutionFilter2D</function> builds a two-dimensional convolution filter kernel from an array of
 169             pixels.
 170         </para>
 171         <para>
 172             The pixel array specified by <parameter>width</parameter>, <parameter>height</parameter>, <parameter>format</parameter>, <parameter>type</parameter>, and
 173             <parameter>data</parameter> is extracted from memory and processed just as if
 174             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> were called, but processing stops after the final
 175             expansion to RGBA is completed.
 176         </para>
 177         <para>
 178             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 179             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a convolution filter is
 180             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 181         </para>
 182         <para>
 183             The R, G, B, and A components of each pixel are next scaled by the four
 184             2D <constant>GL_CONVOLUTION_FILTER_SCALE</constant> parameters and biased by the
 185             four 2D <constant>GL_CONVOLUTION_FILTER_BIAS</constant> parameters.
 186             (The scale and bias parameters are set by <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>
 187             using the <constant>GL_CONVOLUTION_2D</constant> target and the names
 188             <constant>GL_CONVOLUTION_FILTER_SCALE</constant> and <constant>GL_CONVOLUTION_FILTER_BIAS</constant>.
 189             The parameters themselves are vectors of four values that are applied to red,
 190             green, blue, and alpha, in that order.)
 191             The R, G, B, and A values are not clamped to [0,1] at any time during this
 192             process.
 193         </para>
 194         <para>
 195             Each pixel is then converted to the internal format specified by
 196             <parameter>internalformat</parameter>.
 197             This conversion simply maps the component values of the pixel (R, G, B,
 198             and A) to the values included in the internal format (red, green, blue,
 199             alpha, luminance, and intensity).  The mapping is as follows:
 200         </para>
 201         <para>
 202         </para>
 203         <informaltable frame="topbot">
 204             <tgroup cols="7" align="left">
 205                 <colspec colwidth="3*"/>
 206                 <colspec colwidth="1*" align="center"/>
 207                 <colspec colwidth="1*" align="center"/>
 208                 <colspec colwidth="1*" align="center"/>
 209                 <colspec colwidth="1*" align="center"/>
 210                 <colspec colwidth="1.7*" align="center"/>
 211                 <colspec colwidth="1.7*" align="center"/>
 212                 <thead>
 213                     <row>
 214                         <entry rowsep="1" align="left"><emphasis role="bold">
 215                         Internal Format
 216                         </emphasis></entry>
 217                         <entry rowsep="1" align="center"><emphasis role="bold">
 218                         Red
 219                         </emphasis></entry>
 220                         <entry rowsep="1" align="center"><emphasis role="bold">
 221                         Green
 222                         </emphasis></entry>
 223                         <entry rowsep="1" align="center"><emphasis role="bold">
 224                         Blue
 225                         </emphasis></entry>
 226                         <entry rowsep="1" align="center"><emphasis role="bold">
 227                         Alpha
 228                         </emphasis></entry>
 229                         <entry rowsep="1" align="center"><emphasis role="bold">
 230                         Luminance
 231                         </emphasis></entry>
 232                         <entry rowsep="1" align="center"><emphasis role="bold">
 233                         Intensity
 234                         </emphasis></entry>
 235                     </row>
 236                 </thead>
 237                 <tbody>
 238                     <row>
 239                         <entry align="left">
 240                         <constant>GL_ALPHA</constant>
 241                         </entry>
 242                         <entry align="center">
 243                         </entry>
 244                         <entry align="center">
 245                         </entry>
 246                         <entry align="center">
 247                         </entry>
 248                         <entry align="center">
 249                         A
 250                         </entry>
 251                         <entry align="center">
 252                         </entry>
 253                         <entry align="center">
 254
 255                         </entry>
 256                     </row>
 257                     <row>
 258                         <entry align="left">
 259                         <constant>GL_LUMINANCE</constant>
 260                         </entry>
 261                         <entry align="center">
 262                         </entry>
 263                         <entry align="center">
 264                         </entry>
 265                         <entry align="center">
 266                         </entry>
 267                         <entry align="center">
 268                         </entry>
 269                         <entry align="center">
 270                         R
 271                         </entry>
 272                         <entry align="center">
 273
 274                         </entry>
 275                     </row>
 276                     <row>
 277                         <entry align="left">
 278                         <constant>GL_LUMINANCE_ALPHA</constant>
 279                         </entry>
 280                         <entry align="center">
 281                         </entry>
 282                         <entry align="center">
 283                         </entry>
 284                         <entry align="center">
 285                         </entry>
 286                         <entry align="center">
 287                         A
 288                         </entry>
 289                         <entry align="center">
 290                         R
 291                         </entry>
 292                         <entry align="center">
 293
 294                         </entry>
 295                     </row>
 296                     <row>
 297                         <entry align="left">
 298                         <constant>GL_INTENSITY</constant>
 299                         </entry>
 300                         <entry align="center">
 301                         </entry>
 302                         <entry align="center">
 303                         </entry>
 304                         <entry align="center">
 305                         </entry>
 306                         <entry align="center">
 307                         </entry>
 308                         <entry align="center">
 309                         </entry>
 310                         <entry align="center">
 311                         R
 312                         </entry>
 313                     </row>
 314                     <row>
 315                         <entry align="left">
 316                         <constant>GL_RGB</constant>
 317                         </entry>
 318                         <entry align="center">
 319                         R
 320                         </entry>
 321                         <entry align="center">
 322                         G
 323                         </entry>
 324                         <entry align="center">
 325                         B
 326                         </entry>
 327                         <entry align="center">
 328                         </entry>
 329                         <entry align="center">
 330                         </entry>
 331                         <entry align="center">
 332
 333                         </entry>
 334                     </row>
 335                     <row>
 336                         <entry align="left">
 337                         <constant>GL_RGBA</constant>
 338                         </entry>
 339                         <entry align="center">
 340                         R
 341                         </entry>
 342                         <entry align="center">
 343                         G
 344                         </entry>
 345                         <entry align="center">
 346                         B
 347                         </entry>
 348                         <entry align="center">
 349                         A
 350                         </entry>
 351                         <entry align="center">
 352                         </entry>
 353                         <entry align="center">
 354
 355                         </entry>
 356                     </row>
 357                 </tbody>
 358             </tgroup>
 359         </informaltable>
 360         <para>
 361             The red, green, blue, alpha, luminance, and/or intensity components of
 362             the resulting pixels are stored in floating-point rather than integer
 363             format.
 364             They form a two-dimensional filter kernel image indexed with coordinates
 365             <emphasis>i</emphasis> and <emphasis>j</emphasis> such that <emphasis>i</emphasis> starts at zero and increases from left
 366             to right, and <emphasis>j</emphasis> starts at zero and increases from bottom to top.
 367             Kernel location <emphasis>i,j</emphasis> is derived from the <emphasis>N</emphasis>th pixel,
 368             where <emphasis>N</emphasis> is <emphasis>i</emphasis>+<emphasis>j</emphasis>*<parameter>width</parameter>.
 369         </para>
 370         <para>
 371             Note that after a convolution is performed, the resulting color
 372             components are also scaled by their corresponding
 373             <constant>GL_POST_CONVOLUTION_c_SCALE</constant> parameters and biased by their
 374             corresponding <constant>GL_POST_CONVOLUTION_c_BIAS</constant> parameters (where
 375             <emphasis>c</emphasis> takes on the values <emphasis role="bold">RED</emphasis>, <emphasis role="bold">GREEN</emphasis>, <emphasis role="bold">BLUE</emphasis>, and
 376             <emphasis role="bold">ALPHA</emphasis>).
 377             These parameters are set by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
 378         </para>
 379     </refsect1>
 380     <refsect1 id="notes"><title>Notes</title>
 381         <para>
 382             <function>glConvolutionFilter2D</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
 383             is called with an argument of <constant>GL_EXTENSIONS</constant>.
 384         </para>
 385     </refsect1>
 386     <refsect1 id="errors"><title>Errors</title>
 387         <para>
 388             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
 389             <constant>GL_CONVOLUTION_2D</constant>.
 390         </para>
 391         <para>
 392             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the
 393             allowable values.
 394         </para>
 395         <para>
 396             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
 397             values.
 398         </para>
 399         <para>
 400             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
 401             values.
 402         </para>
 403         <para>
 404             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than zero or greater
 405             than the maximum supported value.
 406             This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
 407             using target <constant>GL_CONVOLUTION_2D</constant> and name
 408             <constant>GL_MAX_CONVOLUTION_WIDTH</constant>.
 409         </para>
 410         <para>
 411             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>height</parameter> is less than zero or greater
 412             than the maximum supported value.
 413             This value may be queried with <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>
 414             using target <constant>GL_CONVOLUTION_2D</constant> and name
 415             <constant>GL_MAX_CONVOLUTION_HEIGHT</constant>.
 416         </para>
 417         <para>
 418             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>height</parameter> is one of
 419             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 420             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 421             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 422             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 423             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 424         </para>
 425         <para>
 426             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>height</parameter> is one of
 427             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 428             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 429             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 430             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 431             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 432             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 433             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 434             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 435             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 436         </para>
 437         <para>
 438             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 439             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 440         </para>
 441         <para>
 442             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 443             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 444             object such that the memory reads required would exceed the data store size.
 445         </para>
 446         <para>
 447             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 448             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 449             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 450         </para>
 451         <para>
 452             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glConvolutionFilter2D</function> is executed
 453             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 454             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 455         </para>
 456     </refsect1>
 457     <refsect1 id="associatedgets"><title>Associated Gets</title>
 458         <para>
 459             <citerefentry><refentrytitle>glGetConvolutionParameter</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetConvolutionFilter</refentrytitle></citerefentry>
 460         </para>
 461     </refsect1>
 462     <refsect1 id="seealso"><title>See Also</title>
 463         <para>
 464             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
 465             <citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
 466             <citerefentry><refentrytitle>glConvolutionParameter</refentrytitle></citerefentry>,
 467             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
 468         </para>
 469     </refsect1>
 470     <refsect1 id="Copyright"><title>Copyright</title>
 471         <para>
 472             Copyright <trademark class="copyright"></trademark> 1991-2006
 473             Silicon Graphics, Inc. This document is licensed under the SGI
 474             Free Software B License. For details, see
 475             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 476         </para>
 477     </refsect1>
 478 </refentry>