New Types

A new type is added to aggregate several Core Graphics types typically used to describe image formats:

vImage_CGImageFormat

typedef struct {

uint32_t bitsPerComponent;

uint32_t bitsPerPixel;

CGColorSpaceRef colorSpace;

CGBitmapInfo bitmapInfo;

uint32_t version;

const CGFloat *decode;

CGColorRenderingIntent renderingIntent;

}vImage_CGImageFormat;

The meaning of these fields is the same as in CGImageCreate.

New Functions:

The following APIs are provided to streamline interoperability with Core Graphics, to provide for facile import and export of vImage data into formats such as PNG and JPEG, and to draw to the screen.

• vImageBuffer_init

  A method to streamline allocating vImage_Buffer.data with an optimally sized rowBytes value for image performance.

• vImageBuffer_initWithCGImage

  Initialize a vImage_Buffer struct with data from a CGImageRef.

• vImageCreateCGImageFromBuffer

  Create a CGImageRef from a vImage_Buffer.

• vImageBuffer_GetSize

  Convenience function to return size of vImage_Buffer as CGSize. Will not round up.

• vImageCGImageFormat_GetComponentCount

  Convenience function to return the number of color + alpha channels in an image format.

• vImageCGImageFormat_IsEqual

  Returns true if two CG formats are equivalent -- that is, when vImageConvert_AnyToAny would just be doing a copy.

• vImageConverter_MustOperateOutOfPlace

  Returns true when the source and destination images passed to vImageConvert_AnyToAny must not overlap.

• vImageConvert_AnyToAny

  A high-performance method to convert between almost any Core Graphics pixel format. The conversions are vectorized and multithreaded. The function supports alpha, endianness, format (for example, 8-bit to half-float), decode array, colorspace and rendering intent conversions, and any combination thereof. Make all your image formats “fast-path”!

Example:

Here is an example of how to initialize a vImage_Buffer of a desired format (BGRA, 8-bit, sRGB in this case), from a file referenced by a CFURLRef. (CFURLRefs are toll-free bridged with NSURLs):

CFURLRef url = ...;

CGImageSourceRef imageSource = CGImageSourceCreateWithURL(url, NULL);

CGImageRef image = CGImageSourceCreateImageAtIndex( imageSource, 0, NULL );

vImage_Buffer result;

vImage_CGImageFormat format = {

    .bitsPerComponent = 8,

    .bitsPerPixel = 32,

    .bitmapInfo = kCGBitmapByteOrder32Little | kCGImageAlphaNoneSkipFirst,  //BGRX8888

    .colorSpace = NULL,    //sRGB

}; // .version, .renderingIntent and .decode all initialized to 0 per C rules

vImage_Error err = vImageBuffer_InitWithCGImage( &result, &format, NULL, image, kvImageNoFlags );

You may optionally elect to allocate the buffer yourself and have vImage just fill it with the correct pixels, with kvImageNoAllocate flag.

Likewise, creating a CGImageRef object from a vImage_Buffer object is relatively simple:

vImage_Buffer buf = ...;

// Declare the pixel format for the vImage_Buffer

vImage_CGImageFormat format = {

    .bitsPerComponent = 8,

    .bitsPerPixel = 32,

    .bitmapInfo = kCGBitmapByteOrderDefault | kCGImageAlphaLast,  //RGBA8888

}; // .colorspace, .version, .renderingIntent and .decode all initialized to 0 per C rules

CGImageRef image = vImageCreateCGImageFromBuffer( &buf, &format, NULL, NULL, kvImageNoFlags, &err);

Advanced options are available to allow your to directly use the vImage_Buffer object as the backing store for the new image without causing a copy. Please see the vImage_Utilities.h header comments for more. In addition vImageConvert_AnyToAny is provided to convert nearly any Core Graphics image format to nearly any other. All facets of the image format can be converted, including the colorspace. There are also a set of convenience functions for interconverting between Core Graphics and vImage coordinate spaces and determining whether two images have the same format.

New Functions

High-performance routines to rotate, shear, warp, and resize 16-bit images just like 8-bit and floating-point images. Both signed and unsigned 16-bit formats are supported.

• vImageRotate_ARGB16U / vImageRotate_ARGB16S

• vImageScale_ARGB16U / vImageScale_ARGB16S

• vImageAffineWarp_ARGB16U / vImageAffineWarp_ARGB16S

• vImageHorizontalReflect_ARGB16U / vImageHorizontalReflect_ARGB16S

• vImageVerticalReflect_ARGB16U / vImageVerticalReflect_ARGB16S

• vImageHorizontalShear_ARGB16U / vImageHorizontalShear_ARGB16S

• vImageVerticalShear_ARGB16U / vImageVerticalShear_ARGB16S

New Functions

Multidimensional lookup tables and piecewise gamma curves (power functions with a linear segment near zero) are commonly used for color conversion. We provide high-performance routines for floating-point and 16Q12 (16-bit signed fixed point with 12 fractional bits) image formats for as many as 16 color channels.

• vImageMultiDimensionalInterpolatedLookupTable_PlanarF

• vImageMultiDimensionalInterpolatedLookupTable_Planar16Q12

• vImagePiecewiseGamma_Planar8 / vImagePiecewiseGamma_Planar16Q12 / vImagePiecewiseGamma_PlanarF

