Function

vImageEndsInContrastStretch_PlanarF

Performs an ends-in contrast stretch operation on a PlanarF source image.

Declaration

vImage_Error vImageEndsInContrastStretch_PlanarF(const vImage_Buffer *src, const vImage_Buffer *dest, void *tempBuffer, unsigned int percent_low, unsigned int percent_high, unsigned int histogram_entries, Pixel_F minVal, Pixel_F maxVal, vImage_Flags flags);

Parameters

src

A pointer to a vImage buffer structure that contains the source 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. When you no longer need the data buffer, you must deallocate the memory.

tempBuffer

A pointer to a temporary buffer. If you pass NULL, the function allocates the buffer, then deallocates it before returning. Alternatively, you can allocate the buffer yourself, in which case you are responsible for deallocating it when you is no longer need it.

If you want to allocate the buffer yourself, see the Discussion for information on how to determine the minimum size that you must allocate.

percent_low

A percentage value. The number of pixels that map to the lowest end of the histogram of the transformed image should represent this percentage of the total pixels.

percent_high

A percentage value. The number of pixels that map to the highest end of the histogram of the transformed image should represent this percentage of the total pixels.

histogram_entries

The number of histogram entries, or “bins,” to be used in histograms for this operation.

minVal

A minimum pixel value, the low end of the histogram. Any pixel value less than this will be clipped to this value (for the purposes of histogram calculation), and assigned to the first histogram entry.

maxVal

A maximum pixel value, the high end of the histogram. Any pixel value greater than this will be clipped to this value (for the purposes of histogram calculation), and assigned to the last histogram entry.

flags

The options to use. Set the kvImageDoNotTile flag if you plan to perform your own tiling or use multithreading.

Set the kvImageLeaveAlphaUnchanged flag to copy the alpha channel to the destination image unchanged.

Return Value

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

Discussion

The ends-in contrast stretch operation alters the image histogram so that a certain percentage of pixels are mapped to the lowest end of the histogram, a certain percentage are mapped to the highest end, and the values in between “stretched” between the lowest and the highest. The ends-in contrast stretch operation is done separately for each of the four channels—alpha, red, green, and blue. However the size and range values are the same for each of the four histograms. In general, it is not possible to get exactly the desired percentage of pixels at the low end and the high end of the histogram of the transformed image. This operation only approximates the given values.

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

If you want to allocate the memory for the tempBuffer parameter yourself, call this function twice, as follows:

  1. To determine the minimum size for the temporary buffer, the first time you call this function pass the kvImageGetTempBufferSize flag. Pass the same values for all other parameters that you intend to use in for the second call. The function returns the required minimum size, which should be a positive value. (A negative returned value indicates an error.) The kvImageGetTempBufferSize flag prevents the function from performing any processing other than to determine the minimum buffer size.

  2. After you allocate enough space for a buffer of the returned size, call the function a second time, passing a valid pointer in the tempBuffer parameter. This time, do not pass the kvImageGetTempBufferSize flag.

See Also

Stretching the Contrast

vImageContrastStretch_ARGBFFFF

Stretches the contrast of an ARGBFFFF source image.

vImageContrastStretch_ARGB8888

Stretches the contrast of an ARGB8888 source image.

vImageContrastStretch_PlanarF

Stretches the contrast of a PlanarF source image.

vImageContrastStretch_Planar8

Stretches the contrast of a Planar8 source image.

vImageEndsInContrastStretch_ARGBFFFF

Performs an ends-in contrast stretch operation on an ARGBFFFF source image.

vImageEndsInContrastStretch_ARGB8888

Performs an ends-in contrast stretch operation on an ARGB8888 source image.

vImageEndsInContrastStretch_Planar8

Performs an ends-in contrast stretch operation on a Planar8 source image.