GLGETHISTOGRAMEXT(3GL)GLGETHISTOGRAMEXT(3GL)NAME
glGetHistogramEXT, glGetHistogramParameterivEXT, glGetHistogramParame‐
terfvEXT. - gets histogram image and histogram related parameters
C SPECIFICATION
void glGetHistogramEXT ( GLenum target,
GLboolean reset,
GLenum format,
GLenum type,
GLvoid *values)
PARAMETERS
target The target histogram to be queried for the histogram image.
Must be GL_HISTOGRAM_EXT.
reset Specifies whether or not to reset the histogram image compo‐
nents that have been queried. Must be GL_TRUE or GL_FALSE.
format Format the caller wants the histogram returned in. Must be one
of GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA,
GL_ABGR_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA.
type Data type the caller wants the histogram returned in. Must be
one of GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT,
GL_INT, GL_UNSIGNED_INT, or GL_FLOAT.
value
Pointer to area of memory large enough to contain the returned
histogram image. (Should have width*num_format_components*
sizeof(type) bytes. The value of width is the same that was
used when defining the current histogram with a call to glHis‐
togramEXT.)
C SPECIFICATION
void glGetHistogramParameterivEXT ( GLenum target,
GLenum pname,
GLint* params)
void glGetHistogramParameterfvEXT ( GLenum target,
GLenum pname,
GLfloat* params)
PARAMETERS
target The target histogram to be queried. Must be GL_HIS‐
TOGRAM_EXT or GL_PROXY_HISTOGRAM_EXT.
pname Parameter name. Must be one of GL_HISTOGRAM_WIDTH_EXT,
GL_HISTOGRAM_FORMAT_EXT, GL_HISTOGRAM_RED_SIZE_EXT,
GL_HISTOGRAM_GREEN_SIZE_EXT, GL_HIS‐
TOGRAM_BLUE_SIZE_EXT, GL_HISTOGRAM_ALPHA_SIZE_EXT,
GL_HISTOGRAM_LUMINANCE_SIZE_EXT, or GL_HIS‐
TOGRAM_SINK_EXT.
params Pointer to a single integer or floating point memory
location to contain the retrieved value.
DESCRIPTION
glGetHistogramEXT, glGetHistogramParameterivEXT and glGetHistogramPara‐
meterivEXT are part of the EXT_histogram extension, which defines his‐
togram and minmax operations at a fixed location in the pixel transfer
pipeline after convolution and post convolution colortable.
The current contents of the histogram tables are queried using glGetH‐
istogramEXT. <target> must be GL_HISTOGRAM_EXT. <format> must be one of
GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_ABGR_EXT,
GL_LUMINANCE, or GL_LUMINANCE_ALPHA. <type> must be GL_UNSIGNED_BYTE,
GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or
GL_FLOAT. A 1-dimensional image with the same width as the histogram is
returned to <values>. No pixel transfer operations are performed on
this image, but pixel storage modes that are applicable to ReadPixels
are performed. Color components that are requested in the specified
<format>, but which are not included in the internal format of the his‐
togram, are returned as zero. The assignments of internal color compo‐
nents to the components requested by <format> are:
Internal Component Resulting Component
__________________________________________
red red
green green
blue blue
alpha alpha
luminance red
__________________________________________
<reset> is either GL_TRUE or GL_FALSE. If GL_TRUE, each component
counter that is actually returned is reset to zero. Counters that are
not returned are not modified.
The query functions glGetHistogramParameterivEXT and glGetHistogramPa‐
rameterfvEXT are provided to retrieve that state of the current defini‐
tion of the current histogram, which were set with the call to glHis‐
togramEXT. The <target> must be GL_HISTOGRAM_EXT or GL_PROXY_HIS‐
TOGRAM_EXT. The <pname> is one of GL_HISTOGRAM_FORMAT_EXT, GL_HIS‐
TOGRAM_WIDTH_EXT, GL_HISTOGRAM_RED_SIZE_EXT, GL_HIS‐
TOGRAM_GREEN_SIZE_EXT, GL_HISTOGRAM_BLUE_SIZE_EXT, GL_HIS‐
TOGRAM_ALPHA_SIZE_EXT, GL_HISTOGRAM_LUMINANCE_SIZE_EXT, or GL_HIS‐
TOGRAM_SINK_EXT. The value of the specified parameter is returned in
<params>.
Alternate sets of partial histogram state are defined for the proxy
histogram GL_PROXY_HISTOGRAM_EXT. Specifically, GL_HISTOGRAM_WIDTH_EXT,
GL_HISTOGRAM_FORMAT, GL_HISTOGRAM_RED_SIZE_EXT, GL_HIS‐
TOGRAM_GREEN_SIZE_EXT, GL_HISTOGRAM_BLUE_SIZE_EXT, GL_HIS‐
TOGRAM_ALPHA_SIZE_EXT, and GL_HISTOGRAM_LUMINANCE_SIZE_EXT are main‐
tained for the proxy histogram. When glHistogramEXT is called with
<target> set to GL_PROXY_HISTOGRAM_EXT, these proxy state values are
always recomputed and updated, even if the histogram is too large to
actually be used. If the histogram is too large, all of these state
variables are set to zero. If the histogram could be accommodated by
Histogram called with <target> GL_HISTOGRAM_EXT, these values are set
as though GL_HISTOGRAM_EXT were being defined. All of these state val‐
ues can be queried with glGetHistogramParameterivEXT or glGetHistogram‐
ParameterfvEXT with <target> set to GL_PROXY_HISTOGRAM_EXT. Calling
glHistogramEXT with <target> GL_PROXY_HISTOGRAM_EXT has no effect on
the actual histogram.
There is no image associated with GL_PROXY_HISTOGRAM_EXT. Therefore
GL_PROXY_HISTOGRAM_EXT cannot be used as a histogram, and its image
must never be queried using glGetHistogramEXT. (The error
GL_INVALID_ENUM results if this is attempted.)
NOTES
Doing a query using glGetHistogramParameterivEXT or glGetHistogramPara‐
meterfvEXT with the <target> set to GL_PROXY_HISTOGRAM_EXT and <pname>
set to GL_HISTOGRAM_SINK_EXT will generate an error GL_INVALID_ENUM.
GL_HISTOGRAM_SINK_EXT only applies to the <target> GL_HISTOGRAM_EXT.
glGetHistogramEXT, glGetHistogramParameterivEXT, glGetHistogramParame‐
terfvEXT are not included in display lists. They are executed immedi‐
ately when called.
ERRORS
GL_INVALID_ENUM is generated if glGetHistogramEXT parameter <format> is
not GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_ABGR_EXT,
GL_LUMINANCE, or GL_LUMINANCE_ALPHA.
GL_INVALID_ENUM is generated if glGetHistogramEXT parameter <type> is
not GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.
GL_INVALID_ENUM is generated if glGetHistogramParameterivEXT or glGetH‐
istogramParameterfvEXT parameter <target> is not GL_HISTOGRAM_EXT or
GL_PROXY_HISTOGRAM_EXT.
GL_INVALID_ENUM is generated if glGetHistogramParameterivEXT or glGetH‐
istogramParameterfvEXT parameter <pname> is not GL_HISTOGRAM_FOR‐
MAT_EXT, GL_HISTOGRAM_WIDTH_EXT, GL_HISTOGRAM_RED_SIZE_EXT, GL_HIS‐
TOGRAM_GREEN_SIZE_EXT, GL_HISTOGRAM_BLUE_SIZE_EXT, GL_HIS‐
TOGRAM_ALPHA_SIZE_EXT, GL_HISTOGRAM_LUMINANCE_SIZE_EXT, or GL_HIS‐
TOGRAM_SINK_EXT. GL_INVALID_ENUM is also generated if glGetHistogramPa‐
rameterivEXT or glGetHistogramParameterfvEXT parameter <target> speci‐
fies the proxy histogram and <pname> specifies a piece of state which
is not maintained for the proxy histogram.
GL_INVALID_OPERATION is generated if glGetHistogramEXT, glGetHis‐
togramParameterivEXT, or glGetHistogramParameterfvEXT are called
between execution of glBegin and the corresponding execution of glEnd.
ASSOCIATED CALLS
glHistogramEXT and glResetHistogramEXT.
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 GLGETHISTOGRAMEXT(3GL)
