NAME

glHistogram - define histogram table

C SPECIFICATION

void ggllHHiissttooggrraamm( GLenum _t_a_r_g_e_t,
                  GLsizei _w_i_d_t_h,
                  GLenum _i_n_t_e_r_n_a_l_f_o_r_m_a_t,
                  GLboolean _s_i_n_k )

delim $$

PARAMETERS

_t_a_r_g_e_t
The histogram whose parameters are to be set. Must be one of GGLL__HHIISSTTOOGGRRAAMM or GGLL__PPRROOXXYY__HHIISSTTOOGGRRAAMM.
_w_i_d_t_h
The number of entries in the histogram table. Must be a power of 2.
_i_n_t_e_r_n_a_l_f_o_r_m_a_t
The of entries in the histogram table. Must be one of GGLL__AALLPPHHAA, GGLL__AALLPPHHAA44, GGLL__AALLPPHHAA88, GGLL__AALLPPHHAA1122, GGLL__AALLPPHHAA1166, GGLL__LLUUMMIINNAANNCCEE, GGLL__LLUUMMIINNAANNCCEE44, GGLL__LLUUMMIINNAANNCCEE88, GGLL__LLUUMMIINNAANNCCEE1122, GGLL__LLUUMMIINNAANNCCEE1166, GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA, GGLL__LLUUMMIINNAANNCCEE44__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE66__AALLPPHHAA22, GGLL__LLUUMMIINNAANNCCEE88__AALLPPHHAA88, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA1122, GGLL__LLUUMMIINNAANNCCEE1166__AALLPPHHAA1166, GGLL__RR33__GG33__BB22, GGLL__RRGGBB, GGLL__RRGGBB44, GGLL__RRGGBB55, GGLL__RRGGBB88, GGLL__RRGGBB1100, GGLL__RRGGBB1122, GGLL__RRGGBB1166, GGLL__RRGGBBAA, GGLL__RRGGBBAA22, GGLL__RRGGBBAA44, GGLL__RRGGBB55__AA11, GGLL__RRGGBBAA88, GGLL__RRGGBB1100__AA22, GGLL__RRGGBBAA1122, or GGLL__RRGGBBAA1166.
_s_i_n_k
If GGLL__TTRRUUEE, pixels will be consumed by the histogramming process and no drawing or texture loading will take place. If GGLL__FFAALLSSEE, pixels will proceed to the minmax process after histogramming.

DESCRIPTION

When GGLL__HHIISSTTOOGGRRAAMM is enabled, RGBA color components are converted to histogram table indices by clamping to the range [0,1], multiplying by the width of the histogram table, and rounding to the nearest integer. The table entries selected by the RGBA indices are then incremented. (If the internal of the histogram table includes luminance, then the index derived from the R color component determines the luminance table entry to be incremented.) If a histogram table entry is incremented beyond its maximum value, then its value becomes undefined. (This is not an error.)

Histogramming is performed only for RGBA pixels (though these may be specified originally as color indices and converted to RGBA by index table lookup). Histogramming is enabled with ggllEEnnaabbllee and disabled with ggllDDiissaabbllee.

When _t_a_r_g_e_t is GGLL__HHIISSTTOOGGRRAAMM, ggllHHiissttooggrraamm redefines the current histogram table to have _w_i_d_t_h entries of the specified by _i_n_t_e_r_n_a_l_f_o_r_m_a_t. The entries are indexed 0 through $"width" ~-~ 1$, and all entries are initialized to zero. The values in the previous histogram table, if any, are lost. If _s_i_n_k is GGLL__TTRRUUEE, then pixels are discarded after histogramming; no further processing of the pixels takes place, and no drawing, texture loading, or pixel readback will result.

When _t_a_r_g_e_t is GGLL__PPRROOXXYY__HHIISSTTOOGGRRAAMM, ggllHHiissttooggrraamm computes all state information as if the histogram table were to be redefined, but does not actually define the new table. If the requested histogram table is too large to be supported, then the state information will be set to zero. This provides a way to determine if a histogram table with the given parameters can be supported.

NOTES

ggllHHiissttooggrraamm is present only if GGLL__AARRBB__iimmaaggiinngg is returned when ggllGGeettSSttrriinngg is called with an argument of GGLL__EEXXTTEENNSSIIOONNSS.

ERRORS

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_a_r_g_e_t is not one of the allowable values.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _w_i_d_t_h is less than zero or is not a power of 2.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _i_n_t_e_r_n_a_l_f_o_r_m_a_t is not one of the allowable values.

GGLL__TTAABBLLEE__TTOOOO__LLAARRGGEE is generated if _t_a_r_g_e_t is GGLL__HHIISSTTOOGGRRAAMM and the histogram table specified is too large for the implementation.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllHHiissttooggrraamm is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

ASSOCIATED GETS

ggllGGeettHHiissttooggrraammPPaarraammeetteerr

SEE ALSO

ggllGGeettHHiissttooggrraamm((33GG)), ggllRReesseettHHiissttooggrraamm((33GG))