convolve(3G)							  convolve(3G)

NAME    [Toc]    [Back]

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

C SPECIFICATION    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

     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    [Toc]    [Back]

     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:





									Page 1






convolve(3G)							  convolve(3G)



	  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    [Toc]    [Back]

     lrectwrite,rectcopy,pixmode,pixeltransfer,pixelmap

NOTES    [Toc]    [Back]

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


									PPPPaaaaggggeeee 2222