opensolaris man page for mlib_imagehistogram2

mlib_ImageHistogram2(3MLIB)				    mediaLib Library Functions				       mlib_ImageHistogram2(3MLIB)

NAME
       mlib_ImageHistogram2 - histogram

SYNOPSIS
       cc [ flag... ] file... -lmlib [ library... ]
       #include <mlib.h>

       mlib_status mlib_ImageHistogram2(mlib_s32 **histo, const mlib_image *img,
	    const mlib_s32 *numBins, const mlib_s32 *lowValue,
	    const mlib_s32 *highValue, mlib_s32 xStart, mlib_s32 yStart,
	    mlib_s32 xPeriod, mlib_s32 yPeriod);

DESCRIPTION
       The  mlib_ImageHistogram2()  function creates a histogram by scanning an image, counting the number of pixels within a given range for each
       channel of the image, and then generating a histogram.

       The image can have 1, 2, 3 or 4 channels. The data type of the image can be MLIB_BYTE, MLIB_SHORT, MLIB_USHORT, or MLIB_INT. The  histogram
       must have the same number of channels as the image has.

       One  entry of the histogram, or a bin, is used to accumulate the number of pixels within a certain sub-range. The legal pixel range and the
       number of bins may be controlled separately.

       If binWidth is defined as (highValue - lowValue )/numBins then bin i counts pixel values in the following range:

	 lowValue + i*binWidth <= x < lowValue + (i + 1)*binWidth

       The set of pixels scanned may furthermore be reduced by specifying xPeriod and yPeriod parameters that specify the sampling rate along each
       axis.

       The set of pixels to be accumulated may be obtained from the following equation:

	 x = xStart + p*xPeriod;  0 <= p < (w - xStart)/xPeriod
	 y = yStart + q*yPeriod;  0 <= q < (h - yStart)/yPeriod

       It is the user's responsibility to clear the histogram table before this function is called and to ensure that the histogram table supplied
       is suitable for the source image and the parameters. Otherwise, the result of this function is undefined.

       The range from lowValue[k] to (highValue[k] - 1) must be a valid subrange of the image type range.

PARAMETERS
       The function takes the following arguments:

       histo	    Pointer to histogram. The format of the histogram is histo[channel][index]. The index values for channel i can be 0,  1,  ...,
		    numBins[i]-1.

       img	    Pointer to source image.

       numBins	    The number of bins for each channel of the image.

       lowValue     The lowest pixel value checked for each channel.

       highValue    The highest pixel value checked for each channel. When counting the pixel values, highValue is not included.

       xStart	    The initial X sample coordinate.

       yStart	    The initial Y sample coordinate.

       xPeriod	    The X sampling rate. xPeriod >= 1.

       yPeriod	    The Y sampling rate. yPeriod >= 1.

RETURN VALUES
       The function returns MLIB_SUCCESS if successful. Otherwise it returns MLIB_FAILURE.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       mlib_ImageHistogram(3MLIB), attributes(5)

SunOS 5.11							    2 Mar 2007					       mlib_ImageHistogram2(3MLIB)