glHistogram(3)

NAME

       glHistogram - define histogram table

C SPECIFICATION

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

       delim $$

PARAMETERS

       target          The  histogram whose parameters are to be set.  Must be
                       one of GL_HISTOGRAM or GL_PROXY_HISTOGRAM.

       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
                       GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16,
                       GL_LUMINANCE,       GL_LUMINANCE4,       GL_LUMINANCE8,
                       GL_LUMINANCE12,   GL_LUMINANCE16,   GL_LUMINANCE_ALPHA,
                       GL_LUMINANCE4_ALPHA4,             GL_LUMINANCE6_ALPHA2,
                       GL_LUMINANCE8_ALPHA8,            GL_LUMINANCE12_ALPHA4,
                       GL_LUMINANCE12_ALPHA12,         GL_LUMINANCE16_ALPHA16,
                       GL_R3_G3_B2,   GL_RGB,   GL_RGB4,   GL_RGB5,   GL_RGB8,
                       GL_RGB10,   GL_RGB12,   GL_RGB16,   GL_RGBA,  GL_RGBA2,
                       GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12,
                       or GL_RGBA16.

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

DESCRIPTION

       When GL_HISTOGRAM 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  GL_HISTOGRAM,  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
       initialized to zero.  The values in the previous  histogram  table,  if
       any,  are  lost.   If  sink is GL_TRUE, 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  target  is  GL_PROXY_HISTOGRAM,  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  GL_ARB_imaging  is  returned   when
       glGetString is called with an argument of GL_EXTENSIONS.

ERRORS

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

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

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

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

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

ASSOCIATED GETS

       glGetHistogramParameter

SEE ALSO

       glGetHistogram(3G), glResetHistogram(3G)

                                                               GLHISTOGRAM(3G)