Function

vImageConvolveMultiKernel_ARGB8888(_:_:_:_:_:_:_:_:_:_:_:_:)

Convolves each channel of a region of interest within an ARGB8888 source image by one of the four M x N kernels, then divides the pixel values by one of the four divisors.

Declaration

func vImageConvolveMultiKernel_ARGB8888(_ src: UnsafePointer<vImage_Buffer>, _ dest: UnsafePointer<vImage_Buffer>, _ tempBuffer: UnsafeMutableRawPointer!, _ srcOffsetToROI_X: vImagePixelCount, _ srcOffsetToROI_Y: vImagePixelCount, _ kernels: UnsafeMutablePointer<UnsafePointer<Int16>?>!, _ kernel_height: UInt32, _ kernel_width: UInt32, _ divisors: UnsafePointer<Int32>!, _ biases: UnsafePointer<Int32>!, _ backgroundColor: UnsafePointer<UInt8>!, _ flags: vImage_Flags) -> vImage_Error

Parameters

src

A pointer to a vImage buffer structure that contains data for the source image.

dest

A pointer to a vImage buffer data structure. You're responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer this structure points to contains the destination image data. When you no longer need the data buffer, you must deallocate the memory. The size (number of rows and number of columns) of the destination buffer also specifies the size of the region of interest in the source buffer.

tempBuffer

A pointer to a temporary buffer. If you pass NULL, the function allocates the buffer, then deallocates it before returning. Alternatively, you can allocate the buffer yourself, in which case you are responsible for deallocating it when you is no longer need it.

If you want to allocate the buffer yourself, see the Discussion for information on how to determine the minimum size that you must allocate.

srcOffsetToROI_X

The horizontal offset, in pixels, to the upper-left pixel of the region of interest within the source image.

srcOffsetToROI_Y

The vertical offset, in pixels, to the upper-left pixel of the region of interest within the source image.

kernels

An array of pointers to the data for four kernels. The first kernel is for the alpha channel, the second for red, the third for green, and the fourth for blue. The data for each kernel is a packed array of integer values.

kernel_height

The height of the kernel in pixels. This value must be odd.

kernel_width

The width of the kernel in pixels. This value must be odd.

divisors

An array of values, for normalization purposes, to divide into the convolution results. Supply one value for each channel.

biases

An array of four values to be added to each element of the convolution result for one channel, before clipping. The first value is for the alpha channel, the second for red, the third for green, and the fourth for blue

backgroundColor

A background color. If you supply a color, you must also set the kvImageBackgroundColorFill flag, otherwise the function ignores the color.

flags

The options to use when performing the convolution operation. You must set exactly one of the following flags to specify how vImage handles pixel locations beyond the edge of the source image: kvImageCopyInPlace, kvImageTruncateKernel, kvImageBackgroundColorFill, or kvImageEdgeExtend.

Set the kvImageDoNotTile flag if you plan to perform your own tiling or use multithreading.

Return Value

kvImageNoError; otherwise, one of the error codes described in Data Types and Constants.

Discussion

If you want to allocate the memory for the tempBuffer parameter yourself, call this function twice, as follows:

  1. To determine the minimum size for the temporary buffer, the first time you call this function pass the kvImageGetTempBufferSize flag. Pass the same values for all other parameters that you intend to use in for the second call. The function returns the required minimum size, which should be a positive value. (A negative returned value indicates an error.) The kvImageGetTempBufferSize flag prevents the function from performing any processing other than to determine the minimum buffer size.

  2. After you allocate enough space for a buffer of the returned size, call the function a second time, passing a valid pointer in the tempBuffer parameter. This time, do not pass the kvImageGetTempBufferSize flag.