GLHISTOGRAM(3G)                                                GLHISTOGRAM(3G)



NAME
       glHistogram - define histogram table


C SPECIFICATION
       void glHistogram( GLenum target,
                         GLsizei width,
                         GLenum internalformat,
                         GLboolean sink )


PARAMETERS
       target          The  histogram whose parameters are to be set.  Must be
                       one of GLHISTOGRAM or GLPROXYHISTOGRAM.

       width           The number of entries in the histogram table.  Must  be
                       a power of 2.

       internalformat  The  of entries in the histogram table.  Must be one of
                       GLALPHA, GLALPHA4, GLALPHA8, GLALPHA12, GLALPHA16,
                       GLUMINANCE,       GLUMINANCE4,       GLUMINANCE8,
                       GLUMINANCE12,   GLUMINANCE16,   GLUMINANCEALPHA,
                       GLUMINANCE4ALPHA4,             GLUMINANCE6ALPHA2,
                       GLUMINANCE8ALPHA8,            GLUMINANCE12ALPHA4,
                       GLUMINANCE12ALPHA12,         GLUMINANCE16ALPHA16,
                       GLR3G3B2,   GLRGB,   GLRGB4,   GLRGB5,   GLRGB8,
                       GLRGB100,   GLRGB12,   GLRGB16,   GLRGBA,  GLRGBA2,
                       GLRGBA4, GLRGB5A1, GLRGBA8, GLRGB100A2, GLRGBA12,
                       or GLRGBA16.

       sink            If  GLTRUE,  pixels will be consumed by the histogram-
                       ming process and no drawing  or  texture  loading  will
                       take  place.   If  GLFALSE, pixels will proceed to the
                       minmax process after histogramming.

DESCRIPTION
       When GLHISTOGRAM 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  glEnable  and  disabled
       with glDisable.

       When  target  is  GLHISTOGRAM,  glHistogram redefines the current his-
       togram table to have width entries of the  specified by internalformat.
       The  entries  are indexed 0 through width - 1, and all entries are ini-
       tialized to zero.  The values in the previous histogram table, if  any,
       are  lost.   If  sink  is GLTRUE, then pixels are discarded after his-
       togramming; no further processing of the pixels  takes  place,  and  no
       drawing, texture loading, or pixel readback will result.

       When  target  is  GLPROXYHISTOGRAM,  glHistogram  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
       glHistogram  is  present  only  if  GLARBimaging  is  returned   when
       glGetString is called with an argument of GLEXTENSIONS.

ERORS
       GLINVALIDENUM is generated if target is not one of the allowable val-
       ues.

       GLINVALIDVALUE is generated if width is less than zero or  is  not  a
       power of 2.

       GLINVALIDENUM is generated if internalformat is not one of the allow-
       able values.

       GLTABLETOLARGE is generated if target is GLHISTOGRAM and the  his-
       togram table specified is too large for the implementation.

       GLINVALIDOPERATION  is  generated  if glHistogram is executed between
       the execution of glBegin and the corresponding execution of glEnd.

ASOCIATED GETS
       glGetHistogramParameter

SEE ALSO
       glGetHistogram, glResetHistogram



                                                               GLHISTOGRAM(3G)