Bitmap::GetHistogram method (gdiplusheaders.h)

The Bitmap::GetHistogram method returns one or more histograms for specified color channels of this Bitmap object.

Syntax

Status GetHistogram(
  [in]  HistogramFormat format,
  [in]  UINT            NumberOfEntries,
  [out] UINT            *channel0,
  [out] UINT            *channel1,
  [out] UINT            *channel2,
  [out] UINT            *channel3
);

Parameters

[in] format

Type: HistogramFormat

Element of the HistogramFormat enumeration that specifies the channels for which histograms will be created.

[in] NumberOfEntries

Type: UINT

Integer that specifies the number of elements (of type UINT) in each of the arrays pointed to by channel0, channel1, channel2, and channel3. You must allocate memory for those arrays before you call Bitmap::GetHistogram. To determine the required number of elements, call Bitmap::GetHistogramSize.

[out] channel0

Type: UINT*

Pointer to an array of UINTs that receives the first histogram.

[out] channel1

Type: UINT*

Pointer to an array of UINTs that receives the second histogram if there is a second histogram. Pass NULL if there is no second histogram.

[out] channel2

Type: UINT*

Pointer to an array of UINTs that receives the third histogram if there is a third histogram. Pass NULL if there is no third histogram.

[out] channel3

Type: UINT*

Pointer to an array of UINTs that receives the fourth histogram if there is a fourth histogram. Pass NULL if there is no fourth histogram.

Return value

Type: Status

If the method succeeds, it returns Ok, which is an element of the Status enumeration.

If the method fails, it returns one of the other elements of the Status enumeration.

Remarks

The number of histograms returned depends on the HistogramFormat enumeration element passed to the format parameter. For example, if format is equal to HistogramFormatRGB, then three histograms are returned: one each for the red, green, and blue channels. In that case, channel0 points to the array that receives the red-channel histogram, channel1 points to the array that receives the green-channel histogram, and channel2 points to the array that receives the blue-channel histogram. For HistogramFormatRGB, channel3 must be set to NULL because there is no fourth histogram. For more details, see the HistogramFormat enumeration.

Examples

The following example constructs a Bitmap object from a BMP file. The code retrieves three histograms from the bitmap: one each for the red, green, and blue channels. Note the order of RGB in the name of the enumeration element HistogramFormatRGB. R is first, so it corresponds with ch0. Green is second, so it corresponds with ch1. Blue is third, so it corresponds with ch2. The final parameter passed to Bitmap::GetHistogram is NULL because there is no fourth histogram.

Bitmap myBitmap(L"Picture.bmp");

UINT numEntries;
myBitmap.GetHistogramSize(HistogramFormatRGB, &numEntries);

UINT* ch0 = new UINT[numEntries];
UINT* ch1 = new UINT[numEntries];
UINT* ch2 = new UINT[numEntries];

myBitmap.GetHistogram(HistogramFormatRGB, numEntries, ch0, ch1, ch2, NULL);

// Print the histogram values for the three channels: red, green, blue.
for(UINT j = 0; j < numEntries; ++j)
{
   printf("%u\t%u\t%u\t%u\n", j, ch0[j], ch1[j], ch2[j]);
}

delete ch0;
delete ch1;
delete ch2;

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	gdiplusheaders.h (include Gdiplus.h)
Library	Gdiplus.lib
DLL	Gdiplus.dll

See also

Bitmap