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