glConvolutionFilter2D(3gl)

1GLCONVOLUTIONFILTER2D(3G)                            GLCONVOLUTIONFILTER2D(3G)
2
3
4

NAME

6       glConvolutionFilter2D - define a two-dimensional convolution filter
7
8

C SPECIFICATION

10       void glConvolutionFilter2D( GLenum target,
11                                   GLenum internalformat,
12                                   GLsizei width,
13                                   GLsizei height,
14                                   GLenum format,
15                                   GLenum type,
16                                   const GLvoid *image )
17
18

PARAMETERS

20       target          Must be GL_CONVOLUTION_2D.
21
22       internalformat  The  internal   of  the convolution filter kernel.  The
23                       allowable values are  GL_ALPHA,  GL_ALPHA4,  GL_ALPHA8,
24                       GL_ALPHA12,  GL_ALPHA16,  GL_LUMINANCE,  GL_LUMINANCE4,
25                       GL_LUMINANCE8,     GL_LUMINANCE12,      GL_LUMINANCE16,
26                       GL_LUMINANCE_ALPHA,               GL_LUMINANCE4_ALPHA4,
27                       GL_LUMINANCE6_ALPHA2,             GL_LUMINANCE8_ALPHA8,
28                       GL_LUMINANCE12_ALPHA4,          GL_LUMINANCE12_ALPHA12,
29                       GL_LUMINANCE16_ALPHA16,  GL_INTENSITY,   GL_INTENSITY4,
30                       GL_INTENSITY8,      GL_INTENSITY12,     GL_INTENSITY16,
31                       GL_R3_G3_B2,   GL_RGB,   GL_RGB4,   GL_RGB5,   GL_RGB8,
32                       GL_RGB10,   GL_RGB12,   GL_RGB16,   GL_RGBA,  GL_RGBA2,
33                       GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12,
34                       or GL_RGBA16.
35
36       width           The width of the pixel array referenced by image.
37
38       height          The height of the pixel array referenced by image.
39
40       format          The   of the pixel data in image.  The allowable values
41                       are  GL_RED,  GL_GREEN,  GL_BLUE,   GL_ALPHA,   GL_RGB,
42                       GL_BGR,    GL_RGBA,    GL_BGRA,    GL_LUMINANCE,    and
43                       GL_LUMINANCE_ALPHA.
44
45       type            The type of the pixel data  in  image.   Symbolic  con‐
46                       stants     GL_UNSIGNED_BYTE,     GL_BYTE,    GL_BITMAP,
47                       GL_UNSIGNED_SHORT, GL_SHORT,  GL_UNSIGNED_INT,  GL_INT,
48                       GL_FLOAT,                       GL_UNSIGNED_BYTE_3_3_2,
49                       GL_UNSIGNED_BYTE_2_3_3_REV,    GL_UNSIGNED_SHORT_5_6_5,
50                       GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
51                       GL_UNSIGNED_SHORT_4_4_4_4_REV,
52                       GL_UNSIGNED_SHORT_5_5_5_1,
53                       GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
54                       GL_UNSIGNED_INT_8_8_8_8_REV,
55                       GL_UNSIGNED_INT_10_10_10_2,                         and
56                       GL_UNSIGNED_INT_2_10_10_10_REV are accepted.
57
58       image           Pointer  to  a two-dimensional array of pixel data that
59                       is processed to build the convolution filter kernel.
60

DESCRIPTION

