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">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glConvolutionFilter1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glConvolutionFilter1D
</refname>
17 <refpurpose>define a one-dimensional convolution filter
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
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>
32 <refsect1 id=
"parameters"><title>Parameters
</title>
35 <term><parameter>target
</parameter></term>
38 Must be
<constant>GL_CONVOLUTION_1D
</constant>.
43 <term><parameter>internalformat
</parameter></term>
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>.
90 <term><parameter>width
</parameter></term>
93 The width of the pixel array referenced by
<parameter>data
</parameter>.
98 <term><parameter>format
</parameter></term>
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>.
113 <term><parameter>type
</parameter></term>
116 The type of the pixel data in
<parameter>data
</parameter>.
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>
143 <term><parameter>data
</parameter></term>
146 Pointer to a one-dimensional array of pixel data that is processed to
147 build the convolution filter kernel.
153 <refsect1 id=
"description"><title>Description
</title>
155 <function>glConvolutionFilter1D
</function> builds a one-dimensional convolution filter kernel from an array of
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.
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.
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
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:
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"/>
201 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
204 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
207 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
210 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
213 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
216 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
219 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
227 <constant>GL_ALPHA
</constant>
229 <entry align=
"center">
231 <entry align=
"center">
233 <entry align=
"center">
235 <entry align=
"center">
238 <entry align=
"center">
240 <entry align=
"center">
246 <constant>GL_LUMINANCE
</constant>
248 <entry align=
"center">
250 <entry align=
"center">
252 <entry align=
"center">
254 <entry align=
"center">
256 <entry align=
"center">
259 <entry align=
"center">
265 <constant>GL_LUMINANCE_ALPHA
</constant>
267 <entry align=
"center">
269 <entry align=
"center">
271 <entry align=
"center">
273 <entry align=
"center">
276 <entry align=
"center">
279 <entry align=
"center">
285 <constant>GL_INTENSITY
</constant>
287 <entry align=
"center">
289 <entry align=
"center">
291 <entry align=
"center">
293 <entry align=
"center">
295 <entry align=
"center">
297 <entry align=
"center">
303 <constant>GL_RGB
</constant>
305 <entry align=
"center">
308 <entry align=
"center">
311 <entry align=
"center">
314 <entry align=
"center">
316 <entry align=
"center">
318 <entry align=
"center">
324 <constant>GL_RGBA
</constant>
326 <entry align=
"center">
329 <entry align=
"center">
332 <entry align=
"center">
335 <entry align=
"center">
338 <entry align=
"center">
340 <entry align=
"center">
348 The red, green, blue, alpha, luminance, and/or intensity components of
349 the resulting pixels are stored in floating-point rather than integer
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.
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>.
365 <refsect1 id=
"notes"><title>Notes
</title>
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>.
371 <refsect1 id=
"errors"><title>Errors
</title>
373 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not
374 <constant>GL_CONVOLUTION_1D
</constant>.
377 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the
381 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not one of the allowable
385 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not one of the allowable
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>.
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>.
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>.
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.
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.
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>.
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>.
435 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
437 <citerefentry><refentrytitle>glGetConvolutionParameter
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetConvolutionFilter
</refentrytitle></citerefentry>
440 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
443 <refsect1 id=
"seealso"><title>See Also
</title>
445 <citerefentry><refentrytitle>glConvolutionFilter2D
</refentrytitle></citerefentry>,
446 <citerefentry><refentrytitle>glSeparableFilter2D
</refentrytitle></citerefentry>,
447 <citerefentry><refentrytitle>glConvolutionParameter
</refentrytitle></citerefentry>,
448 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>
451 <refsect1 id=
"Copyright"><title>Copyright
</title>
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>.