upstream-man-pages/man2/xhtml/glSeparableFilter2D.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glSeparableFilter2D</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glSeparableFilter2D"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glSeparableFilter2D — define a separable two-dimensional convolution filter</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glSeparableFilter2D</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">internalformat</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">height</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">format</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const GLvoid *  </td><td><var class="pdparam">row</var>, </td></tr><tr><td> </td><td>const GLvoid *  </td><td><var class="pdparam">column</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
   4                     Must be <code class="constant">GL_SEPARABLE_2D</code>.
   5                 </p></dd><dt><span class="term"><em class="parameter"><code>internalformat</code></em></span></dt><dd><p>
   6                     The internal format of the convolution filter kernel.
   7                     The allowable values are
   8                     <code class="constant">GL_ALPHA</code>,
   9                     <code class="constant">GL_ALPHA4</code>,
  10                     <code class="constant">GL_ALPHA8</code>,
  11                     <code class="constant">GL_ALPHA12</code>,
  12                     <code class="constant">GL_ALPHA16</code>,
  13                     <code class="constant">GL_LUMINANCE</code>,
  14                     <code class="constant">GL_LUMINANCE4</code>,
  15                     <code class="constant">GL_LUMINANCE8</code>,
  16                     <code class="constant">GL_LUMINANCE12</code>,
  17                     <code class="constant">GL_LUMINANCE16</code>,
  18                     <code class="constant">GL_LUMINANCE_ALPHA</code>,
  19                     <code class="constant">GL_LUMINANCE4_ALPHA4</code>,
  20                     <code class="constant">GL_LUMINANCE6_ALPHA2</code>,
  21                     <code class="constant">GL_LUMINANCE8_ALPHA8</code>,
  22                     <code class="constant">GL_LUMINANCE12_ALPHA4</code>,
  23                     <code class="constant">GL_LUMINANCE12_ALPHA12</code>,
  24                     <code class="constant">GL_LUMINANCE16_ALPHA16</code>,
  25                     <code class="constant">GL_INTENSITY</code>,
  26                     <code class="constant">GL_INTENSITY4</code>,
  27                     <code class="constant">GL_INTENSITY8</code>,
  28                     <code class="constant">GL_INTENSITY12</code>,
  29                     <code class="constant">GL_INTENSITY16</code>,
  30                     <code class="constant">GL_R3_G3_B2</code>,
  31                     <code class="constant">GL_RGB</code>,
  32                     <code class="constant">GL_RGB4</code>,
  33                     <code class="constant">GL_RGB5</code>,
  34                     <code class="constant">GL_RGB8</code>,
  35                     <code class="constant">GL_RGB10</code>,
  36                     <code class="constant">GL_RGB12</code>,
  37                     <code class="constant">GL_RGB16</code>,
  38                     <code class="constant">GL_RGBA</code>,
  39                     <code class="constant">GL_RGBA2</code>,
  40                     <code class="constant">GL_RGBA4</code>,
  41                     <code class="constant">GL_RGB5_A1</code>,
  42                     <code class="constant">GL_RGBA8</code>,
  43                     <code class="constant">GL_RGB10_A2</code>,
  44                     <code class="constant">GL_RGBA12</code>, or
  45                     <code class="constant">GL_RGBA16</code>.
  46                 </p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>
  47                     The number of elements in the pixel array referenced by <em class="parameter"><code>row</code></em>.
  48                     (This is the width of the separable filter kernel.)
  49                 </p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>
  50                     The number of elements in the pixel array referenced by <em class="parameter"><code>column</code></em>.
  51                     (This is the height of the separable filter kernel.)
  52                 </p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>
  53                     The format of the pixel data in <em class="parameter"><code>row</code></em> and <em class="parameter"><code>column</code></em>.
  54                     The allowable values are
  55                     <code class="constant">GL_RED</code>,
  56                     <code class="constant">GL_GREEN</code>,
  57                     <code class="constant">GL_BLUE</code>,
  58                     <code class="constant">GL_ALPHA</code>,
  59                     <code class="constant">GL_RGB</code>,
  60                     <code class="constant">GL_BGR</code>,
  61                     <code class="constant">GL_RGBA</code>,
  62                     <code class="constant">GL_BGRA</code>,
  63                     <code class="constant">GL_INTENSITY</code>,
  64                     <code class="constant">GL_LUMINANCE</code>, and
  65                     <code class="constant">GL_LUMINANCE_ALPHA</code>.
  66                 </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
  67                     The type of the pixel data in <em class="parameter"><code>row</code></em> and <em class="parameter"><code>column</code></em>.
  68                     Symbolic constants
  69                     <code class="constant">GL_UNSIGNED_BYTE</code>,
  70                     <code class="constant">GL_BYTE</code>,
  71                     <code class="constant">GL_BITMAP</code>,
  72                     <code class="constant">GL_UNSIGNED_SHORT</code>,
  73                     <code class="constant">GL_SHORT</code>,
  74                     <code class="constant">GL_UNSIGNED_INT</code>,
  75                     <code class="constant">GL_INT</code>,
  76                     <code class="constant">GL_FLOAT</code>,
  77                     <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
  78                     <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
  79                     <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>,
  80                     <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>,
  81                     <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
  82                     <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
  83                     <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
  84                     <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
  85                     <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
  86                     <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
  87                     <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, and
  88                     <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
  89                     are accepted.
  90                 </p></dd><dt><span class="term"><em class="parameter"><code>row</code></em></span></dt><dd><p>
  91                     Pointer to a one-dimensional array of pixel data that is processed to
  92                     build the row filter kernel.
  93                 </p></dd><dt><span class="term"><em class="parameter"><code>column</code></em></span></dt><dd><p>
  94                     Pointer to a one-dimensional array of pixel data that is processed to
  95                     build the column filter kernel.
  96                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  97             <code class="function">glSeparableFilter2D</code> builds a two-dimensional separable convolution filter kernel from
  98             two arrays of pixels.
  99         </p><p>
 100             The pixel arrays specified by (<em class="parameter"><code>width</code></em>, <em class="parameter"><code>format</code></em>, <em class="parameter"><code>type</code></em>, <em class="parameter"><code>row</code></em>)
 101             and (<em class="parameter"><code>height</code></em>, <em class="parameter"><code>format</code></em>, <em class="parameter"><code>type</code></em>, <em class="parameter"><code>column</code></em>) are processed just as if
 102             they had been passed to <a class="citerefentry" href="glDrawPixels.xml"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a>,
 103             but processing stops after the final expansion to RGBA is completed.
 104         </p><p>
 105             If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target
 106             (see <a class="citerefentry" href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a convolution filter is
 107             specified, <em class="parameter"><code>row</code></em> and <em class="parameter"><code>column</code></em> are treated as byte offsets into the buffer object's data store.
 108         </p><p>
 109             Next, the R, G, B, and A components of all pixels in both arrays are scaled
 110             by the four separable 2D <code class="constant">GL_CONVOLUTION_FILTER_SCALE</code> parameters and
 111             biased by the four separable 2D <code class="constant">GL_CONVOLUTION_FILTER_BIAS</code> parameters.
 112             (The scale and bias parameters are set by <a class="citerefentry" href="glConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glConvolutionParameter</span></span></a>
 113             using the <code class="constant">GL_SEPARABLE_2D</code> target and the names
 114             <code class="constant">GL_CONVOLUTION_FILTER_SCALE</code> and <code class="constant">GL_CONVOLUTION_FILTER_BIAS</code>.
 115             The parameters themselves are vectors of four values that are applied to red,
 116             green, blue, and alpha, in that order.)
 117             The R, G, B, and A values are not clamped to [0,1] at any time during this
 118             process.
 119         </p><p>
 120             Each pixel is then converted to the internal format specified by
 121             <em class="parameter"><code>internalformat</code></em>.
 122             This conversion simply maps the component values of the pixel (R, G, B,
 123             and A) to the values included in the internal format (red, green, blue,
 124             alpha, luminance, and intensity).  The mapping is as follows:
 125         </p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /><col align="center" /></colgroup><thead><tr><th align="left"><span class="bold"><strong>
 126                         Internal Format
 127                         </strong></span></th><th align="center"><span class="bold"><strong>
 128                         Red
 129                         </strong></span></th><th align="center"><span class="bold"><strong>
 130                         Green
 131                         </strong></span></th><th align="center"><span class="bold"><strong>
 132                         Blue
 133                         </strong></span></th><th align="center"><span class="bold"><strong>
 134                         Alpha
 135                         </strong></span></th><th align="center"><span class="bold"><strong>
 136                         Luminance
 137                         </strong></span></th><th align="center"><span class="bold"><strong>
 138                         Intensity
 139                         </strong></span></th></tr></thead><tbody><tr><td align="left">
 140                         <code class="constant">GL_LUMINANCE</code>
 141                         </td><td align="center">
 142                         </td><td align="center">
 143                         </td><td align="center">
 144                         </td><td align="center">
 145                         </td><td align="center">
 146                         R
 147                         </td><td align="center">
 148
 149                         </td></tr><tr><td align="left">
 150                         <code class="constant">GL_LUMINANCE_ALPHA</code>
 151                         </td><td align="center">
 152                         </td><td align="center">
 153                         </td><td align="center">
 154                         </td><td align="center">
 155                         A
 156                         </td><td align="center">
 157                         R
 158                         </td><td align="center">
 159
 160                         </td></tr><tr><td align="left">
 161                         <code class="constant">GL_INTENSITY</code>
 162                         </td><td align="center">
 163                         </td><td align="center">
 164                         </td><td align="center">
 165                         </td><td align="center">
 166                         </td><td align="center">
 167                         </td><td align="center">
 168                         R
 169                         </td></tr><tr><td align="left">
 170                         <code class="constant">GL_RGB</code>
 171                         </td><td align="center">
 172                         R
 173                         </td><td align="center">
 174                         G
 175                         </td><td align="center">
 176                         B
 177                         </td><td align="center">
 178                         </td><td align="center">
 179                         </td><td align="center">
 180
 181                         </td></tr><tr><td align="left">
 182                         <code class="constant">GL_RGBA</code>
 183                         </td><td align="center">
 184                         R
 185                         </td><td align="center">
 186                         G
 187                         </td><td align="center">
 188                         B
 189                         </td><td align="center">
 190                         A
 191                         </td><td align="center">
 192                         </td><td align="center">
 193
 194                         </td></tr></tbody></table></div><p>
 195             The red, green, blue, alpha, luminance, and/or intensity components of
 196             the resulting pixels are stored in floating-point rather than integer
 197             format.
 198             They form two one-dimensional filter kernel images.
 199             The row image is indexed by coordinate <span class="emphasis"><em>i</em></span> starting at zero and
 200             increasing from left to right.
 201             Each location in the row image is derived from element <span class="emphasis"><em>i</em></span> of <em class="parameter"><code>row</code></em>.
 202             The column image is indexed by coordinate <span class="emphasis"><em>j</em></span> starting at zero
 203             and increasing from bottom to top.
 204             Each location in the column image is derived from element <span class="emphasis"><em>j</em></span> of <em class="parameter"><code>column</code></em>.
 205         </p><p>
 206             Note that after a convolution is performed, the resulting color
 207             components are also scaled by their corresponding
 208             <code class="constant">GL_POST_CONVOLUTION_c_SCALE</code> parameters and biased by their
 209             corresponding <code class="constant">GL_POST_CONVOLUTION_c_BIAS</code> parameters (where
 210             <span class="emphasis"><em>c</em></span> takes on the values <span class="bold"><strong>RED</strong></span>, <span class="bold"><strong>GREEN</strong></span>, <span class="bold"><strong>BLUE</strong></span>, and
 211             <span class="bold"><strong>ALPHA</strong></span>).
 212             These parameters are set by <a class="citerefentry" href="glPixelTransfer.xml"><span class="citerefentry"><span class="refentrytitle">glPixelTransfer</span></span></a>.
 213         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 214             <code class="function">glSeparableFilter2D</code> is present only if <code class="code">ARB_imaging</code> is returned when <a class="citerefentry" href="glGetString.xml"><span class="citerefentry"><span class="refentrytitle">glGetString</span></span></a>
 215             is called with an argument of <code class="constant">GL_EXTENSIONS</code>.
 216         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 217             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not
 218             <code class="constant">GL_SEPARABLE_2D</code>.
 219         </p><p>
 220             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>internalformat</code></em> is not one of the
 221             allowable values.
 222         </p><p>
 223             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>format</code></em> is not one of the allowable
 224             values.
 225         </p><p>
 226             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not one of the allowable
 227             values.
 228         </p><p>
 229             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em> is less than zero or greater
 230             than the maximum supported value.
 231             This value may be queried with <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>
 232             using target <code class="constant">GL_SEPARABLE_2D</code> and name
 233             <code class="constant">GL_MAX_CONVOLUTION_WIDTH</code>.
 234         </p><p>
 235             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>height</code></em> is less than zero or greater
 236             than the maximum supported value.
 237             This value may be queried with <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>
 238             using target <code class="constant">GL_SEPARABLE_2D</code> and name
 239             <code class="constant">GL_MAX_CONVOLUTION_HEIGHT</code>.
 240         </p><p>
 241             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>height</code></em> is one of
 242             <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
 243             <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
 244             <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>, or
 245             <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>
 246             and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_RGB</code>.
 247         </p><p>
 248             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>height</code></em> is one of
 249             <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
 250             <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
 251             <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
 252             <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
 253             <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
 254             <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
 255             <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, or
 256             <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
 257             and <em class="parameter"><code>format</code></em> is neither <code class="constant">GL_RGBA</code> nor <code class="constant">GL_BGRA</code>.
 258         </p><p>
 259             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 260             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the buffer object's data store is currently mapped.
 261         </p><p>
 262             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 263             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer
 264             object such that the memory reads required would exceed the data store size.
 265         </p><p>
 266             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 267             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>row</code></em> or
 268             <em class="parameter"><code>column</code></em> is not evenly divisible
 269             into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.
 270         </p><p>
 271             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glSeparableFilter2D</code> is executed
 272             between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding
 273             execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 274         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 275             <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>, <a class="citerefentry" href="glGetSeparableFilter.xml"><span class="citerefentry"><span class="refentrytitle">glGetSeparableFilter</span></span></a>
 276         </p><p>
 277             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_PIXEL_UNPACK_BUFFER_BINDING</code>
 278         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 279             <a class="citerefentry" href="glConvolutionFilter1D.xml"><span class="citerefentry"><span class="refentrytitle">glConvolutionFilter1D</span></span></a>,
 280             <a class="citerefentry" href="glConvolutionFilter2D.xml"><span class="citerefentry"><span class="refentrytitle">glConvolutionFilter2D</span></span></a>,
 281             <a class="citerefentry" href="glConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glConvolutionParameter</span></span></a>,
 282             <a class="citerefentry" href="glPixelTransfer.xml"><span class="citerefentry"><span class="refentrytitle">glPixelTransfer</span></span></a>
 283         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 284             Copyright <span class="trademark"></span>© 1991-2006
 285             Silicon Graphics, Inc. This document is licensed under the SGI
 286             Free Software B License. For details, see
 287             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 288         </p></div></div></body></html>