GLCONVOLUTIONFILTEREXT(3GL)GLCONVOLUTIONFILTEREXT(3GL)NAME
glConvolutionFilter1DEXT, glConvolutionFilter2DEXT, glSeparable‐
Filter2DEXT - specify 1D, 2D and separable convolution filter images
C SPECIFICATION
void glConvolutionFilter1DEXT ( GLenum target,
GLenum internalformat,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid* image);
PARAMETERS
target The target Convolution filter. Must be GL_CONVOLU‐
TION_1D_EXT.
internalformat The internal storage format of the convolution filter.
Must be one of GL_ALPHA, GL_LUMINANCE, GL_LUMI‐
NANCE_ALPHA, GL_INTENSITY, GL_RGB, or GL_RGBA.
width Width of convolution filter image. Must be 3, 5 or 7.
format Format of pixel data in image. Symbolic constants
GL_RGBA, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
GL_LUMINANCE, GL_LUMINANCE_ALPHA and GL_ABGR_EXT are
accepted.
type Specifies the data type for pixels. Symbolic constants
GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT,GL_SHORT,
GL_UNSIGNED_INT, GL_INT and GL_FLOAT are accepted.
image Specifies a pointer to one-dimensional array of convo‐
lution filter values.
C SPECIFICATION
void glConvolutionFilter2DEXT ( GLenum target,
GLenum internalformat,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid* image)
PARAMETERS
target The target Convolution filter. Must be GL_CONVOLU‐
TION_2D_EXT.
internalformat The internal storage format of the convolution filter.
Must be one of GL_ALPHA, GL_LUMINANCE, GL_LUMI‐
NANCE_ALPHA, GL_INTENSITY_EXT, GL_RGB, or GL_RGBA.
width Width of convolution filter image. Must be 3, 5 or 7.
height Height of convolution filter image. Must be 3, 5 or 7.
format Format of pixel data in image. Symbolic constants
GL_RGBA, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
GL_LUMINANCE, GL_LUMINANCE_ALPHA and GL_ABGR_EXT are
accepted.
type Specifies the data type for pixels. Symbolic constants
GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
GL_UNSIGNED_INT, GL_INT and GL_FLOAT are accepted.
image Specifies a pointer to two-dimensional array of convo‐
lution filter values.
C SPECIFICATION
void glSeparableFilter2DEXT ( GLenum target,
GLenum internalformat,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid* row,
const GLvoid* column)
PARAMETERS
target The target Separabale convolution filter. Must be
GL_SEPARABLE_2D_EXT.
internalformat The internal storage format of the convolution filter.
Must be one of GL_ALPHA, GL_LUMINANCE, GL_LUMI‐
NANCE_ALPHA, GL_INTENSITY_EXT, GL_RGB, or GL_RGBA.
width Width of separable convolution filter image. Must be 3,
5 or 7.
height Height of separable convolution filter image. Must be
3, 5 or 7.
format Format of pixel data in image. Symbolic constants
GL_RGBA, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
GL_LUMINANCE, GL_LUMINANCE_ALPHA and GL_ABGR_EXT are
accepted.
type Specifies the data type for pixels. Symbolic constants
GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
GL_UNSIGNED_INT, GL_INT and GL_FLOAT are accepted.
row Specifies a pointer to one-dimensional array of convo‐
lution filter values.
column Specifies a pointer to one-dimensional array of convo‐
lution filter values.
DESCRIPTION
glConvolutionFilter*EXT and glSeparableFilter2DEXT are part of the
EXT_convolution extension, which defines 1 and 2 dimensional convolu‐
tion operations at a fixed location in the pixel transfer pipeline.
Enable convolutions using glEnable. Disable using glDisable. Check
whether enabled using glIsEnabled.
A 1-dimensional convolution filter image is specified using glConvolu‐
tionFilter1DEXT command. Its <target> parameter must be CONVOLU‐
TION_1D_EXT. Supported filter widths are 3, 5 and 7.
A 2-dimensional convolution filter image is specified using glConvolu‐
tionFilter2DEXT command. Its <target> parameter must be CONVOLU‐
TION_2D_EXT. Filter image height and width should be the same. Sup‐
ported sizes are 3x3, 5x5 and 7x7.
Special facilities are provided for the definition of 2-dimensional
separable filters. Filters whose image can be represented as the prod‐
uct of two 1-dimensional images, rather than as full 2-dimensional
images. A 2-dimensional convolution filter is specified using glSepa‐
rableFilter2DEXT. Filter image height and width should be the same.
Supported sizes are 3x3, 5x5 and 7x7.
The convolution image data specified by <width>, <format>, <type> and
<image | row | column> is extracted from memory and processed just as
if glDrawPixels were called, but processing stops after the final
expansion to RGBA is completed. The resulting retained image replaces
the current filter image.
The four scale parameters and the four bias parameters that are
defined for the filter image are then used to scale and bias the R,
G, B, and A components of each pixel. Use glConvolutionParame‐
ter[i|f]vEXT to set these scale and bias parameters.
Each pixel is then converted to the internal format specified by inter‐
nalformat. This conversion simply maps the component values of
the pixel (R, G, B, and A) to the values included in the internal for‐
mat (red, green, blue, alpha, luminance, and intensity). The mapping
is as follows:
----------------------------------------------------------------------
|Base Stored values |
|Internal Format Red Green Blue Alpha Luminance Intensity|
|____________________________________________________________________|
| |
|GL_ALPHA A |
|GL_LUMINANCE R |
|GL_LUMINANCE_ALPHA A R |
|GL_INTENSITY R |
|GL_RGB R G B |
|GL_RGBA R G B A |
----------------------------------------------------------------------
If CONVOLUTION_1D_EXT is enabled, the 1-dimensional convolution filter
is applied only to the image passed to glTexImage1D, and to 1-dimen‐
sional textures queried by glGetTexImage. If CONVOLUTION_2D_EXT is
enabled, the 2-dimensional convolution filter is applied only to the 2D
images passed to glDrawPixels, glCopyPixels, glReadPixels, glTexIm‐
age2D, glTexSubImage2DEXT, glCopyTexImage2DEXT, glCopyTexSubImage2DEXT,
and glGetTexImage, and to 2-dimensional images queried by glGetTexIm‐
age. If SEPARABLE_2D_EXT is enabled, and CONVOLUTION_2D_EXT is dis‐
abled, the separable 2-dimensional convolution filter is applied only
to these same images.
The convolution operation is a sum of products of source image pixels
and convolution filter pixels. Source image pixels always have four
components: red, green, blue, and alpha, denoted in the equations below
as Rs, Gs, Bs, and As. Filter pixels may be stored in one of five for‐
mats, with 1, 2, 3, or 4 components. These components are denoted as
Rf, Gf, Bf, Af, Lf, and If in the equations below. The result of the
convolution operation is the 4-tuple R,G,B,A. Depending on the inter‐
nal format of the filter, individual color components of each source
image pixel are convolved with one filter component, or are passed
unmodified. The rules for this are:
Filter format
-------------
ALPHA R = Rs G = Gs
B = Bs A = convolve(As,Af)
LUMINANCE R = convolve(Rs,Lf) G = convolve(Gs,Lf)
B = convolve(Bs,Lf) A = As
LUMINANCE_ALPHA R = convolve(Rs,Lf) G = convolve(Gs,Lf)
B = convolve(Bs,Lf) A = convolve(As,Af)
INTENSITY R = convolve(Rs,If) G = convolve(Gs,IF)
B = convolve(Bs,If) A = convolve(As,If)
RGB R = convolve(Rs,Rf) G = convolve(Gs,Gf)
B = convolve(Bs,Bf) A = As
RGBA R = convolve(Rs,Rf) G = convolve(Gs,Gf)
B = convolve(Bs,Bf) A = convolve(As,Af)
The convolution equations are:
1-dimensional filter:
C[i] = SUM{n = 0 through Wf-1}
Cs[i+n] * Cf[n]
2-dimensional filter:
C[i,j] = SUM{n = 0 through Wf-1}
{m = 0 through Hf-1}
Cs[i+n,j+m] * Cf[n,m]
2-dimensional separable filter:
C[i,j] = SUM{n = 0 through Wf-1}
{m = 0 through Hf-1}
Cs[i+n,j+m] * Crow[n] * Ccolumn[m]
where the variables Wf and Hf refer to the dimensions of the convolu‐
tion filter. Cs refers to the source image.
The convolution border mode for a specific convolution filter is speci‐
fied using glConvolutionParameteriEXT and glConvolutionParameterfEXT
with the <target> parameter set to the name of the filter, the <pname>
parameter set to CONVOLUTION_BORDER_MODE_EXT, and <param> set to one of
GL_REDUCE_EXT, GL_IGNORE_BORDER_HP, GL_CONSTANT_BORDER_HP, GL_WRAP_BOR‐
DER_SUN or GL_REPLICATE_BORDER_HP.
We define Cw = floor(Wf / 2) and Ch = floor(Hf / 2). The coordinates
(Cw, Ch) define the center of the convolution filter.
The convolution filter is moved around the source image so that its
center passes over every pixel in the source image. At each location,
the sum of products is computed and the result is written in the desti‐
nation image at the location that corresponds to the pixel location
where the convolution filter is centered.
If the convolution border mode is GL_REDUCE_EXT, the output image size
is reduced. The coordinates of the image that results are zero through
Ws-Wf in width, and zero through Hs-Hf in height, where Ws and Hs are
width and height of the source image respectively.
If the convolution border mode is GL_IGNORE_BORDER_HP, the output image
has the same dimensions as the source image. However, the sum of prod‐
ucts is not computed for any pixel where the convolution filter extends
beyond one of the edges of the source image. Instead, for these loca‐
tions, the pixel value from the source image is copied to the destina‐
tion image.
If the convolution border mode is GL_CONSTANT_BORDER_HP then convolu‐
tion does not change the size of the source image. The result of the
convolution is the same as if the source image were surrounded by pix‐
els with the same color as the current convolution border color. When‐
ever the convolution filter extends beyond one of the edges of the
source image, the constant-color border pixels are copied to the resul‐
tant image. The current convolution border color is set by calling
glConvolutionParameterivEXT or glConvolutionParameterfvEXT with <pname>
set to GL_CONVOLUTION_BORDER_COLOR_HP and <params> containing four val‐
ues that comprise the RGBA color to be used as the image border. Inte‐
ger color components are interpreted linearly such that the most posi‐
tive integer maps to 1.0, and the most negative integer maps to -1.0.
Floating point color components are clamped to the range [0,1] when
they are specified.
The convolution border mode GL_REPLICATE_BORDER_HP also produces an
output image with the same dimensions as the source image. For pixel
locations where the convolution filter extends beyond the edge of the
source image, it is as if the outermost one-pixel border of the source
image was replicated. Conceptually, each pixel in the leftmost one-
pixel column of the source image is replicated Cw times to provide
additional image data along the left edge, each pixel in the rightmost
one-pixel column is replicated Cw times to provide additional image
data along the right edge, and each pixel value in the top and bottom
one-pixel rows is replicated to create Ch rows of image data along the
top and bottom edges. The pixel value at each corner is also replicated
in order to provide data for the convolution operation at each corner
of the source image.
The convolution border mode GL_WRAP_BORDER_SUN is similar to GL_REPLI‐
CATE_BORDER_HP except that the duplicated rows come from the opposite
edge for filter values that extends beyond the edge of the source
image. Say, to convolve the left edge, Cw columns from the right edge
are used to provide additional image data along the left edge. For con‐
volving right edge, Cw columns from left edge is used. Similarly for
top and bottom edges. For corners, the diagonally opposite pixel values
provide the required image data.
If a convolution operation is performed, the resulting image is scaled
and biased by parameters specified using the glPixelTransfer command.
These operations are:
red = red * GL_POST_CONVOLUTION_RED_SCALE_EXT
+ GL_POST_CONVOLUTION_RED_BIAS_EXT
green = green * GL_POST_CONVOLUTION_GREEN_SCALE_EXT
+ GL_POST_CONVOLUTION_GREEN_BIAS_EXT
blue = blue * GL_POST_CONVOLUTION_BLUE_SCALE_EXT
+ GL_POST_CONVOLUTION_BLUE_BIAS_EXT
alpha = alpha * GL_POST_CONVOLUTION_ALPHA_SCALE_EXT
+ GL_POST_CONVOLUTION_ALPHA_BIAS_EXT
If no convolution operation is performed, the scale and bias are not
performed either.
After the Scale and Bias opeartion, the resulting image is passed
through a color table specified by glColorTableSGI with target as
GL_POST_CONVOLUTION_COLOR_TABLE_SGI. This is done only if convolution
operation is performed and this color table is enabled.
NOTES
Border modes GL_IGNORE_BORDER_HP, GL_CONSTANT_BORDER_HP, GL_REPLI‐
CATE_BORDER_HP is part of the GL_HP_convolution_border_modes extension.
GL_WRAP_BORDER_SUN is a Sun specific extension. GL_REDUCE_EXT is part
of GL_EXT_convolution extension.
For 2d convolutions and separable convolutions, the width and height of
the source image should be atleast 3 times the width and height of the
filter image. If this not the case, then, for example when glDrawPixels
is called GL_INVALID_OPERATION will be generated.
Only 3x3, 5x5 and 7x7 filters are supported for 2d convolutions and
separable convolutions. 1d convolutions support only 3x1, 5x1 and 7x1
size filters. If a different size is specified then GL_INVALID_VALUE
will be generated.
ERRORS
GL_INVALID_ENUM is generated if target is not one of the allowable
values.
GL_INVALID_ENUM is generated if internalformat is not one of the allow‐
able values.
GL_INVALID_VALUE is generated if width is less than zero and if it is
not 3, 5 or 7 for cases of convolution.
GL_INVALID_VALUE is generated if height is less than zero and if it is
not 3, 5 or 7.
GL_INVALID_VALUE is generated if width and height values differ for
GL_CONVOLUTION_2D_EXT and GL_SEPARABLE_2D_EXT.
GL_INVALID_ENUM is generated if format is not one of the allowable
values.
GL_INVALID_ENUM is generated if type is not one of the allowable
values.
GL_OUT_OF_MEMORY is generated if the image cannot be stored internally
due to memory restrictions.
ASSOCIATED GETS
glGetConvolutionFilterEXT, glGetSeparableFilterEXT.
SEE ALSO
glCopyConvolutionFilter1DEXT, glCopyConvolutionFilter2DEXT, glConvolu‐
tionParameteriEXT, glConvolutionParameterivEXT, glConvolutionParame‐
terfEXT, glConvolutionParameterfvEXT, glGetConvolutionParameterivEXT,
glGetConvolutionParameterfvEXT, glColorTableSGI, glTexImage1D, glGet‐
TexImage, glDrawPixels, glCopyPixels, glReadPixels, glTexImage2D,
glTexSubImage2DEXT, glCopyTexImage2DEXT, glCopyTexSubImage2DEXT, glGet‐
TexImage, glPixelTransferf, glPixelTransferi, glEnable, glDisable,
glIsEnabled, glPixelStore.
1 Dec 97 GLCONVOLUTIONFILTEREXT(3GL)