Function

vImageConvert_Planar8toIndexed2

Converts a Planar8 image to an indexed 2-bit image.

Declaration

vImage_Error vImageConvert_Planar8toIndexed2(const vImage_Buffer *src, const vImage_Buffer *dest, void *tempBuffer, Pixel_8 colors[4], int dither, const vImage_Flags flags);

Parameters

src

A pointer to the source vImage buffer object.

dest

A pointer to the destination vImage buffer object. Because the source pixel format is smaller than a byte, there are multiple pixels in each byte of the data buffer. These pixels are interpreted as being in big endian order (that is, the low-indexed pixel is in the high-order bits of the byte).

Sub-byte indexing of scanlines is unsupported, because the data and rowBytes fields of the buffer are specified in whole bytes.

Widths, however, are measured in pixels, so a scanline may end in the middle of a byte. If this occurs, the contents of any unused bits of the final byte are ignored.

tempBuffer

A pointer to temporary buffer for the routine to use for scratch space. If non-NULL, the buffer must be at least as large as the value returned by calling this function with the kvImageGetTempBufferSize flag. If NULL, this function will still work, but may allocate and free a scratch buffer internally.

colors

Color table to use for the destination. vImage can compute an appropriate color table by setting this parameter to all zeros.

dither

Type of dithering, if any, to apply to the image.

flags

The options to use when performing the operation. If you plan to perform your own tiling or use multithreading, pass kvImageDoNotTile.

Return Value

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

Discussion

This function supports the following dithering options:

kvImageConvert_DitherNone

This option applies no dithering. Input values are rounded to the nearest value representable in the destination format.

kvImageConvert_DitherOrdered

Precomputed blue noise is added to the image before the values are rounded to the destination format. The offset into the blue noise is randomized per call to avoid visible artifacts if you do your own tiling or call the function on sequential frames of video.

kvImageConvert_DitherOrderedReproducible

Precomputed blue noise is added to the image before the values are rounded to the destination format. The offset into the blue noise is the same for every call to allow users to get reproducible results.

kvImageConvert_DitherFloydSteinberg

Floyd-Steinberg dithering is applied to the image.

kvImageConvert_DitherAtkinson

Atkinson dithering is applied to the image.

You can further influence the ordered dither methods by shaping the noise distribution using the Gaussian and uniform options below. These options are OR-ed with kvImageConvert_DitherOrdered or kvImageConvert_DitherOrderedReproducible:

kvImageConvert_OrderedGaussianBlue

When using an ordered dither pattern, distribute the noise according to a Gaussian distribution. This generally gives more pleasing images—less noisy and perhaps a little more saturated—but color fidelity can suffer. Its effect is between kvImageConvert_DitherNone and kvImageConvert_DitherOrdered | kvImageConvert_DitherUniform. This option is the default for kvImageConvert_DitherOrdered and kvImageConvert_DitherOrderedReproducible.

kvImageConvert_OrderedUniformBlue

When using an ordered dither pattern, distribute the noise uniformly. This generally gives the best color fidelity, but the resulting image is noisier and more obviously dithered. This is usually the best choice when low bit depth content is drawn next to high bit depth content and in other circumstances where subtle changes to color arising from the conversion could be easily noticed. It may be a poor choice when the image is likely to be enlarged—which would cause the noise to become more evident—and for very flat or synthetic content with little inherent noise. You can avoid the enlargement problem by enlarging first at high bit depth, then converting to lower bit depth.

See Also

Converting from Planar Formats

vImageConvert_Planar8ToARGBFFFF

Combines four Planar8 images into one ARGBFFFF image.

vImageConvert_Planar8toARGB1555

Combines four Planar8 images into one ARGB1555 image.

vImageConvert_Planar8toARGB8888

Combines four Planar8 images into one ARGB8888 image.

vImageConvert_Planar8ToBGRX8888

Interleaves three Planar8 images into one BGRX8888 image.

vImageConvert_Planar8ToBGRXFFFF

Combines three Planar8 images into one BGRXFFFF image.

vImageConvert_Planar8toRGB565

Combines three Planar8 images into one RGB565 image.

vImageConvert_Planar8toRGB888

Combines three Planar8 images into one RGB888 image.

vImageConvert_Planar8ToXRGBFFFF

Combines three Planar8 images into one XRGBFFFF image.

vImageConvert_Planar8ToXRGB8888

Interleaves three Planar8 images into one XRGB8888 image.

vImageConvert_Planar8To16U

Converts a Planar8 image to a 16U image .

vImageConvert_Planar8ToRGBXFFFF

Combines three Planar8 images into one RGBXFFFF image.

vImageConvert_Planar8ToRGBX8888

Interleaves three Planar8 images into one RGBX8888 image.

vImageConvert_Planar8toIndexed1

Converts a Planar8 image to an indexed 1-bit image.

vImageConvert_Planar8toIndexed4

Converts a Planar8 image to an indexed 4-bit image.

vImageConvert_Planar16Q12toARGB16F

Combines three 16Q12 images into one ARGB16F image.

vImageConvert_Planar16UtoARGB16U

Combines four 16U images into one ARGB16U image.

vImageConvert_Planar16Q12toRGB888

Combines three 16Q12 images into one RGB888 image.

vImageConvert_Planar16Q12toARGB8888

Combines three 16Q12 images into one ARGB8888 image.

vImageConvert_Planar16Q12toRGB16F

Combines three 16Q12 images into one RGB16F image.

vImageConvert_Planar16UtoRGB16U

Combines three 16U images into one RGB16U image.

vImageConvert_FTo16S

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

vImageConvert_FTo16U

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

vImageConvert_PlanarFtoARGBFFFF

Combines four PlanarF images into one ARGBFFFF image.

vImageConvert_PlanarFToARGB8888

Converts four PlanarF images into one ARGB8888 image.

vImageConvert_PlanarFtoRGBFFF

Combines three PlanarF images into one RGBFFF image.

vImageConvert_PlanarFToBGRX8888

Converts three PlanarF images into one BGRX8888 image.

vImageConvert_PlanarFToBGRXFFFF

Converts three PlanarF images into one BGRXFFFF image.

vImageConvert_PlanarFToXRGBFFFF

Converts three PlanarF images into one XRGBFFFF image.

vImageConvert_PlanarFToXRGB8888

Converts three PlanarF images into one XRGB8888 image.

vImageConvert_PlanarFToRGBXFFFF

Converts three PlanarF images into one RGBXFFFF image.

vImageConvert_PlanarFToRGBX8888

Converts three PlanarF images into one RGBX8888 image.