GLCOPYCONVOLUTIONFILTER2D(3G)                    GLCOPYCONVOLUTIONFILTER2D(3G)



NAME
       glCopyConvolutionFilter2D - copy pixels into a two-dimensional convolu-
       tion filter


C SPECIFICATION
       void glCopyConvolutionFilter2D( GLenum target,
                                       GLenum internalformat,
                                       GLint x,
                                       GLint y,
                                       GLsizei width,
                                       GLsizei height )


PARAMETERS
       target          Must be GLCONVOLUTION2D.

       internalformat  The internal  of the convolution  filter  kernel.   The
                       allowable  values  are  GLALPHA, GLALPHA4, GLALPHA8,
                       GLALPHA12,  GLALPHA16,  GLUMINANCE,  GLUMINANCE4,
                       GLUMINANCE8,      GLUMINANCE12,     GLUMINANCE16,
                       GLUMINANCEALPHA,               GLUMINANCE4ALPHA4,
                       GLUMINANCE6ALPHA2,             GLUMINANCE8ALPHA8,
                       GLUMINANCE12ALPHA4,          GLUMINANCE12ALPHA12,
                       GLUMINANCE16ALPHA16,   GLINTENSITY,  GLINTENSITY4,
                       GLINTENSITY8,     GLINTENSITY12,      GLINTENSITY16,
                       GLR3G3B2,   GLRGB,   GLRGB4,   GLRGB5,   GLRGB8,
                       GLRGB100,  GLRGB12,   GLRGB16,   GLRGBA,   GLRGBA2,
                       GLRGBA4, GLRGB5A1, GLRGBA8, GLRGB100A2, GLRGBA12,
                       or GLRGBA16.

       x, y            The window space coordinates of the lower-left  coordi-
                       nate of the pixel array to copy.

       width           The width of the pixel array to copy.

       height          The height of the pixel array to copy.

DESCRIPTION
       glCopyConvolutionFilter2D  defines a two-dimensional convolution filter
       kernel with pixels from the current GLREADBUFER  (rather  than  from
       main memory, as is the case for glConvolutionFilter2D).

       The  screen-aligned  pixel  rectangle with lower-left corner at (x, y),
       width width and height height is used to define the convolution filter.
       If any pixels within this region are outside the window that is associ-
       ated with the GL context, the values  obtained  for  those  pixels  are
       undefined.

       The  pixels  in  the rectangle are processed exactly as if glReadPixels
       had been called with format set to RGBA, but  the  process  stops  just
       before  final  conversion.  The R, G, B, and A components of each pixel
       are next scaled by the four 2D  GLCONVOLUTIONFILTERSCALE  parameters
       and  biased by the four 2D GLCONVOLUTIONFILTERBIAS parameters.  (The
       scale and bias parameters are set by glConvolutionParameter  using  the
       GLCONVOLUTION2D  target and the names GLCONVOLUTIONFILTERSCALE and
       GLCONVOLUTIONFILTERBIAS.  The parameters themselves are  vectors  of
       four  values  that  are applied to red, green, blue, and alpha, in that
       order.)  The R, G, B, and A values are not clamped to [0,1] at any time
       during this process.

       Each pixel is then converted to the internal  specified by internalfor-
       mat.  This conversion simply maps the component values of the pixel (R,
       G, B, and A) to the values included in the internal  (red, green, blue,
       alpha, luminance, and intensity).  The mapping is as follows:


        Internal Format     Channel mapping
        GLALPHA            A=Alpha
        GLUMINANCE        R=Luminance
        GLUMINANCEALPHA  A=Alpha, R=Luminance
        GLINTENSITY        R=Intensity
        GLRGB              R=Red, G=Green, B=Blue
        GLRGBA             R=Red, G=Green, B=Blue, A=Alpha


       The red, green, blue, alpha, luminance, and/or intensity components  of
       the resulting pixels are stored in floating-point rather than integer

       Pixel  ordering  is  such that lower x screen coordinates correspond to
       lower i filter image coordinates, and lower y screen coordinates corre-
       spond to lower j filter image coordinates.

       Note  that after a convolution is performed, the resulting color compo-
       nents     are     also     scaled      by      their      corresponding
       GLPOSTCONVOLUTIONcSCALE  parameters and biased by their correspond-
       ing GLPOSTCONVOLUTIONcBIAS parameters (where c takes on the  values
       RED,   GREN,   BLUE,   and   ALPHA).   These  parameters  are  set  by
       glPixelTransfer.

NOTES
       glCopyConvolutionFilter2D is present only if GLARBimaging is returned
       when glGetString is called with an argument of GLEXTENSIONS.

ERORS
       GLINVALIDENUM is generated if target is not GLCONVOLUTION2D.

       GLINVALIDENUM is generated if internalformat is not one of the allow-
       able values.

       GLINVALIDVALUE is generated if width is less  than  zero  or  greater
       than  the  maximum  supported  value.   This  value may be queried with
       glGetConvolutionParameter  using  target  GLCONVOLUTION2D  and   name
       GLMAXCONVOLUTIONWIDTH.

       GLINVALIDVALUE  is  generated  if height is less than zero or greater
       than the maximum supported value.   This  value  may  be  queried  with
       glGetConvolutionParameter   using  target  GLCONVOLUTION2D  and  name
       GLMAXCONVOLUTIONHEIGHT.

       GLINVALIDOPERATION is generated if glCopyConvolutionFilter2D is  exe-
       cuted  between the execution of glBegin and the corresponding execution
       of glEnd.

ASOCIATED GETS
       glGetConvolutionParameter, glGetConvolutionFilter

SEE ALSO
       glConvolutionFilter2D, glConvolutionParameter, glPixelTransfer



                                                 GLCOPYCONVOLUTIONFILTER2D(3G)