glSeparableFilter2D(3gl)

1GLSEPARABLEFILTER2D(3G)                                GLSEPARABLEFILTER2D(3G)
2
3
4

NAME

6       glSeparableFilter2D  -  define  a separable two-dimensional convolution
7       filter
8
9

C SPECIFICATION

11       void glSeparableFilter2D( GLenum target,
12                                 GLenum internalformat,
13                                 GLsizei width,
14                                 GLsizei height,
15                                 GLenum format,
16                                 GLenum type,
17                                 const GLvoid *row,
18                                 const GLvoid *column )
19
20

PARAMETERS

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

DESCRIPTION

71       glSeparableFilter2D builds a two-dimensional separable convolution fil‐
72       ter kernel from two arrays of pixels.
73
74       The  pixel  arrays specified by (width, format, type, row) and (height,
75       format, type, column) are processed just as if they had been passed  to
76       glDrawPixels, but processing stops after the final expansion to RGBA is
77       completed.
78
79       Next, the R, G, B, and A components of all pixels in  both  arrays  are
80       scaled  by the four separable 2D GL_CONVOLUTION_FILTER_SCALE parameters
81       and biased by the four separable 2D GL_CONVOLUTION_FILTER_BIAS  parame‐
82       ters.  (The scale and bias parameters are set by glConvolutionParameter
83       using     the     GL_SEPARABLE_2D     target     and     the      names
84       GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS.  The param‐
85       eters themselves are vectors of four values that are  applied  to  red,
86       green,  blue, and alpha, in that order.)  The R, G, B, and A values are
87       not clamped to [0,1] at any time during this process.
88
89       Each pixel is then converted to the internal  specified by internalfor‐
90       mat.  This conversion simply maps the component values of the pixel (R,
91       G, B, and A) to the values included in the internal  (red, green, blue,
92       alpha, luminance, and intensity).  The mapping is as follows:
93
94       ────────────────────────────────────────────────────────────────────────
95       Internal Format      Red   Green   Blue   Alpha   Luminance   Intensity
96       ────────────────────────────────────────────────────────────────────────
97       GL_LUMINANCE                                          R
98       GL_LUMINANCE_ALPHA                          A         R
99       GL_INTENSITY                                                      R
100       GL_RGB                R      G      B
101       GL_RGBA               R      G      B       A
102       ────────────────────────────────────────────────────────────────────────
103
104
105       The  red, green, blue, alpha, luminance, and/or intensity components of
106       the resulting pixels are stored in floating-point rather  than  integer
107       They  form  two one-dimensional filter kernel images.  The row image is
108       indexed by coordinate i starting at zero and increasing  from  left  to
109       right.   Each  location  in  the row image is derived from element i of
110       row.  The column image is indexed by coordinate j starting at zero  and
111       increasing  from  bottom  to top.  Each location in the column image is
112       derived from element j of column.
113
114       Note that after a convolution is performed, the resulting color  compo‐
115       nents      are      also      scaled     by     their     corresponding
116       GL_POST_CONVOLUTION_c_SCALE parameters and biased by their  correspond‐
117       ing  GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values
118       RED,  GREEN,  BLUE,  and  ALPHA).   These   parameters   are   set   by
119       glPixelTransfer.
120

NOTES

122       glSeparableFilter2D  is present only if GL_ARB_imaging is returned when
123       glGetString is called with an argument of GL_EXTENSIONS.
124

ERRORS

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

ASSOCIATED GETS

164       glGetConvolutionParameter, glGetSeparableFilter
165