vImage Data Types and Constants Reference

Overview

The data types and constants defined in this document are used by vImage functions. The primary vImage data type is the vImage buffer, which contains a pointer to image data along with other image data information. The vImage framework also defines data types for planar and interleaved pixel types, a resampling callback filter, and an affine transform. It provides constants that specify errors that can be returned by vImage functions and flags that you can pass to a function to specify a variety of processing options.

Data Types

vImagePixelCount

A type for the number of pixels.

typedef unsigned long vImagePixelCount;

vImage_Buffer

The basic data structure used by vImage functions for passing image data.

typedef struct vImage_Buffer
   {
   void *data;
   vImagePixelCount height;
   vImagePixelCount width;
   size_t rowBytes;
} vImage_Buffer;

Fields

data

A pointer to memory for image data. The image data can be in planar (Planar8, PlanarF) or interleaved (ARGB8888, ARGBFFFF, RGBA8888, or RGBAFFFF) formats. If you are using the vImage buffer to provide an image, then the pointer should point to the top left pixel of the image. If you are providing the vImage buffer to a function that fills the memory with image data (that is, as a destination buffer), the pointer must point to an area of memory that is an appropriate size for the destination buffer. Specifically, size of the memory, in bytes, must be at least the height of the image data multiplied by the number of row bytes.

height

The number of pixels in one column of the image.

width

The number of pixels in one row of the image.

rowBytes

The number of bytes in a pixel row. This is the distance, in bytes, between the start of one row of the image and the start of the next. This quantity must be at least the width times the pixel size, where pixel size depends on the image format. You can provide a larger value, in which case the extra bytes will extend beyond the end of each row of pixels.

You may want to provide a larger value for one of two reasons: to improve performance, or to describe an image within a larger image without copying the data. The extra bytes are not considered part of the image represented by the vImage buffer.

vImage_AffineTransform

A structure for values that represent an affine transformation.

typedef struct vImage_AffineTransform
   {
   float a, b, c, d;
   float tx, ty;
} vImage_AffineTransform;

Discussion

This structure represents the 3x2 matrix :

In 32-bit applications, this structure is just like the Core Graphics CGAffineTransform data structure. In 64-bit applications, the Core Graphics data structure is equivalent to vImage_AffineTransform_Double. Most of the time, you should use the vImage_CGAffineTransform data structure, which changes size depending on architecture.

The CGAffineTransform Reference describes functions for creating and manipulating matrixes of this form.

vImage_AffineTransform_Double

A structure for values that represent a double-precision affine transformation.

typedef struct vImage_AffineTransform_Double
   {
   double         a, b, c, d;
   double         tx, ty;
} vImage_AffineTransform_Double;

Discussion

This structure represents the 3x2 matrix :

In 64-bit applications, this structure is just like the Core Graphics CGAffineTransform data structure. In 32-bit applications, the Core Graphics data structure is equivalent to vImage_AffineTransform. Most of the time, you should use the vImage_CGAffineTransform data structure, which changes size depending on architecture.

The CGAffineTransform Reference describes functions for creating and manipulating matrixes of this form.

vImage_CGAffineTransform

A structure for values that represent a Core-Graphics-compatible affine transformation.

#if defined( __LP64__ )
   typedef vImage_AffineTransform_Double vImage_CGAffineTransform;
#else
   typedef vImage_AffineTransform vImage_CGAffineTransform;
#endif

Discussion

This structure represents the 3x2 matrix :

This structure changes size to be the same size as the Core Graphics CGAffineTransform data structure. CGAffineTransform Reference describes functions for creating and manipulating matrixes of this form.

vImage_Error

A type for image errors.

typedef ssize_t vImage_Error;

vImage_Flags

A type for processing options.

typedef uint32_t vImage_Flags;

Pixel_8

A type for an 8-bit planar pixel value

typedef uint8_t Pixel_8;

Pixel_F

A type for a floating-point planar pixel value

typedef float Pixel_F;

Pixel_8888

A type for an interleaved, 8 bits per channel pixel value.

typedef uint8_t Pixel_8888[4];

Pixel_FFFF

A type for an interleaved, floating-point pixel value.

typedef float Pixel_FFFF[4];

GammaFunction

A type for a gamma function.

typedef void * GammaFunction;

ResamplingFilter

A pointer to a resampling filter callback function.

typedef void * ResamplingFilter;

Constants

Error Codes

Error codes returned by vImage functions.

enum
{
   kvImageNoError                  =   0,
   kvImageRoiLargerThanInputBuffer =   -21766,
   kvImageInvalidKernelSize        =   -21767,
   kvImageInvalidEdgeStyle         =   -21768,
   kvImageInvalidOffset_X          =   -21769,
   kvImageInvalidOffset_Y          =   -21770,
   kvImageMemoryAllocationError    =   -21771,
   kvImageNullPointerArgument      =   -21772,
   kvImageInvalidParameter         =   -21773,
   kvImageBufferSizeMismatch       =   -21774,
   kvImageUnknownFlagsBit           =    -21775
};

Constants

kvImageNoError

The vImage function completed without error.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageRoiLargerThanInputBuffer

The region of interest, as specified by the srcOffsetToROI_X and srcOffsetToROI_Y parameters and the height and width of the destination buffer, extends beyond the bottom edge or right edge of the source buffer.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageInvalidKernelSize

Either the kernel height, the kernel width, or both, are even.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageInvalidEdgeStyle

