iOS Developer Library

Developer

Accelerate Framework Reference vImage Data Types and Constants Reference

Options
Deployment Target:

On This Page
Language:

vImage Data Types and Constants Reference

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

  • A type for the number of pixels.

    Declaration

    Objective-C

    typedef unsigned long vImagePixelCount;

    Discussion

    For LP64 (ppc64) this is a 64-bit quantity.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    struct vImage_Buffer { var data: UnsafeMutablePointer<Void> var height: vImagePixelCount var width: vImagePixelCount var rowBytes: UInt }

    Objective-C

    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.

    Discussion

    vImage functions will not attempt to read pixel data outside the area described by the height and width fields of the vImage buffer. The function will also not write data outside that area.

    Availability

    Available in iOS 5.0 and later.

  • A structure for values that represent an affine transformation.

    Declaration

    Swift

    struct vImage_AffineTransform { var a: Float var b: Float var c: Float var d: Float var tx: Float var ty: Float }

    Objective-C

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

    Discussion

    This structure represents the 3x2 matrix :

    image: ../Art/matrix1.pdf

    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.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    struct vImage_AffineTransform_Double { var a: Double var b: Double var c: Double var d: Double var tx: Double var ty: Double }

    Objective-C

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

    Discussion

    This structure represents the 3x2 matrix :

    image: ../Art/matrix1.pdf

    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.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Objective-C

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

    Discussion

    This structure represents the 3x2 matrix :

    image: ../Art/matrix1.pdf

    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.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 6.0 and later.

  • A type for image errors.

    Declaration

    Objective-C

    typedef ssize_t vImage_Error;

    Discussion

    Error Codes describes the constants that use this type.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

  • A type for processing options.

    Declaration

    Objective-C

    typedef uint32_t vImage_Flags;

    Discussion

    Processing Flags describes the constants that use this type.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

  • A type for an 8-bit planar pixel value

    Declaration

    Objective-C

    typedef uint8_t Pixel_8;

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

  • A type for a floating-point planar pixel value

    Declaration

    Objective-C

    typedef float Pixel_F;

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Objective-C

    typedef uint8_t Pixel_8888[4];

    Discussion

    For example, uint8_t[4] = { alpha, red, green, blue } for ARGB data.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Objective-C

    typedef float Pixel_FFFF[4];

    Discussion

    For example, float[4] = { alpha, red, green, blue } for ARGB data.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

  • A type for a gamma function.

    Declaration

    Objective-C

    typedef void * GammaFunction;

    Discussion

    You use this data type when you create a gamma function. See vImageCreateGammaFunction.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

  • A pointer to a resampling filter callback function.

    Declaration

    Objective-C

    typedef void * ResamplingFilter;

    Discussion

    You pass a resampling filter callback to a shear function. The resampling filter pointer can point to a structure that contains a function, rows of precalculated values, flag settings, and so on. The shear function requires that the structure contains a scale factor.

    Import Statement

    Objective-C

    @import Accelerate;

    Availability

    Available in iOS 5.0 and later.

Constants

  • Error codes returned by vImage functions.

    Declaration

    Objective-C

    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

      kvImageNoError

      The vImage function completed without error.

      Available in iOS 5.0 and later.

    • kvImageRoiLargerThanInputBuffer

      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 iOS 5.0 and later.

    • kvImageInvalidKernelSize

      kvImageInvalidKernelSize

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

      Available in iOS 5.0 and later.

    • kvImageInvalidEdgeStyle

      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 iOS 5.0 and later.

    • kvImageInvalidOffset_X

      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 iOS 5.0 and later.

    • kvImageInvalidOffset_Y

      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 iOS 5.0 and later.

    • kvImageMemoryAllocationError

      kvImageMemoryAllocationError

      An attempt to allocate memory failed.

      Available in iOS 5.0 and later.

    • kvImageNullPointerArgument

      kvImageNullPointerArgument

      A pointer parameter is NULL and it must not be.

      Available in iOS 5.0 and later.

    • kvImageInvalidParameter

      kvImageInvalidParameter

      Invalid parameter.

      Available in iOS 5.0 and later.

    • kvImageBufferSizeMismatch

      kvImageBufferSizeMismatch

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

      Available in iOS 5.0 and later.

    • kvImageUnknownFlagsBit

      kvImageUnknownFlagsBit

      The flag is not recognized.

      Available in iOS 5.0 and later.

  • Flags that specify options for vImage functions.

    Declaration

    Objective-C

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

    Constants

    • kvImageNoFlags

      kvImageNoFlags

      Do not set any flags.

      Available in iOS 5.0 and later.

    • kvImageLeaveAlphaUnchanged

      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 iOS 5.0 and later.

    • kvImageCopyInPlace

      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 iOS 5.0 and later.

    • kvImageBackgroundColorFill

      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 iOS 5.0 and later.

    • kvImageEdgeExtend

      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 iOS 5.0 and later.

    • kvImageDoNotTile

      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 iOS 5.0 and later.

    • kvImageHighQualityResampling

      kvImageHighQualityResampling

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

      Available in iOS 5.0 and later.

    • kvImageTruncateKernel

      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 iOS 5.0 and later.

    • kvImageGetTempBufferSize

      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 iOS 5.0 and later.

    Discussion

    You can pass multiple flags to a function by adding the flag values together. For example, to leave alpha unchanged and turn off tiling, you can pass:

    • kvImageLeaveAlphaUnchanged + kvImageDoNotTile

    Three of the flags are mutually exclusive: kvImageCopyInPlace, kvImageBackgroundColorFill, and kvImageEdgeExtend. Never pass more than one of these flag values in the same flag parameter.

    When passing flags to a function, do not set values for flags that are not used by the function. If the function requires you to set certain flag values, do so. For example, for the convolution function, you must set exactly one of kvImageCopyInPlace, kvImageBackgroundColorFill, and kvImageEdgeExtend. Otherwise the function may return an error. If you don’t want to set flag values, pass kvImageNoFlags.

  • Para

    Declaration

    Objective-C

    #define VIMAGE_AFFINETRANSFORM_DOUBLE_IS_AVAILABLE 1 #define VIMAGE_CGAFFINETRANSFORM_IS_AVAILABLE 1

    Constants

    • VIMAGE_AFFINETRANSFORM_DOUBLE_IS_AVAILABLE

      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 iOS 5.0 and later.

    • VIMAGE_CGAFFINETRANSFORM_IS_AVAILABLE

      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 iOS 6.0 and later.