vImage Histogram Reference

Histogram functions calculate image histograms or manipulate a histogram to modify an image. There are a number of reasons to apply histogram operations to an image. An image may not make full use of the possible range of intensity values—for example, most of its pixels may be fairly dark, making details difficult to see. Changing the image so that it has a more uniform histogram can improve contrast. Also, it may be easier to compare two images (with respect to texture or other aspects) if you change each histogram to match some standard histogram.

Histogram operations are point operations: that is, the intensity of a destination pixel depends only on the intensity of the source pixel, modified by values that are the same over the entire image. Two pixels of the same intensity always map to two pixels of the same (but presumably altered) intensity. If the original image has N different intensity values, the transformed image will have at most N different intensity levels represented.

The vImage histogram functions either calculate histograms or perform one of these point operations:

Contrast stretch transforms an image so that its intensity values stretch out along the full range of intensity values. It is best used on images in which all the pixels are concentrated in one area of the intensity spectrum, and intensity values outside that area are not represented.

Ends-in contrast stretch is a more complex version of the contrast stretch operation. These types of functions are best used on images that have some pixels at or near the lowest and highest values of the intensity spectrum, but whose histogram is still mainly concentrated in one area. The ends-in contrast stretch functions map all intensities less than or equal to a certain level to 0; all intensities greater than or equal to a certain level to 255; and perform a contrast stretch on all the values in between. The low and high levels are not defined directly by two given intensity values, but by percentages: the ends-in contrast stretch operation must find intensity levels such that a certain percent of pixels are below one of the intensity values, and a certain percent are above the other intensity value

Equalization transforms an image so that it has a more uniform histogram. A truly uniform histogram is one in which each intensity level occurs with equal frequency. These functions approximate that histogram.

Histogram specification transforms an image so that its histogram more closely resembles a given histogram.

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.

histogram_entries

The number of histogram entries, or bins, to use 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. This minimum value is applied to each of the four channels separately.

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. This maximum value is applied to each of the four channels separately.

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

Discussion

The contrast stretch operation alters the image histogram so that pixel values can be found at both the lowest and highest end of the histogram, with values in between “stretched” in a linear fashion. The 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.

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:

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.

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.

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.

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

Discussion

The contrast stretch operation alters the image histogram so that pixel values can be found at both the lowest and highest end of the histogram, with values in between “stretched” in a linear fashion. The 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.

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

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.

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

Discussion

The contrast stretch operation alters the image histogram so that pixel values can be found at both the lowest and highest end of the histogram, with values in between “stretched” in a linear fashion. The 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.

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:

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.

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.

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.

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

Discussion

The contrast stretch operation alters the image histogram so that pixel values can be found at both the lowest and highest end of the histogram, with values in between “stretched” in a linear fashion. The 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.

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

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. This minimum value is applied to each of the four channels separately.

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. This maximum value is applied to each of the four channels separately.

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

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:

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.

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.

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.

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.

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

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.

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

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:

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.

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.

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.

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.

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

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.

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.

histogram_entries

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

minVal

A minimum pixel value. 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. This minimum value is applied to each of the four channels separately.

maxVal

A maximum pixel value. 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. This maximum value is applied to each of the four channels separately.

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

Discussion

The equalization operation alters the image histogram so that it is closer to a uniform intensity distribution. The histogram equalization 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.

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:

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.

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.

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.

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

Discussion

The equalization operation alters the image histogram so that it is closer to a uniform intensity distribution. The histogram equalization 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.

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

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.

histogram_entries

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

minVal

A minimum pixel value. 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. This minimum value is applied to each of the four channels separately.

maxVal

A maximum pixel value. 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. This maximum value is applied to each of the four channels separately.

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

Discussion

The equalization operation alters the image histogram so that it is closer to a uniform intensity distribution. The histogram equalization 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.

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:

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.

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.

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.

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.

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.

desiredHistogram

A pointer to an array of four histograms, one each for alpha, red, green, and blue (in that order). These are the desired histograms for the transformed image. Each histogram should be an array with histogram_entries elements.

histogram_entries

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

minVal

A minimum pixel value. 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. This minimum value is applied to each of the four channels separately.

maxVal

A maximum pixel value. 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. This maximum value is applied to each of the four channels separately.

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

Discussion

The specification operation alters the image histogram so that it more closely resembles a given histogram. The histogram specification 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, and for each of the four desired histograms.

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:

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.

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.

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.

desiredHistogram

A pointer to an array of four histograms, one each for alpha, red, green, and blue (in that order). These are the desired histograms for the transformed image. Each histogram should be an array with 256 elements.

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

Discussion

The specification operation alters the image histogram so that it more closely resembles a given histogram. The histogram specification 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, and for each of the four desired histograms.

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

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.

desiredHistogram

A pointer the desired histogram for the transformed image. The histogram should be an array with histogram_entries elements.

histogram_entries

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

minVal

A minimum pixel value. 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. This minimum value is applied to each of the four channels separately.

maxVal

A maximum pixel value. 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. This maximum value is applied to each of the four channels separately.

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

Discussion

The specification operation alters the image histogram so that it more closely resembles a given histogram. The histogram specification 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, and for each of the four desired histograms.

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:

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.

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.

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.

desiredHistogram

A pointer the desired histogram for the transformed image. The histogram should be an array with 256 elements.

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

Discussion

The specification operation alters the image histogram so that it more closely resembles a given histogram. The histogram specification 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, and for each of the four desired histograms.

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

Parameters

src

A pointer to a vImage buffer structure that contains the source image.

histogram

A pointer to an array of four histograms, one each for alpha, red, green, and blue (in that order). On return, this array will contain the four histograms for the corresponding channels. Each of the four histograms will be an array with histogram_entries elements.

histogram_entries

The number of histogram entries, or “bins.” Each of the four calculated histograms will be an array with histogram_entries elements.

minVal

A minimum pixel value. 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. This minimum value is applied to each of the four channels separately.

maxVal

A maximum pixel value. 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. This maximum value is applied to each of the four channels separately.

flags

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

Parameters

src

A pointer to a vImage buffer structure that contains the source image.

histogram

A pointer to a histograms, one each for alpha, red, green, and blue (in that order). On return, this array will contain the four histograms for the corresponding channels. Each of the four histograms will be an array with 256 elements.

flags

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