The edge style specified is invalid. This usually means that a particular function requires you to set at least one edge option flag (kvImageCopyInPlace, kvImageBackgroundColorFill, or kvImageEdgeExtend), but you did not specify one. See “Processing Flags” for more information about these flags.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageInvalidOffset_X

The srcOffsetToROI_X parameter that specifies the left edge of the region of interest is greater than the width of the source image.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageInvalidOffset_Y

The srcOffsetToROI_Y parameter that specifies the top edge of the region of interest is greater than the height of the source image.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageMemoryAllocationError

An attempt to allocate memory failed.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageNullPointerArgument

A pointer parameter is NULL and it must not be.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageInvalidParameter

Invalid parameter.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageBufferSizeMismatch

The function requires the source and destination buffers to have the same height and the same width, but they do not.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageUnknownFlagsBit

The flag is not recognized.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

Processing Flags

Flags that specify options for vImage functions.

enum
{
   kvImageNoFlags                  =   0,
   kvImageLeaveAlphaUnchanged      =   1,
   kvImageCopyInPlace              =   2,
   kvImageBackgroundColorFill      =   4,
   kvImageEdgeExtend               =   8,
   kvImageDoNotTile                =   16,
   kvImageHighQualityResampling    =   32,
   kvImageTruncateKernel           =   64,
   kvImageGetTempBufferSize        =   128
};

Constants

kvImageNoFlags

Do not set any flags.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageLeaveAlphaUnchanged

Operate on red, green, and blue channels only. When you set this flag, the alpha value is copied from source to destination. You can set this flag only for interleaved image formats.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageCopyInPlace

Copy the value of the edge pixel in the source to the destination. When you set this flag, and a convolution function is processing an image pixel for which some of the kernel extends beyond the image boundaries, vImage does not computer the convolution. Instead, the value of the particular pixel unchanged; it’s simply copied to the destination image. This flag is valid only for convolution operations. The morphology functions do not use this flag because they do not use pixels outside the image in any of their calculations.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageBackgroundColorFill

A background color fill. The associated value is a background color (that is, a pixel value). When you set this flag, vImage assigns the pixel value to all pixels outside the image. You can set this flag for convolution and geometry functions. The morphology functions do not use this flag because they do not use pixels outside the image in any of their calculations.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageEdgeExtend

Extend the edges of the image infinitely. When you set this flag, vImage replicates the edges of the image outward. It repeats the top row of the image infinitely above the image, the bottom row infinitely below the image, the first column infinitely to the left of the image, and the last column infinitely to the right. For spaces that are diagonal to the image, vImage uses the value of the corresponding corner pixel. For example, for all pixels that are both above and to the left of the image, the upper-leftmost pixel of the image (the pixel at row 0, column 0) supplies the value. In this way, vImage assigns every pixel location outside the image some value. You can set this flag for convolution and geometry functions. The morphology functions do not use this flag because they do not use pixels outside the image in any of their calculations.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageDoNotTile

Do not use vImage internal tiling routines. When you set this flag, vImage turns off internal tiling. Set this flag if you want to perform your own tiling or your own multithreading, or to use the minimum or maximum filters in place.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageHighQualityResampling

Use a higher quality, slower resampling filter for for geometry operations—shear, scale, rotate, affine transform, and so forth.

Available in OS X v10.3 and later.

Declared in vImage_Types.h.

kvImageTruncateKernel

Use the part of the kernel that overlaps the image. This flag is valid only for convolution operations. When you set this flag, vImage restricts calculations to the portion of the kernel overlapping the image. It corrects the calculated pixel by first multiplying by the sum of all the kernel elements, then dividing by the sum of the kernel elements that are actually used. This preserves image brightness at the edges.

For integer kernels:

real_divisor = divisor * (sum of used kernel elements) / (sum of kernel elements)

The morphology functions do not use this flag because they do not use pixels outside the image in any of their calculations.

Kernel truncation is not robust for certain kernels. It can ail when any rectangular segment of the kernel that includes the center, and at least one of the corners, sums to zero. You typically see this with emboss or edge detection filters, or other filters that are designed to find the slope of a signal. For those kinds of filters, you should use the kvImageEdgeExtend option instead.

Available in OS X v10.4 and later.

Declared in vImage_Types.h.

kvImageGetTempBufferSize

Get the minimum temporary buffer size for the operation, given the parameters provided. When you set this flag, the function returns the number of bytes required for the temporary buffer. A negative value specifies an error.

Available in OS X v10.4 and later.

Declared in vImage_Types.h.

kvImageLeaveAlphaUnchanged + kvImageDoNotTile

PoundDefineGroup

Para

#define VIMAGE_AFFINETRANSFORM_DOUBLE_IS_AVAILABLE 1
#define VIMAGE_CGAFFINETRANSFORM_IS_AVAILABLE 1

Constants

VIMAGE_AFFINETRANSFORM_DOUBLE_IS_AVAILABLE

Defined as 1 if double-precision affine transforms and related functions are supported on the current architecture and in the current SDK, else undefined. See vImage_AffineTransform_Double for more information.

Available in OS X v10.6 and later.

Declared in vImage_Types.h.

VIMAGE_CGAFFINETRANSFORM_IS_AVAILABLE

Defined as 1 if Core Graphics affine transforms and related functions are supported on the current architecture and in the current SDK, else undefined. See vImage_CGAffineTransform for more information.

Available in OS X v10.6 and later.

Declared in vImage_Types.h.