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">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glConvolutionFilter2D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glConvolutionFilter2D
</refname>
17 <refpurpose>define a two-dimensional convolution filter
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
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>
33 <refsect1 id=
"parameters"><title>Parameters
</title>
36 <term><parameter>target
</parameter></term>
39 Must be
<constant>GL_CONVOLUTION_2D
</constant>.
44 <term><parameter>internalformat
</parameter></term>
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>.
91 <term><parameter>width
</parameter></term>
94 The width of the pixel array referenced by
<parameter>data
</parameter>.
99 <term><parameter>height
</parameter></term>
102 The height of the pixel array referenced by
<parameter>data
</parameter>.
107 <term><parameter>format
</parameter></term>
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>.
126 <term><parameter>type
</parameter></term>
129 The type of the pixel data in
<parameter>data
</parameter>.
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>
156 <term><parameter>data
</parameter></term>
159 Pointer to a two-dimensional array of pixel data that is processed to
160 build the convolution filter kernel.
166 <refsect1 id=
"description"><title>Description
</title>
168 <function>glConvolutionFilter2D
</function> builds a two-dimensional convolution filter kernel from an array of
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.
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.
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
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:
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"/>
214 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
217 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
220 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
223 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
226 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
229 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
232 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
240 <constant>GL_ALPHA
</constant>
242 <entry align=
"center">
244 <entry align=
"center">
246 <entry align=
"center">
248 <entry align=
"center">
251 <entry align=
"center">
253 <entry align=
"center">
259 <constant>GL_LUMINANCE
</constant>
261 <entry align=
"center">
263 <entry align=
"center">
265 <entry align=
"center">
267 <entry align=
"center">
269 <entry align=
"center">
272 <entry align=
"center">
278 <constant>GL_LUMINANCE_ALPHA
</constant>
280 <entry align=
"center">
282 <entry align=
"center">
284 <entry align=
"center">
286 <entry align=
"center">
289 <entry align=
"center">
292 <entry align=
"center">
298 <constant>GL_INTENSITY
</constant>
300 <entry align=
"center">
302 <entry align=
"center">
304 <entry align=
"center">
306 <entry align=
"center">
308 <entry align=
"center">
310 <entry align=
"center">
316 <constant>GL_RGB
</constant>
318 <entry align=
"center">
321 <entry align=
"center">
324 <entry align=
"center">
327 <entry align=
"center">
329 <entry align=
"center">
331 <entry align=
"center">
337 <constant>GL_RGBA
</constant>
339 <entry align=
"center">
342 <entry align=
"center">
345 <entry align=
"center">
348 <entry align=
"center">
351 <entry align=
"center">
353 <entry align=
"center">
361 The red, green, blue, alpha, luminance, and/or intensity components of
362 the resulting pixels are stored in floating-point rather than integer
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>.
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>.
380 <refsect1 id=
"notes"><title>Notes
</title>
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>.
386 <refsect1 id=
"errors"><title>Errors
</title>
388 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not
389 <constant>GL_CONVOLUTION_2D
</constant>.
392 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the
396 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not one of the allowable
400 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not one of the allowable
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>.
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>.
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>.
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>.
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.
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.
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>.
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>.
457 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
459 <citerefentry><refentrytitle>glGetConvolutionParameter
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetConvolutionFilter
</refentrytitle></citerefentry>
462 <refsect1 id=
"seealso"><title>See Also
</title>
464 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
465 <citerefentry><refentrytitle>glSeparableFilter2D
</refentrytitle></citerefentry>,
466 <citerefentry><refentrytitle>glConvolutionParameter
</refentrytitle></citerefentry>,
467 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>
470 <refsect1 id=
"Copyright"><title>Copyright
</title>
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>.