62       glConvolutionFilter2D builds a two-dimensional convolution filter  ker‐
63       nel from an array of pixels.
64
65       The  pixel array specified by width, height, format, type, and image is
66       extracted from memory  and  processed  just  as  if  glDrawPixels  were
67       called,  but processing stops after the final expansion to RGBA is com‐
68       pleted.
69
70       The R, G, B, and A components of each pixel are next scaled by the four
71       2D  GL_CONVOLUTION_FILTER_SCALE  parameters  and  biased by the four 2D
72       GL_CONVOLUTION_FILTER_BIAS parameters.  (The scale and bias  parameters
73       are  set  by  glConvolutionParameter using the GL_CONVOLUTION_2D target
74       and       the       names        GL_CONVOLUTION_FILTER_SCALE        and
75       GL_CONVOLUTION_FILTER_BIAS.   The  parameters themselves are vectors of
76       four values that are applied to red, green, blue, and  alpha,  in  that
77       order.)  The R, G, B, and A values are not clamped to [0,1] at any time
78       during this process.
79
80       Each pixel is then converted to the internal  specified by internalfor‐
81       mat.  This conversion simply maps the component values of the pixel (R,
82       G, B, and A) to the values included in the internal  (red, green, blue,
83       alpha, luminance, and intensity).  The mapping is as follows:
84
85
86       ────────────────────────────────────────────────────────────────────────
87       Internal Format      Red   Green   Blue   Alpha   Luminance   Intensity
88       ────────────────────────────────────────────────────────────────────────
89       GL_ALPHA                                    A
90       GL_LUMINANCE                                R
91       GL_LUMINANCE_ALPHA                  A       R
92       GL_INTENSITY                                                      R
93       GL_RGB                R      G      B
94       GL_RGBA               R      G      B       A
95       ────────────────────────────────────────────────────────────────────────
96
97       The  red, green, blue, alpha, luminance, and/or intensity components of
98       the resulting pixels are stored in floating-point rather  than  integer
99       They  form  a  two-dimensional filter kernel image indexed with coordi‐
100       nates i and j such that i starts at zero and  increases  from  left  to
101       right,  and  j starts at zero and increases from bottom to top.  Kernel
102       location i,j is derived from the Nth pixel, where N is i+j*width.
103
104       Note that after a convolution is performed, the resulting color  compo‐
105       nents      are      also      scaled     by     their     corresponding
106       GL_POST_CONVOLUTION_c_SCALE parameters and biased by their  correspond‐
107       ing  GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values
108       RED,  GREEN,  BLUE,  and  ALPHA).   These   parameters   are   set   by
109       glPixelTransfer.
110

NOTES

112       glConvolutionFilter2D  is  present  only  if GL_ARB_imaging is returned
113       when glGetString is called with an argument of GL_EXTENSIONS.
114

ERRORS

116       GL_INVALID_ENUM is generated if target is not GL_CONVOLUTION_2D.
117
118       GL_INVALID_ENUM is generated if internalformat is not one of the allow‐
119       able values.
120
121       GL_INVALID_VALUE  is  generated  if  width is less than zero or greater
122       than the maximum supported value.   This  value  may  be  queried  with
123       glGetConvolutionParameter   using  target  GL_CONVOLUTION_2D  and  name
124       GL_MAX_CONVOLUTION_WIDTH.
125
126       GL_INVALID_VALUE is generated if height is less than  zero  or  greater
127       than  the  maximum  supported  value.   This  value may be queried with
128       glGetConvolutionParameter  using  target  GL_CONVOLUTION_2D  and   name
129       GL_MAX_CONVOLUTION_HEIGHT.
130
131       GL_INVALID_ENUM is generated if format is not one of the allowable val‐
132       ues.
133
134       GL_INVALID_ENUM is generated if type is not one of the  allowable  val‐
135       ues.
136
137       GL_INVALID_OPERATION  is generated if glConvolutionFilter2D is executed
138       between the execution of glBegin and  the  corresponding  execution  of
139       glEnd.
140
141       GL_INVALID_OPERATION    is    generated    if    height   is   one   of
142       GL_UNSIGNED_BYTE_3_3_2,                     GL_UNSIGNED_BYTE_2_3_3_REV,
143       GL_UNSIGNED_SHORT_5_6_5,  or  GL_UNSIGNED_SHORT_5_6_5_REV and format is
144       not GL_RGB.
145
146       GL_INVALID_OPERATION   is   generated   if    height    is    one    of
147       GL_UNSIGNED_SHORT_4_4_4_4,               GL_UNSIGNED_SHORT_4_4_4_4_REV,
148       GL_UNSIGNED_SHORT_5_5_5_1,               GL_UNSIGNED_SHORT_1_5_5_5_REV,
149       GL_UNSIGNED_INT_8_8_8_8,                   GL_UNSIGNED_INT_8_8_8_8_REV,
150       GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and  for‐
151       mat is neither GL_RGBA nor GL_BGRA.
152

ASSOCIATED GETS

154       glGetConvolutionParameter, glGetConvolutionFilter
155