GLHISTOGRAMEXT(3GL)GLHISTOGRAMEXT(3GL)NAME
glHistogramEXT, glResetHistogramEXT - specify histogram parameters and
reset internal representation of histogram
C SPECIFICATION
void glHistogramEXT ( GLenum target,
GLsizei width,
GLenum internalformat,
GLboolean sink)
PARAMETERS
target The target histogram to be defined. Must be GL_HIS‐
TOGRAM_EXT or GL_PROXY_HISTOGRAM_EXT.
width Width of the histogram. Represents the number of bins
in which the histogram is stored. internalformat The
internal storage format of the histogram. sink Speci‐
fies whether pixel groups will be consumed by the his‐
togram operation (GL_TRUE) or passed on to the minmax
operation (GL_FALSE).
C SPECIFICATION
void glResetHistogramEXT ( GLenum target)
PARAMETERS
target The target histogram to be reset. Must be GL_HISTOGRAM_EXT.
DESCRIPTIONglHistogramEXT and glResetHistogramEXT are part of the EXT_histogram
extension, which defines histogram and minmax operations at a fixed
location in the pixel transfer pipeline after convolution and post con‐
volution colortable.
glResetHistogramEXT resets the internal representation of the histogram
to all zeros.
Histogram is Enabled glEnable(GL_HISTOGRAM_EXT). Use glDisable(GL_HIS‐
TOGRAM_EXT) to disable histogram. Use glIsEnabled(GL_HISTOGRAM_EXT) to
check if histogram is enabled or not.
The width of the histogram must be a power of 2. The maximum width of a
histogram is 65536. If the histogram width is less than zero or is not
a power of 2 then an error is generated (GL_INVALID_VALUE). If the
width is larger than the maximum allowed histogram width, then the
error GL_TABLE_TOO_LARGE_EXT is generated.
The error INVALID_ENUM results if <internalformat> is not one of the
values accepted by the <components> parameter of TexImage2D (as defined
by EXT_texture), except that values 1, 2, 3, 4, INTENSITY_EXT, INTEN‐
SITY4_EXT, INTENSITY8_EXT, INTENSITY12_EXT, and INTENSITY16_EXT are not
accepted.
If no error results from the execution of HistogramEXT, the specified
histogram table is redefined to have <width> entries, each with the
specified internal format. The entries are indexed zero through N-1,
where N is the <width> of the table. Each value in each entry is set to
zero. The values in the previous histogram table, if any, are lost.
Histogram operations are performed only for RGBA pixel groups, though
these groups may have been specified as color indices and converted to
RGBA by index table lookup. If GL_HISTOGRAM_EXT is enabled and the
width of the table is non-zero, and the pixel groups contain RGBA val‐
ues, then indices Ri, Gi, Bi, and Ai are derived from the red, green,
blue, and alpha components of each pixel group (without modifying these
components) by clamping the components to [0,1], multiplying each by
one less than the width of the histogram table, and rounding each to
the nearest integer. If the format of the GL_HISTOGRAM_EXT table
includes red or luminance, the red or luminance component of histogram
entry Ri is incremented by one. If the format of the GL_HISTOGRAM_EXT
table includes green, the green component of histogram entry Gi is
incremented by one. The blue and alpha components of histogram entries
Bi and Ai are incremented in the same way. If a histogram entry compo‐
nent is incremented beyond its maximum value, its value becomes unde‐
fined. (This is not an error.)
By default histogram operation has no effect on the stream of pixel
groups being processed. However, if GL_HISTOGRAM_EXT is enabled and
the histogram <sink> parameter was specified as GL_TRUE then all RGBA
pixel groups are discarded immediately after the histogram operation is
completed. Because histogram precedes minmax, no minmax operation will
be performed. No pixel fragments are generated, no change is made to
texture memory contents, and no pixel values are returned.
The operation of histogram during pixel copy and query operations is
identical to the operation during pixel drawing and texture image defi‐
nition.
NOTESglHistogramEXT with a GL_PROXY_HISTOGRAM_EXT target is not included in
display lists. It is executed immediately when called.
ERRORS
GL_INVALID_ENUM is generated if glHistogramEXT parameter <target> is
not GL_HISTOGRAM_EXT or GL_PROXY_HISTOGRAM_EXT.
GL_INVALID_VALUE is generated if glHistogramEXT parameter <width> is
less than zero or is not a power of 2.
GL_INVALID_ENUM is generated if glHistogramEXT parameter <internalfor‐
mat> is not GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, GL_LUMI‐
NANCE_ALPHA, or one of the tokens defined by the EXT_texture extension.
(Values 1, 2, 3, 4, INTENSITY_EXT, INTENSITY4_EXT, INTENSITY8_EXT,
INTENSITY12_EXT, and INTENSITY16_EXT are not accepted as internal for‐
mats by glHistogramEXT).
GL_TABLE_TOO_LARGE_EXT is generated if glHistogramEXT is called with
parameter <target> of GL_HISTOGRAM_EXT and the histogram as specified
is too large for the implementation.
GL_INVALID_ENUM is generated if glResetHistogramEXT parameter <target>
is not GL_HISTOGRAM_EXT.
GL_INVALID_OPERATION is generated if glHistogramEXT or glResetHis‐
togramEXT is called between execution of glBegin and the corresponding
execution of glEnd.
ASSOCIATED GETS
glGetHistogramEXT, glGetHistogramParameterivEXT, glGetHistogramParame‐
terfvEXT
SEE ALSO
glMinmaxEXT, glResetMinmaxEXT, glGetMinmaxEXT, glGetMinmaxParame‐
terivEXT, glGetMinmaxParameterfvEXT, glDrawPixels, glCopyPixels,
glReadPixels, glTexImage2D, glTexImage3DEXT, glTexSubImage2DEXT,
glCopyTexImage2DEXT, glCopyTexSubImage2DEXT, glGetTexImage, glPixel‐
Tranferf, glPixelTransferi, glEnable, glDisable, glIsEnabled, glPixel‐
Store.
1 Dec 97 GLHISTOGRAMEXT(3GL)