convolve(3G)

NAME
     convolve - modify the operation of lrectwrite and rectcopy to convolve
     pixel data

C SPECIFICATION
     void convolve(long convop, long border, long xksize, long yksize, float *kernel, float bias)

PARAMETERS
     convop   the convolution mode: general, separable or off

     border   a token specifying the source for the input data border

     xksize   the size of the kernel width in pixels in the x dimension

     yksize   the size of the kernel width in pixels in the y dimension

     kernel   an array of kernel elements

     bias     a value usually between [-1.0,1.0] to be added to the result of
              the convolution.

DESCRIPTION
     RealityEngine supports a sequence of of floating point image processing
     operations.  The operations are performed in the following order: integer
     to floating point conversion, scale, bias, convolution, floating point to
     integer conversion, and finally lookup table mapping.

     The pixels are converted from integers in the range specified by
     pixmode(PM_INPUT_TYPE), to the floating point range [0.,1.] if the input
     type was unsigned or (-1.,1] if the input type was signed. The pixels are
     multiplied by a color scale and then a color bias is added.  The scale
     and bias values are specified using the pixeltransfer() function. The
     resulting pixels are convolved, if convolution has been enabled by the
     convolve() function.  The resulting pixels are converted back to integers
     where the range [0.0,1.0] maps to [0,4095] if pixeltransfer(PT_MAP_COLOR)
     is disabled or [0,lookup_table_size), if table lookup mapping is enabled.
     The result is written to the framebuffer.

     convolve specifies the parameters defining the convolution to be
     performed by lrectwrite or rectcopy.

     convop may be CV_GENERAL, CV_SEPARABLE, or CV_OFF, which is the default.
     CV_GENERAL specifies that a full 3x3, 5x5, or 7x7 convolution should be
     performed.  CV_SEPARABLE specifies that the convolution should be
     performed as two one dimensional convolutions: first a horizontal
     convolution, followed by a vertical convolution.  Separable convolutions
     can be considerably faster than general convolutions as the number of
     arithmetic operations is reduced.

     border may be:
          CV_REDUCE to specify that the input border data will be supplied by
          the programmer so that the output data will be less than that input.
          If the input data is MxN and the kernel size KxK, the output data
          will be (M - K + 1)x(N - K + 1).

     xksize and yksize may be 3, 5 or 7 and must be equal to each other.

     kernel is a xksize x yksize array of floats in row major order if convop
     is CV_GENERAL.  If the convop is CV_SEPARABLE, the kernel should be an
     array of xksize + yksize floats; first the coefficients for the
     horizontal pass, followed by the coefficients for the vertical pass.  The
     coefficients should be chosen so the output range will be between
     [0.,1.].

     If convolution is enabled, all of the features of pixmode will be ignored
     except for PM_INPUT_FORMAT, PM_OUTPUT_FORMAT, PM_INPUT_TYPE,
     PM_OUTPUT_TYPE, PM_OFFSET, and PM_STRIDE.

     If the pixel input format has multiple components, they will be convolved
     independently.

SEE ALSO
     lrectwrite,rectcopy,pixmode,pixeltransfer,pixelmap

NOTES
     convolve is supported only on RealityEngine systems with release 5.0.1 or
     greater.