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=
"glCopyConvolutionFilter1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCopyConvolutionFilter1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCopyConvolutionFilter1D
</refname>
17 <refpurpose>copy pixels into a one-dimensional convolution filter
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCopyConvolutionFilter1D
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLenum
<parameter>internalformat
</parameter></paramdef>
25 <paramdef>GLint
<parameter>x
</parameter></paramdef>
26 <paramdef>GLint
<parameter>y
</parameter></paramdef>
27 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
31 <refsect1 id=
"parameters"><title>Parameters
</title>
34 <term><parameter>target
</parameter></term>
37 Must be
<constant>GL_CONVOLUTION_1D
</constant>.
42 <term><parameter>internalformat
</parameter></term>
45 The internal format of the convolution filter kernel.
46 The allowable values are
47 <constant>GL_ALPHA
</constant>,
48 <constant>GL_ALPHA4
</constant>,
49 <constant>GL_ALPHA8
</constant>,
50 <constant>GL_ALPHA12
</constant>,
51 <constant>GL_ALPHA16
</constant>,
52 <constant>GL_LUMINANCE
</constant>,
53 <constant>GL_LUMINANCE4
</constant>,
54 <constant>GL_LUMINANCE8
</constant>,
55 <constant>GL_LUMINANCE12
</constant>,
56 <constant>GL_LUMINANCE16
</constant>,
57 <constant>GL_LUMINANCE_ALPHA
</constant>,
58 <constant>GL_LUMINANCE4_ALPHA4
</constant>,
59 <constant>GL_LUMINANCE6_ALPHA2
</constant>,
60 <constant>GL_LUMINANCE8_ALPHA8
</constant>,
61 <constant>GL_LUMINANCE12_ALPHA4
</constant>,
62 <constant>GL_LUMINANCE12_ALPHA12
</constant>,
63 <constant>GL_LUMINANCE16_ALPHA16
</constant>,
64 <constant>GL_INTENSITY
</constant>,
65 <constant>GL_INTENSITY4
</constant>,
66 <constant>GL_INTENSITY8
</constant>,
67 <constant>GL_INTENSITY12
</constant>,
68 <constant>GL_INTENSITY16
</constant>,
69 <constant>GL_R3_G3_B2
</constant>,
70 <constant>GL_RGB
</constant>,
71 <constant>GL_RGB4
</constant>,
72 <constant>GL_RGB5
</constant>,
73 <constant>GL_RGB8
</constant>,
74 <constant>GL_RGB10
</constant>,
75 <constant>GL_RGB12
</constant>,
76 <constant>GL_RGB16
</constant>,
77 <constant>GL_RGBA
</constant>,
78 <constant>GL_RGBA2
</constant>,
79 <constant>GL_RGBA4
</constant>,
80 <constant>GL_RGB5_A1
</constant>,
81 <constant>GL_RGBA8
</constant>,
82 <constant>GL_RGB10_A2
</constant>,
83 <constant>GL_RGBA12
</constant>, or
84 <constant>GL_RGBA16
</constant>.
89 <term><parameter>x
</parameter></term>
90 <term><parameter>y
</parameter></term>
93 The window space coordinates of the lower-left coordinate of the
99 <term><parameter>width
</parameter></term>
102 The width of the pixel array to copy.
108 <refsect1 id=
"description"><title>Description
</title>
110 <function>glCopyConvolutionFilter1D
</function> defines a one-dimensional convolution filter kernel with pixels
111 from the current
<constant>GL_READ_BUFFER
</constant> (rather than from main memory,
112 as is the case for
<citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>).
115 The screen-aligned pixel rectangle with lower-left corner at (
<parameter>x
</parameter>,\
<parameter>y
</parameter>),
116 width
<parameter>width
</parameter> and height
1 is used to define
117 the convolution filter. If any pixels within this region are
118 outside the window that is associated with the GL context, the
119 values obtained for those pixels are undefined.
122 The pixels in the rectangle are processed exactly as if
<citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>
123 had been called with
<emphasis>format
</emphasis>
124 set to RGBA, but the process stops just before final conversion.
125 The R, G, B, and A components of each pixel are next scaled by the four
126 1D
<constant>GL_CONVOLUTION_FILTER_SCALE
</constant> parameters and biased by the
127 four
1D
<constant>GL_CONVOLUTION_FILTER_BIAS
</constant> parameters.
128 (The scale and bias parameters are set by
<citerefentry><refentrytitle>glConvolutionParameter
</refentrytitle></citerefentry>
129 using the
<constant>GL_CONVOLUTION_1D
</constant> target and the names
130 <constant>GL_CONVOLUTION_FILTER_SCALE
</constant> and
<constant>GL_CONVOLUTION_FILTER_BIAS
</constant>.
131 The parameters themselves are vectors of four values that are applied to red,
132 green, blue, and alpha, in that order.)
133 The R, G, B, and A values are not clamped to [
0,
1] at any time during this
137 Each pixel is then converted to the internal format specified by
138 <parameter>internalformat
</parameter>.
139 This conversion simply maps the component values of the pixel (R, G, B,
140 and A) to the values included in the internal format (red, green, blue,
141 alpha, luminance, and intensity). The mapping is as follows:
145 <informaltable frame=
"topbot">
146 <tgroup cols=
"7" align=
"left">
147 <colspec colwidth=
"3*" />
148 <colspec colwidth=
"1*" align=
"center"/>
149 <colspec colwidth=
"1*" align=
"center"/>
150 <colspec colwidth=
"1*" align=
"center"/>
151 <colspec colwidth=
"1*" align=
"center"/>
152 <colspec colwidth=
"1.7*" align=
"center"/>
153 <colspec colwidth=
"1.7*" align=
"center"/>
156 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
159 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
162 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
165 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
168 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
171 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
174 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
182 <constant>GL_ALPHA
</constant>
184 <entry align=
"center">
186 <entry align=
"center">
188 <entry align=
"center">
190 <entry align=
"center">
193 <entry align=
"center">
195 <entry align=
"center">
201 <constant>GL_LUMINANCE
</constant>
203 <entry align=
"center">
205 <entry align=
"center">
207 <entry align=
"center">
209 <entry align=
"center">
211 <entry align=
"center">
214 <entry align=
"center">
220 <constant>GL_LUMINANCE_ALPHA
</constant>
222 <entry align=
"center">
224 <entry align=
"center">
226 <entry align=
"center">
228 <entry align=
"center">
231 <entry align=
"center">
234 <entry align=
"center">
240 <constant>GL_INTENSITY
</constant>
242 <entry align=
"center">
244 <entry align=
"center">
246 <entry align=
"center">
248 <entry align=
"center">
250 <entry align=
"center">
252 <entry align=
"center">
258 <constant>GL_RGB
</constant>
260 <entry align=
"center">
263 <entry align=
"center">
266 <entry align=
"center">
269 <entry align=
"center">
271 <entry align=
"center">
273 <entry align=
"center">
279 <constant>GL_RGBA
</constant>
281 <entry align=
"center">
284 <entry align=
"center">
287 <entry align=
"center">
290 <entry align=
"center">
293 <entry align=
"center">
295 <entry align=
"center">
303 The red, green, blue, alpha, luminance, and/or intensity components of
304 the resulting pixels are stored in floating-point rather than integer
308 Pixel ordering is such that lower x screen coordinates correspond to
309 lower
<emphasis>i
</emphasis> filter image coordinates.
312 Note that after a convolution is performed, the resulting color
313 components are also scaled by their corresponding
314 <constant>GL_POST_CONVOLUTION_c_SCALE
</constant> parameters and biased by their
315 corresponding
<constant>GL_POST_CONVOLUTION_c_BIAS
</constant> parameters (where
316 <emphasis>c
</emphasis> takes on the values
<emphasis role=
"bold">RED
</emphasis>,
<emphasis role=
"bold">GREEN
</emphasis>,
<emphasis role=
"bold">BLUE
</emphasis>, and
317 <emphasis role=
"bold">ALPHA
</emphasis>).
318 These parameters are set by
<citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>.
321 <refsect1 id=
"notes"><title>Notes
</title>
323 <function>glCopyConvolutionFilter1D
</function> is present only if
<code>ARB_imaging
</code> is returned when
<citerefentry><refentrytitle>glGetString
</refentrytitle></citerefentry>
324 is called with an argument of
<constant>GL_EXTENSIONS
</constant>.
327 <refsect1 id=
"errors"><title>Errors
</title>
329 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not
330 <constant>GL_CONVOLUTION_1D
</constant>.
333 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the
337 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter> is less than zero or greater
338 than the maximum supported value.
339 This value may be queried with
<citerefentry><refentrytitle>glGetConvolutionParameter
</refentrytitle></citerefentry>
340 using target
<constant>GL_CONVOLUTION_1D
</constant> and name
341 <constant>GL_MAX_CONVOLUTION_WIDTH
</constant>.
344 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glCopyConvolutionFilter1D
</function> is executed
345 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
346 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
349 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
351 <citerefentry><refentrytitle>glGetConvolutionParameter
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glGetConvolutionFilter
</refentrytitle></citerefentry>
354 <refsect1 id=
"seealso"><title>See Also
</title>
356 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
357 <citerefentry><refentrytitle>glConvolutionParameter
</refentrytitle></citerefentry>,
358 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>
361 <refsect1 id=
"Copyright"><title>Copyright
</title>
363 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
364 Silicon Graphics, Inc. This document is licensed under the SGI
365 Free Software B License. For details, see
366 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.