Next Page >

Hide TOC

vImage Conversion Reference

Framework	Accelerate/vImage
Companion guide	vImage Programming Guide
Declared in	Conversion.h

Overview

Conversion functions change an image from one image format into another. These functions work with the formats supported by vImage (Planar8, PlanarF, ARGB8888, ARGBFFFF, RGBA8888, and RGBAFFFF) but they can also change between a supported format to one that’s not supported by vImage (such as RGB565). Conversion functions can also fill buffers with a color, overwrite channels, permute channels, flatten data, and clip data.

Conversion functions use a vImage buffer structure (vImage_Buffer—see vImage Data Types and Constants Reference) to receive and supply image data. This buffer contains a pointer to image data, the height and width (in pixels) of the image data, and the number of row bytes. You actually pass a pointer to a vImage buffer structure. For some functions, you can provide a pointer to the same vImage buffer structure for the source images and the destination image because the function “works in place”. That is , the source and destination images can occupy the same memory if the they are strictly aligned pixel for pixel.

Functions by Task

Filling Buffers

Permuting Channels

Overwriting Channels

Converting From 16 Bit

Transforming Using Table Lookups

Flattening Data

Clipping Data

Converting Between Chunky and Planar

These convenience functions allow you to convert between various interleaved (or chunky) formats that vImage does not explicitly support (and that may have less than or more than four channels) and the formats that vImage supports explicitly. You can represent some non-interleaved formats as well. The functions are not fast or vectorized.

Converting From Planar Formats

Converting From ARGB Formats

Converting From RGB Formats

Functions

vImageBufferFill_ARGB8888

Fills an ARGB8888 buffer with a specified color.

vImage_Error vImageBufferFill_ARGB8888 (
   const vImage_Buffer *dest,
   const Pixel_8888 color,
   vImage_Flags flags
);

Parameters

dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data created with the fill color. When you no longer need the data buffer, you must deallocate the memory.
color: The color to fill the buffer with.
flags: 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 vImage Data Types and Constants Reference.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageBufferFill_ARGBFFFF

Fills an ARGBFFFF buffer with a specified color.

vImage_Error vImageBufferFill_ARGBFFFF (
   const vImage_Buffer *dest,
   const Pixel_FFFF color,
   vImage_Flags flags
);

Parameters

dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data created with the fill color. When you no longer need the data buffer, you must deallocate the memory.
color: The color to fill the buffer with.
flags: 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 vImage Data Types and Constants Reference.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageClip_PlanarF

Clips the pixel values of an image in PlanarF format, using the provided minimum and maximum values.