• vImagePiecewiseGamma_Planar8toPlanar16Q12 / vImagePiecewiseGamma_Planar16Q12toPlanar8

• vImagePiecewiseGamma_Planar8toPlanarF / vImagePiecewiseGamma_PlanarFtoPlanar8

We've also added several 1D lookup tables:

• vImageLookupTable_Planar8toPlanar16

• vImageLookupTable_Planar8toPlanarF / vImageLookupTable_PlanarFtoPlanar8

• vImageLookupTable_8to64U

And 16-bit support for matrix multiplication, for color conversion and color twist operations on 16-bit signed data:

• vImageMatrixMultiply_Planar16S

New Functions

Many new conversions were added to support vImageConvert_AnyToAny. These are exposed for use when you already know which conversion you want and just want to call that.

• vImageConvert_ARGB16UToARGB8888 / vImageConvert_ARGB8888ToARGB16U

• vImageConvert_RGB16UToARGB8888 / vImageConvert_ARGB8888ToRGB16U

  (also do channel reordering and channel insertion)

• vImageConvert_16Uto16F / vImageConvert_16Fto16U

• vImageConvert_Planar8toPlanar16F / vImageConvert_Planar16FtoPlanar8

• vImageConvert_ARGB8888toPlanarF / vImageConvert_ARGBFFFFtoPlanar8

• vImageConvert_ARGBFFFFtoRGBFFF / vImageConvert_RGBAFFFFtoRGBFFF / vImageConvert_BGRAFFFFtoRGBFFF

• vImageConvert_RGBFFFtoARGBFFFF / vImageConvert_RGBFFFtoRGBAFFFF / vImageConvert_RGBFFFtoBGRAFFFF

• vImageConvert_RGBA8888toRGB888 / vImageConvert_BGRA8888toRGB888

• vImageConvert_RGB565toRGBA8888 / vImageConvert_RGB565toBGRA8888

• vImageConvert_XRGB8888ToPlanar8 / vImageConvert_BGRX8888ToPlanar8

• vImageConvert_XRGBFFFFToPlanarF / vImageConvert_BGRXFFFFToPlanarF

• vImageConvert_Planar16UtoARGB16U / vImageConvert_ARGB16UtoPlanar16U

• vImageConvert_Planar16UtoRGB16U / vImageConvert_RGB16UtoPlanar16U

• vImageConvert_RGB16UtoARGB16U / vImageConvert_RGB16UtoRGBA16U / vImageConvert_RGB16UtoBGRA16U

• vImageConvert_ARGB16UtoRGB16U / vImageConvert_RGBA16UtoRGB16U / vImageConvert_BGRA16UtoRGB16U

• vImageFlatten_ARGB8888 / vImageFlatten_RGBA8888

• vImageFlatten_ARGB16U / vImageFlatten_RGBA16U

• vImageFlatten_ARGB16Q12 / vImageFlatten_RGBA16Q12

• vImageFlatten_ARGBFFFF / vImageFlatten_RGBAFFFF

• vImageFlatten_ARGB8888ToRGB888 / vImageFlatten_RGBA8888ToRGB888 / vImageFlatten_BGRA8888ToRGB888

• vImageFlatten_ARGBFFFFToRGBFFF / vImageFlatten_RGBAFFFFToRGBFFF / vImageFlatten_BGRAFFFFToRGBFFF

• vImageConvert_Planar1toPlanar8 / vImageConvert_Planar2toPlanar8 / vImageConvert_Planar4toPlanar8

• vImageConvert_Indexed1toPlanar8 / vImageConvert_Indexed2toPlanar8 / vImageConvert_Indexed4toPlanar8

• vImageConvert_Planar8toPlanar1 / vImageConvert_Planar8toPlanar2 / vImageConvert_Planar8toPlanar4

• vImageConvert_Planar8toIndexed1 / vImageConvert_Planar8toIndexed2 / vImageConvert_Planar8toIndexed4

• vImageConvert_8to16Q12 / vImageConvert_RGB888toPlanar16Q12 / vImageConvert_ARGB8888toPlanar16Q12

• vImageConvert_16Q12to8 / vImageConvert_Planar16Q12toRGB888 / vImageConvert_Planar16Q12toARGB8888

• vImageConvert_16Q12toF / vImageConvert_Fto16Q12

• vImageConvert_16Q12to16U / vImageConvert_16Uto16Q12

• vImageOverwriteChannelsWithPixel_ARGB8888

• vImageByteSwap_Planar16U

New Functions

A number of new functions were added to support the 16Q12 data format. 16Q12 is a signed 16-bit fixed-point format capable of representing the range from [–8,8). It has 12 bits of fractional precision. The extra precision and range are useful for preserving signal fidelity when doing nonlinear operations on 8-bit data.

• vImagePremultipliedAlphaBlendWithPermute_ARGB8888 / vImagePremultipliedAlphaBlendWithPermute_RGBA8888

• vImagePermuteChannelsWithMaskedInsert_ARGB8888 / vImagePermuteChannelsWithMaskedInsert_ARGBFFFF

• vImagePremultiplyData_ARGB16Q12 / vImagePremultiplyData_RGBA16Q12

• vImageUnpremultiplyData_ARGB16Q12 / vImageUnpremultiplyData_RGBA16Q12

• vImageBufferFill_ARGB16U / vImageBufferFill_ARGB16S