HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man2 / xhtml / glConvolutionFilter2D.xml
CommitLineData
7faf1d71
AW		 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>glConvolutionFilter2D</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glConvolutionFilter2D"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glConvolutionFilter2D — define a 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">glConvolutionFilter2D</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">data</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_CONVOLUTION_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 width of the pixel array referenced by <em class="parameter"><code>data</code></em>.
48 </p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>
49 The height of the pixel array referenced by <em class="parameter"><code>data</code></em>.
50 </p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>
51 The format of the pixel data in <em class="parameter"><code>data</code></em>.
52 The allowable values are
53 <code class="constant">GL_RED</code>,
54 <code class="constant">GL_GREEN</code>,
55 <code class="constant">GL_BLUE</code>,
56 <code class="constant">GL_ALPHA</code>,
57 <code class="constant">GL_RGB</code>,
58 <code class="constant">GL_BGR</code>,
59 <code class="constant">GL_RGBA</code>,
60 <code class="constant">GL_BGRA</code>,
61 <code class="constant">GL_LUMINANCE</code>, and
62 <code class="constant">GL_LUMINANCE_ALPHA</code>.
63 </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
64 The type of the pixel data in <em class="parameter"><code>data</code></em>.
65 Symbolic constants
66 <code class="constant">GL_UNSIGNED_BYTE</code>,
67 <code class="constant">GL_BYTE</code>,
68 <code class="constant">GL_BITMAP</code>,
69 <code class="constant">GL_UNSIGNED_SHORT</code>,
70 <code class="constant">GL_SHORT</code>,
71 <code class="constant">GL_UNSIGNED_INT</code>,
72 <code class="constant">GL_INT</code>,
73 <code class="constant">GL_FLOAT</code>,
74 <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
75 <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
76 <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>,
77 <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>,
78 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
79 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
80 <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
81 <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
82 <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
83 <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
84 <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, and
85 <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
86 are accepted.
87 </p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>
88 Pointer to a two-dimensional array of pixel data that is processed to
89 build the convolution filter kernel.
90 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
91 <code class="function">glConvolutionFilter2D</code> builds a two-dimensional convolution filter kernel from an array of
92 pixels.
93 </p><p>
94 The pixel array specified by <em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>, <em class="parameter"><code>format</code></em>, <em class="parameter"><code>type</code></em>, and
95 <em class="parameter"><code>data</code></em> is extracted from memory and processed just as if
96 <a class="citerefentry" href="glDrawPixels.xml"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a> were called, but processing stops after the final
97 expansion to RGBA is completed.
98 </p><p>
99 If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target
100 (see <a class="citerefentry" href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a convolution filter is
101 specified, <em class="parameter"><code>data</code></em> is treated as a byte offset into the buffer object's data store.
102 </p><p>
103 The R, G, B, and A components of each pixel are next scaled by the four
104 2D <code class="constant">GL_CONVOLUTION_FILTER_SCALE</code> parameters and biased by the
105 four 2D <code class="constant">GL_CONVOLUTION_FILTER_BIAS</code> parameters.
106 (The scale and bias parameters are set by <a class="citerefentry" href="glConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glConvolutionParameter</span></span></a>
107 using the <code class="constant">GL_CONVOLUTION_2D</code> target and the names
108 <code class="constant">GL_CONVOLUTION_FILTER_SCALE</code> and <code class="constant">GL_CONVOLUTION_FILTER_BIAS</code>.
109 The parameters themselves are vectors of four values that are applied to red,
110 green, blue, and alpha, in that order.)
111 The R, G, B, and A values are not clamped to [0,1] at any time during this
112 process.
113 </p><p>
114 Each pixel is then converted to the internal format specified by
115 <em class="parameter"><code>internalformat</code></em>.
116 This conversion simply maps the component values of the pixel (R, G, B,
117 and A) to the values included in the internal format (red, green, blue,
118 alpha, luminance, and intensity). The mapping is as follows:
119 </p><p>
120 </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>
121 Internal Format
122 </strong></span></th><th align="center"><span class="bold"><strong>
123 Red
124 </strong></span></th><th align="center"><span class="bold"><strong>
125 Green
126 </strong></span></th><th align="center"><span class="bold"><strong>
127 Blue
128 </strong></span></th><th align="center"><span class="bold"><strong>
129 Alpha
130 </strong></span></th><th align="center"><span class="bold"><strong>
131 Luminance
132 </strong></span></th><th align="center"><span class="bold"><strong>
133 Intensity
134 </strong></span></th></tr></thead><tbody><tr><td align="left">
135 <code class="constant">GL_ALPHA</code>
136 </td><td align="center">
137 </td><td align="center">
138 </td><td align="center">
139 </td><td align="center">
140 A
141 </td><td align="center">
142 </td><td align="center">
143
144 </td></tr><tr><td align="left">
145 <code class="constant">GL_LUMINANCE</code>
146 </td><td align="center">
147 </td><td align="center">
148 </td><td align="center">
149 </td><td align="center">
150 </td><td align="center">
151 R
152 </td><td align="center">
153
154 </td></tr><tr><td align="left">
155 <code class="constant">GL_LUMINANCE_ALPHA</code>
156 </td><td align="center">
157 </td><td align="center">
158 </td><td align="center">
159 </td><td align="center">
160 A
161 </td><td align="center">
162 R
163 </td><td align="center">
164
165 </td></tr><tr><td align="left">
166 <code class="constant">GL_INTENSITY</code>
167 </td><td align="center">
168 </td><td align="center">
169 </td><td align="center">
170 </td><td align="center">
171 </td><td align="center">
172 </td><td align="center">
173 R
174 </td></tr><tr><td align="left">
175 <code class="constant">GL_RGB</code>
176 </td><td align="center">
177 R
178 </td><td align="center">
179 G
180 </td><td align="center">
181 B
182 </td><td align="center">
183 </td><td align="center">
184 </td><td align="center">
185
186 </td></tr><tr><td align="left">
187 <code class="constant">GL_RGBA</code>
188 </td><td align="center">
189 R
190 </td><td align="center">
191 G
192 </td><td align="center">
193 B
194 </td><td align="center">
195 A
196 </td><td align="center">
197 </td><td align="center">
198
199 </td></tr></tbody></table></div><p>
200 The red, green, blue, alpha, luminance, and/or intensity components of
201 the resulting pixels are stored in floating-point rather than integer
202 format.
203 They form a two-dimensional filter kernel image indexed with coordinates
204 <span class="emphasis"><em>i</em></span> and <span class="emphasis"><em>j</em></span> such that <span class="emphasis"><em>i</em></span> starts at zero and increases from left
205 to right, and <span class="emphasis"><em>j</em></span> starts at zero and increases from bottom to top.
206 Kernel location <span class="emphasis"><em>i,j</em></span> is derived from the <span class="emphasis"><em>N</em></span>th pixel,
207 where <span class="emphasis"><em>N</em></span> is <span class="emphasis"><em>i</em></span>+<span class="emphasis"><em>j</em></span>*<em class="parameter"><code>width</code></em>.
208 </p><p>
209 Note that after a convolution is performed, the resulting color
210 components are also scaled by their corresponding
211 <code class="constant">GL_POST_CONVOLUTION_c_SCALE</code> parameters and biased by their
212 corresponding <code class="constant">GL_POST_CONVOLUTION_c_BIAS</code> parameters (where
213 <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
214 <span class="bold"><strong>ALPHA</strong></span>).
215 These parameters are set by <a class="citerefentry" href="glPixelTransfer.xml"><span class="citerefentry"><span class="refentrytitle">glPixelTransfer</span></span></a>.
216 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
217 <code class="function">glConvolutionFilter2D</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>
218 is called with an argument of <code class="constant">GL_EXTENSIONS</code>.
219 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
220 <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not
221 <code class="constant">GL_CONVOLUTION_2D</code>.
222 </p><p>
223 <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>internalformat</code></em> is not one of the
224 allowable values.
225 </p><p>
226 <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>format</code></em> is not one of the allowable
227 values.
228 </p><p>
229 <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not one of the allowable
230 values.
231 </p><p>
232 <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em> is less than zero or greater
233 than the maximum supported value.
234 This value may be queried with <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>
235 using target <code class="constant">GL_CONVOLUTION_2D</code> and name
236 <code class="constant">GL_MAX_CONVOLUTION_WIDTH</code>.
237 </p><p>
238 <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>height</code></em> is less than zero or greater
239 than the maximum supported value.
240 This value may be queried with <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>
241 using target <code class="constant">GL_CONVOLUTION_2D</code> and name
242 <code class="constant">GL_MAX_CONVOLUTION_HEIGHT</code>.
243 </p><p>
244 <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>height</code></em> is one of
245 <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
246 <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
247 <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>, or
248 <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>
249 and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_RGB</code>.
250 </p><p>
251 <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>height</code></em> is one of
252 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
253 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
254 <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
255 <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
256 <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
257 <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
258 <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, or
259 <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
260 and <em class="parameter"><code>format</code></em> is neither <code class="constant">GL_RGBA</code> nor <code class="constant">GL_BGRA</code>.
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 buffer object's data store is currently mapped.
264 </p><p>
265 <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
266 <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer
267 object such that the memory reads required would exceed the data store size.
268 </p><p>
269 <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
270 <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>data</code></em> is not evenly divisible
271 into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.
272 </p><p>
273 <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glConvolutionFilter2D</code> is executed
274 between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding
275 execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
276 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
277 <a class="citerefentry" href="glGetConvolutionParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionParameter</span></span></a>, <a class="citerefentry" href="glGetConvolutionFilter.xml"><span class="citerefentry"><span class="refentrytitle">glGetConvolutionFilter</span></span></a>
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="glSeparableFilter2D.xml"><span class="citerefentry"><span class="refentrytitle">glSeparableFilter2D</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>
Unnamed repository; edit this file 'description' to name the repository.