vImage_Error vImageClip_PlanarF (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   Pixel_F maxFloat,
   Pixel_F minFloat,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to clip.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.
maxFloat: A maximum pixel value. The function clips larger values to this value in the destination image.
minFloat: A maximum pixel value. The function clips smaller values to this value in the destination image.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_16SToF

Converts an image in a special planar format—in which each pixel value is a 16-bit signed integer— to a PlanarF format.

vImage_Error vImageConvert_16SToF (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   float offset,
   float scale,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image (for which each pixel value is a 16-bit signed integer) whose data you want to overwrite.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data in PlanarF format. When you no longer need the data buffer, you must deallocate the memory.
offset: The offset value to add to each pixel.
scale: The value to multiply each pixel by.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The function changes each pixel value to a floating-point value, scales each value and then adds the offset value. The calculation is

    resultPixel = (float) sourcePixel * scale + offset

The functions vImageConvert_16SToF and vImageConvert_FTo16S are inverse transformations when you use the same offset and scale values for each. (The inversion is not precise due to round-off error.) This requires the two functions to use these values differently (and in a different order).

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_16UToF

Converts an image in a special planar format—in which each pixel value is a 16-bit unsigned integer— to a PlanarF format.

vImage_Error vImageConvert_16UToF (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   float offset,
   float scale,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image (for which each pixel value is a 16-bit unsigned integer) whose data you want to overwrite.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data in PlanarF format. When you no longer need the data buffer, you must deallocate the memory.
offset: The offset value to add to each pixel.
scale: The value to multiply each pixel by.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

Each pixel value is changed to a floating-point value, then scaled and offset by the provided values. The calculation is

    resultPixel =   SATURATED_CLIP_SHRT_MIN_to_SHRT_MAX( (sourcePixel

                    - offset) / scale  + 0.5f)

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_16UToPlanar8

Converts an image in a special planar format—in which each pixel value is a 16-bit unsigned integer—to a Planar8 image.

vImage_Error vImageConvert_16UToPlanar8 (
const vImage_Buffer *src,
const vImage_Buffer *dest,
vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The conversion from 16-bit to 8-bit values is:

    uint8_t result = (srcPixel * 255 + 32767) / 65535

You can also use this function to convert a 4-channel interleaved 16U image to an ARGB8888. image. Simply multiply the width of the destination buffer by four.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGB1555toARGB8888

Converts an ARGB1555 image to an ARGB8888 image.

vImage_Error vImageConvert_ARGB1555toARGB8888 (
const vImage_Buffer *src,
const vImage_Buffer *dest,
vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the converted data. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The ARGB1555 format has 16-bit pixels with 1 bit for alpha and 5 bits each for red, green, and blue. The function calculates the 8-bit pixels in the destination image as follows:

    Pixel8 alpha =  1bitAlphaChannel * 255

    Pixel8 red   = (5bitRedChannel   * 255 + 15) / 31

    Pixel8 green = (5bitGreenChannel * 255 + 15) / 31

    Pixel8 blue  = (5bitBlueChannel  * 255 + 15) / 31

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGB1555toPlanar8

Separates an ARGB1555 image into four Planar8 images.

vImage_Error vImageConvert_ARGB1555toPlanar8 (
   const vImage_Buffer *src,
   const vImage_Buffer *destA,
   const vImage_Buffer *destR,
   const vImage_Buffer *destG,
   const vImage_Buffer *destB,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to separate.
destA: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the alpha channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destR: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the red channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destG: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the green channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destB: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the blue channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The ARGB1555 format has 16-bit pixels with 1 bit for alpha and 5 bits each for red, green, and blue. The function calculates the 8-bit pixels in the destination image as follows:

    Pixel8 alpha =  1bitAlphaChannel * 255

    Pixel8 red   = (5bitRedChannel   * 255 + 15) / 31

    Pixel8 green = (5bitGreenChannel * 255 + 15) / 31

    Pixel8 blue  = (5bitBlueChannel  * 255 + 15) / 31

This function works in place for one destination buffer; the others must be allocated separately.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGB8888toARGB1555

Converts an ARGB8888 image into an ARGB1555 image.

vImage_Error vImageConvert_ARGB8888toARGB1555 (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the converted image data. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The ARGB1555 format has 16-bit pixels with 1 bit for alpha and 5 bits each for red, green, and blue. The function calculates the 16-bit pixels in the destination image as follows:

    uint32_t alpha = (8bitAlphaChannel      + 127) / 255

    uint32_t red   = (8bitRedChannel   * 31 + 127) / 255

    uint32_t green = (8bitGreenChannel * 31 + 127) / 255

    uint32_t blue  = (8bitBlueChannel  * 31 + 127) / 255

    uint16_t ARGB1555pixel = (alpha << 15) | (red <<  10) | (green << 5) | blue

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGB8888toPlanar8

Separates an ARGB8888 image into four Planar8 images.

vImage_Error vImageConvert_ARGB8888toPlanar8 (
   const vImage_Buffer *srcARGB,
   const vImage_Buffer *destA,
   const vImage_Buffer *destR,
   const vImage_Buffer *destG,
   const vImage_Buffer *destB,
   vImage_Flags flags
);

Parameters

srcARGB: A pointer to a vImage buffer structure that contains the source image whose data you want to separate.
destA: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the alpha channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destR: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the red channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destG: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the green channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destB: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a Planar8 image equivalent to the blue channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The source image, and the destA, destR, destG, and destB destination buffers, must have the same height and the same width. This function works in place for one destination buffer. The others must be allocated separately.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_ARGB8888toRGB565

Converts an ARGB8888 image into an RGB565 image.

vImage_Error vImageConvert_ARGB8888toRGB565 (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the data in RGB565 format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The alpha channel in the ARGB8888 image is ignored. (The RGB565 format has 16-bit pixels with 5 bits for red, 6 for green, and 5 for blue.) The function calculates the pixels in the destination image as follows:

    uint32_t red   = (8bitRedChannel   * (31*2) + 255) / (255*2)

    uint32_t green = (8bitGreenChannel * 63 + 127) / 255

    uint32_t blue  = (8bitBlueChannel  * 31 + 127) / 255

    uint16_t RGB565pixel =  (red << 11) | (green <<  5) | blue

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGB8888toRGB888

Converts an ARGB8888 image into an RGB888 image.

vImage_Error vImageConvert_ARGB8888toRGB888 (
   const vImage_Buffer *argbSrc,
   const vImage_Buffer *rgbDest,
   vImage_Flags flags
);

Parameters

argbSrc: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
rgbDest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the argbSrc data buffer. On return, the data buffer pointed to by this structure contains the data in RGB888 format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The red, green, and blue channels are simply copied.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_ARGBFFFFtoPlanarF

Separates an ARGBFFFF image into four PlanarF images.

vImage_Error vImageConvert_ARGBFFFFtoPlanarF (
   const vImage_Buffer *srcARGB,
   const vImage_Buffer *destA,
   const vImage_Buffer *destR,
   const vImage_Buffer *destG,
   const vImage_Buffer *destB,
   vImage_Flags flags
);

Parameters

srcARGB: A pointer to a vImage buffer structure that contains the source image whose data you want to separate.
destA: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a PlanarF image equivalent to the alpha channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destR: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a PlanarF image equivalent to the red channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destG: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a PlanarF image equivalent to the green channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
destB: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains data for a PlanarF image equivalent to the blue channel of the source image. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_ChunkyToPlanar8

Separates a source image into a collection of corresponding planar destination images, one for each 8-bit channel of the original image.

vImage_Error vImageConvert_ChunkyToPlanar8 (
   const void *srcChannels[],
   const vImage_Buffer *destPlanarBuffers[],
   unsigned int channelCount,
   size_t srcStrideBytes,
   vImagePixelCount srcWidth,
   vImagePixelCount srcHeight,
   size_t srcRowBytes,
   vImage_Flags flags
);

Parameters

srcChannels: An array of pointers to channels of the source image. Each pointer points to the start of the data for one source channel.
destPlanarBuffers: An array of vImage buffer structures, each of which contains image data in Planar8 format. Each structure must have the same width and height values, but may have different row byte values. On return, the data buffer in each vImage buffer structure contains a planar image equivalent to the corresponding channel of the source image.
channelCount: The number of channels in the source image.
srcStrideBytes: The number of bytes from one pixel value in a given channel to the next pixel of that channel (within a row). This value must be the same for all channels.
srcWidth: The number of pixels in a row. This value must be the same for all channels in the source image, and for all the destination buffers.
srcHeight: The number of rows. This value must be the same for all channels in the source image, and for all the destination buffers.
srcRowBytes: The number of bytes from the beginning of a channel row to the beginning of the next row of the channel. This value must be the same for all channels of the source image. (It does not have the be the same as the rowBytes values of the destination buffers. Each destination buffer can have its own rowBytes value.)
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_ChunkyToPlanarF

Separates a source image into a collection of corresponding planar destination images, one for each floating-point channel of the original image.

vImage_Error vImageConvert_ChunkyToPlanarF (
   const void *srcChannels[],
   const vImage_Buffer *destPlanarBuffers[],
   unsigned int channelCount,
   size_t srcStrideBytes,
   vImagePixelCount srcWidth,
   vImagePixelCount srcHeight,
   size_t srcRowBytes,
   vImage_Flags flags
);

Parameters

srcChannels: An array of pointers to channels of the source image. Each pointer points to the start of the data for one source channel.
destPlanarBuffers: An array of vImage buffer structures, each of which contains image data in PlanarF format. Each structure must have the same width and height values, but may have different row byte values. On return, the data buffer in each each vImage buffer structure contains a planar image equivalent to the corresponding channel of the source image.
channelCount: The number of channels in the source image.
srcStrideBytes: The number of bytes from one pixel value in a given channel to the next pixel of that channel (within a row). This value must be the same for all channels.
srcWidth: The number of pixels in a row. This value must be the same for all channels in the source image, and for all the destination buffers.
srcHeight: The number of rows. This value must be the same for all channels in the source image, and for all the destination buffers.
srcRowBytes: The number of bytes from the beginning of a channel row to the beginning of the next row of the channel. This value must be the same for all channels of the source image. (It does not have the be the same as the rowBytes values of the destination buffers. Each destination buffer can have its own rowBytes value.)
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_FTo16S

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

vImage_Error vImageConvert_FTo16S (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   float offset,
   float scale,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image converted to 16-bit signed integer format. When you no longer need the data buffer, you must deallocate the memory.
offset: The offset value to subtract from every pixel.
scale: The scale value to divide each pixel by.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

Each pixel value is first offset and scaled by the provided values, and then changed to a 16-bit signed integer (rounded and clipped as necessary). The calculation is as follows:

    resultPixel =   SATURATED_CLIP_0_to_USHRT_MAX( (srcPixel - offset)

                    / scale  + 0.5f)

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_FTo16U

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

vImage_Error vImageConvert_FTo16U (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   float offset,
   float scale,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image converted to 16-bit unsigned integer format. When you no longer need the data buffer, you must deallocate the memory.
offset: The offset value to subtract from every pixel.
scale: The scale value to divide each pixel by.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

Each pixel value is first offset and scaled by user-supplied values, and then changed to a 16-bit unsigned integer (rounded and clipped as necessary). The calculation is as follows:

    resultPixel =   SATURATED_CLIP_0_to_USHRT_MAX( (sourcePixel  - offset)

                    / scale  + 0.5f)

The functions vImageConvert_16UToF and vImageConvert_FTo16U are inverse transformations when you use the same offset and scale values for each. (The inversion is not precise due to round-off error.) This requires the two functions to use these values differently (and in a different order).

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_Planar16FtoPlanarF

Converts a Planar16F image to a PlanarF image.

vImage_Error vImageConvert_Planar16FtoPlanarF (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image converted to PlanarF format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The Planar16F format is identical to the OpenEXR format; it uses 16-bit floating-point numbers. In conformance with IEEE-754, the function quiets signaling NaNs during the conversion. (OpenEXR-1.2.1 does not do this.)

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_Planar8To16U

Converts a Planar8 image to a 16U image .

vImage_Error vImageConvert_Planar8To16U (
const vImage_Buffer *src,
const vImage_Buffer *dest,
vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The function converts from 8-bit to 16-bit values as follows:

    uint16_t result = (srcPixel * 65535 + 127 ) / 255

You can also use this function to convert an ARGB8888 image to a 4-channel interleaved 16U image. Simply multiply the width of the destination buffer by four.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_Planar8toARGB1555

Combines four Planar8 images into one ARGB1555 image.

vImage_Error vImageConvert_Planar8toARGB1555 (
   const vImage_Buffer *srcA,
   const vImage_Buffer *srcR,
   const vImage_Buffer *srcG,
   const vImage_Buffer *srcB,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

srcA: A pointer to vImage buffer structure that contains the Planar8 image to use as the alpha channel of the destination image.
srcR: A pointer to vImage buffer structure that contains the Planar8 image to use as the red channel of the destination image.
srcG: A pointer to vImage buffer structure that contains the Planar8 image to use as the green channel of the destination image.
srcB: A pointer to vImage buffer structure that contains the Planar8 image to use as the blue channel of the destination image.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data in ARGB1555 format (16-bit pixels with 1 bit for alpha and 5 bits each for red, green, and blue). When you no longer need the data buffer, you must deallocate the memory. The destination buffer can be the same as the source buffer.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

This function calculates the 8-bit pixels in the destination image as follows:

    Pixel8 alpha =  1bitAlphaChannel * 255

    Pixel8 red   = (5bitRedChannel   * 255 + 15) / 31

    Pixel8 green = (5bitGreenChannel * 255 + 15) / 31

    Pixel8 blue  = (5bitBlueChannel  * 255 + 15) / 31

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_Planar8toARGB8888

Combines four Planar8 images into one ARGB8888 image.

vImage_Error vImageConvert_Planar8toARGB8888 (
   const vImage_Buffer *srcA,
   const vImage_Buffer *srcR,
   const vImage_Buffer *srcG,
   const vImage_Buffer *srcB,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

srcA: A pointer to vImage buffer structure that contains the Planar8 image to use as the alpha channel of the destination image.
srcR: A pointer to vImage buffer structure that contains the Planar8 image to use as the red channel of the destination image.
srcG: A pointer to vImage buffer structure that contains the Planar8 image to use as the green channel of the destination image.
srcB: A pointer to vImage buffer structure that contains the Planar8 image to use as the blue channel of the destination image.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image in ARGB8888 format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The source and destination buffers must have the same height and width.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_Planar8toPlanarF

Converts a Planar8 image to a PlanarF image.

vImage_Error vImageConvert_Planar8toPlanarF (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   Pixel_F maxFloat,
   Pixel_F minFloat,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image converted to PlanarF format. When you no longer need the data buffer, you must deallocate the memory.
maxFloat: The maximum pixel value for the destination image.
minFloat: The minimum pixel value for the destination image.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

This function transforms a Planar8 image to a PlanarF image, using a minFloat value and a maxFloat value to specify the range of values for the PlanarF image. The function maps each source pixel value(which can be in the range of 0 to 255 inclusive) linearly into the range minFloat to maxFloat, using the following mapping (where i is the old pixel value):

new pixel value = i* (maxFloat - minFloat)/255.0f + minFloat

The two buffers must have the same number of rows and the same number of columns.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_Planar8toRGB565

Combines three Planar8 images into one RGB565 image.

vImage_Error vImageConvert_Planar8toRGB565 (
   const vImage_Buffer *srcR,
   const vImage_Buffer *srcG,
   const vImage_Buffer *srcB,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

srcR: A pointer to vImage buffer structure that contains the Planar8 image to use as the red channel of the destination image.
srcG: A pointer to vImage buffer structure that contains the Planar8 image to use as the green channel of the destination image.
srcB: A pointer to vImage buffer structure that contains the Planar8 image to use as the blue channel of the destination image.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image in RGB565 format (16-bit pixels with 5 bits for red, 6 for green, and 5 for blue). When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The function calculates the pixels in the destination image as follows:

    uint32_t red   = (8bitRedChannel   * (31*2) + 255) / (255*2)

    uint32_t green = (8bitGreenChannel * 63 + 127) / 255

    uint32_t blue  = (8bitBlueChannel  * 31 + 127) / 255

    uint16_t RGB565pixel =  (red << 11) | (green <<  5) | blue

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_Planar8toRGB888

Combines three Planar8 images into one RGB888 image.

vImage_Error vImageConvert_Planar8toRGB888 (
   const vImage_Buffer *planarRed,
   const vImage_Buffer *planarGreen,
   const vImage_Buffer *planarBlue,
   const vImage_Buffer *rgbDest,
   vImage_Flags flags
);

Parameters

planarRed: A pointer to vImage buffer structure that contains the Planar8 image to use as the red channel of the destination image.
planarGreen: A pointer to vImage buffer structure that contains the Planar8 image to use as the green channel of the destination image.
planarBlue: A pointer to vImage buffer structure that contains the Planar8 image to use as the blue channel of the destination image.
rgbDest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image in RGB888 format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The source and destination buffers must have the same height and width.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_PlanarFtoARGBFFFF

Combines four PlanarF images into one ARGBFFFF image.

vImage_Error vImageConvert_PlanarFtoARGBFFFF (
   const vImage_Buffer *srcA,
   const vImage_Buffer *srcR,
   const vImage_Buffer *srcG,
   const vImage_Buffer *srcB,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

srcA: A pointer to vImage buffer structure that contains the PlanarF image to use as the alpha channel of the destination image.
srcR: A pointer to vImage buffer structure that contains the PlanarF image to use as the red channel of the destination image.
srcG: A pointer to vImage buffer structure that contains the PlanarF image to use as the green channel of the destination image.
srcB: A pointer to vImage buffer structure that contains the PlanarF image to use as the blue channel of the destination image.
dest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image data in ARGBFFFF format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The source and destination buffers must have the same height and width.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_PlanarFtoPlanar16F

Converts a PlanarF image to a Planar16F image.

vImage_Error vImageConvert_PlanarFtoPlanar16F (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image converted to Planar16F format. The destination buffer can be the same as the source buffer. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

Planar16F pixels are 16-bit floating-point numbers, conforming to the OpenEXR standard. Denormals, NaNs. and +/– Infinity are supported. In conformance with IEEE-754, all signaling NaNs are quieted during the conversion (OpenEXR-1.2.1 does not do this.)

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_PlanarFtoPlanar8

Converts a PlanarF image to a Planar8 image, clipping values to the provided minimum and maximum values.

vImage_Error vImageConvert_PlanarFtoPlanar8 (
   const vImage_Buffer *src,
   const vImage_Buffer *dest,
   Pixel_F maxFloat,
   Pixel_F minFloat,
   vImage_Flags flags
);

Parameters

src: A pointer to a vImage buffer structure that contains the source image whose data you want to convert.
dest: A pointer to a vImage buffer data structure. You are responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. The destination data buffer can be the same as the src data buffer. On return, the data buffer pointed to by this structure contains the destination image converted to Planar8 format. When you no longer need the data buffer, you must deallocate the memory.
maxFloat: A maximum pixel value. The function clips larger values to this value in the destination image.
maxFloat: A minimum pixel value. The function clips smaller values to this value in the destination image.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The minimum and maximum value determine the mapping of intensity values to the destination image. The mapping is:

    if oldPixel < minFloat

    newPixel = 0

    if minfloat <= oldPixel <= maxFloat

    newPixel = (oldPixel - minFloat) * 255.0f / (maxFloat - minFloat)

    if oldPixel > maxFloat

    newPixel = 255

The source and destination buffers must have the same height and width.

Availability

Available in Mac OS X v10.3 and later.

Declared In

Conversion.h

vImageConvert_PlanarFtoRGBFFF

Combines three PlanarF images into one RGBFFF image.

vImage_Error vImageConvert_PlanarFtoRGBFFF (
   const vImage_Buffer *planarRed,
   const vImage_Buffer *planarGreen,
   const vImage_Buffer *planarBlue,
   const vImage_Buffer *rgbDest,
   vImage_Flags flags
);

Parameters

planarRed: A pointer to vImage buffer structure that contains the PlanarF image to use as the red channel of the destination image.
planarGreen: A pointer to vImage buffer structure that contains the PlanarF image to use as the green channel of the destination image.
planarBlue: A pointer to vImage buffer structure that contains the PlanarF image to use as the blue channel of the destination image.
rgbDest: A pointer to a vImage buffer data structure. You are 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 pointed to by this structure contains the destination image in RGBFFF format. When you no longer need the data buffer, you must deallocate the memory.
flags: The options to use when performing this operation. 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 vImage Data Types and Constants Reference.

Discussion

The source and destination buffers must have the same height and width.

Availability

Available in Mac OS X v10.4 and later.

Declared In

Conversion.h

vImageConvert_PlanarToChunky8

Combines a collection of planar source images into a single interleaved destination image, with one 8-bit channel for each

vImage Conversion Reference

Overview

Functions by Task

Filling Buffers

Permuting Channels

Overwriting Channels

Converting From 16 Bit

Transforming Using Table Lookups

Flattening Data

Clipping Data

Converting Between Chunky and Planar

Converting From Planar Formats

Converting From ARGB Formats

Converting From RGB Formats

Functions

vImageBufferFill_ARGB8888

Parameters

Return Value

Availability

See Also

Declared In

vImageBufferFill_ARGBFFFF

Parameters

Return Value

Availability

See Also

Declared In

vImageClip_PlanarF

Parameters

Return Value

Availability

Declared In

vImageConvert_16SToF

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_16UToF

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_16UToPlanar8

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_ARGB1555toARGB8888

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_ARGB1555toPlanar8

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_ARGB8888toARGB1555

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_ARGB8888toPlanar8

Parameters

Return Value

Discussion

Availability

Declared In

vImageConvert_ARGB8888toRGB565

Parameters

Return Value

Discussion

Availability

Declared In