Article

Converting From Planar Formats

Overview

These conversion routines convert planar 8-bit buffers to packed (interleaved) 4-channel floating point format.

The meaning of maxFloat and minFloat here is substantially the same as for the vImageConvert_Planar8toPlanarF function. The difference is that since this is a four-channel image, we use four-channel min and max values so that different mins and maxes can be used for each channel. The channels in minFloat and maxFloat are in the same order as the output pixels. If the maxFloat parameter is less than the minFloat parameter, the image will come out looking like a photographic negative.

(That is, you get a free contrast + brightness adjustment as part of this conversion.)

The vImageConvert_Planar8ToARGBFFFF function is the workhorse of this family. The other three are provided as a convenience. You can actually substitute any of the channels with a constant by replacing the vImage_Buffer passed in for that channel with one from another color channel, and set maxFloat.color = minFloat.color = desired color for that channel. (In the particular case where you want all four-channels to be constant, call vImageBufferFill_ARGBFFFF(_:_:_:) instead.)

Likewise, although these API names appear to correspond to particular color channel orders, vImage has no way of knowing what is actually red or green or cyan, so you can use them for other color spaces and other packing orders. Thus, vImageConvert_Planar8ToARGBFFFF should be properly considered a somewhat colorspace-agnostic <=4-planar 8-bit channel to 4-channel packed-float conversion function.

Performance data on Intel Core2 and G5 suggest that like most simple conversion functions, these functions only perform well if the data is already in the cache.

Optimum tile sizes are between ~200 pixels and somewhere in the 50,000 to 200,000 pixel range, depending on cache size. If the image is larger than that, this function is limited by the throughput of the machine's front side bus and will run anywhere from 3 to 10 times slower. For well sized images / times, we observe that the vector code is 3-12x faster than scalar code. For images that don't fit in cache or that are not in cache, the vector code is perhaps only 10% faster than scalar.

Flag

Description

kvImageGetTempBufferSize

Returns 0. Does no work.

kvImageDoNotTile

Disables internal multithreading, if any.

Other flags

Other flags cause the function to return kvImageUnknownFlagsBit.

See Also

Converting from Planar Formats

func vImageConvert_FTo16S(UnsafePointer<vImage_Buffer>, UnsafePointer<vImage_Buffer>, Float, Float, vImage_Flags) -> vImage_Error

Converts a PlanarF image into a special format in which each pixel is a 16-bit signed integer.

func vImageConvert_FTo16U(UnsafePointer<vImage_Buffer>, UnsafePointer<vImage_Buffer>, Float, Float, vImage_Flags) -> vImage_Error

Converts a PlanarF image into a special format in which each pixel is a 16-bit unsigned integer.