139 lines
4.3 KiB
Plaintext
139 lines
4.3 KiB
Plaintext
|
'\" te
|
||
|
|
'\"! tbl|eqn | mmdoc
|
||
|
|
'\"macro stdmacro
|
||
|
|
.ds Vn Version 1.2
|
||
|
|
.ds Dt 24 September 1999
|
||
|
|
.ds Re Release 1.2.1
|
||
|
|
.ds Dp Jan 14 18:30
|
||
|
|
.ds Dm 01 histogram
|
||
|
|
.ds Xs 13152 6 histogram.gl
|
||
|
|
.TH GLHISTOGRAM 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glHistogram
|
||
|
|
\- define histogram table
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glHistogram\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglHistogram( 'u
|
||
|
|
GLsizei \fIwidth\fP,
|
||
|
|
GLenum \fIinternalformat\fP,
|
||
|
|
GLboolean \fIsink\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP \w'\fIinternalformat\fP\ \ 'u
|
||
|
|
\f2target\fP
|
||
|
|
The histogram whose parameters are to be set.
|
||
|
|
Must be one of
|
||
|
|
\%\f3GL_HISTOGRAM\fP or
|
||
|
|
\%\f3GL_PROXY_HISTOGRAM\fP.
|
||
|
|
.TP
|
||
|
|
\f2width\fP
|
||
|
|
The number of entries in the histogram table. Must be a power of 2.
|
||
|
|
.TP
|
||
|
|
\f2internalformat\fP
|
||
|
|
The of entries in the histogram table.
|
||
|
|
Must be one of
|
||
|
|
\%\f3GL_ALPHA\fP,
|
||
|
|
\%\f3GL_ALPHA4\fP,
|
||
|
|
\%\f3GL_ALPHA8\fP,
|
||
|
|
\%\f3GL_ALPHA12\fP,
|
||
|
|
\%\f3GL_ALPHA16\fP,
|
||
|
|
\%\f3GL_LUMINANCE\fP,
|
||
|
|
\%\f3GL_LUMINANCE4\fP,
|
||
|
|
\%\f3GL_LUMINANCE8\fP,
|
||
|
|
\%\f3GL_LUMINANCE12\fP,
|
||
|
|
\%\f3GL_LUMINANCE16\fP,
|
||
|
|
\%\f3GL_LUMINANCE_ALPHA\fP,
|
||
|
|
\%\f3GL_LUMINANCE4_ALPHA4\fP,
|
||
|
|
\%\f3GL_LUMINANCE6_ALPHA2\fP,
|
||
|
|
\%\f3GL_LUMINANCE8_ALPHA8\fP,
|
||
|
|
\%\f3GL_LUMINANCE12_ALPHA4\fP,
|
||
|
|
\%\f3GL_LUMINANCE12_ALPHA12\fP,
|
||
|
|
\%\f3GL_LUMINANCE16_ALPHA16\fP,
|
||
|
|
\%\f3GL_R3_G3_B2\fP,
|
||
|
|
\%\f3GL_RGB\fP,
|
||
|
|
\%\f3GL_RGB4\fP,
|
||
|
|
\%\f3GL_RGB5\fP,
|
||
|
|
\%\f3GL_RGB8\fP,
|
||
|
|
\%\f3GL_RGB10\fP,
|
||
|
|
\%\f3GL_RGB12\fP,
|
||
|
|
\%\f3GL_RGB16\fP,
|
||
|
|
\%\f3GL_RGBA\fP,
|
||
|
|
\%\f3GL_RGBA2\fP,
|
||
|
|
\%\f3GL_RGBA4\fP,
|
||
|
|
\%\f3GL_RGB5_A1\fP,
|
||
|
|
\%\f3GL_RGBA8\fP,
|
||
|
|
\%\f3GL_RGB10_A2\fP,
|
||
|
|
\%\f3GL_RGBA12\fP, or
|
||
|
|
\%\f3GL_RGBA16\fP.
|
||
|
|
.TP
|
||
|
|
\f2sink\fP
|
||
|
|
If \%\f3GL_TRUE\fP, pixels will be consumed by the histogramming
|
||
|
|
process and no drawing or texture loading will take place.
|
||
|
|
If \%\f3GL_FALSE\fP, pixels will proceed to the minmax process after
|
||
|
|
histogramming.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
When \%\f3GL_HISTOGRAM\fP 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.)
|
||
|
|
.PP
|
||
|
|
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 \%\f3glEnable\fP and disabled with \%\f3glDisable\fP.
|
||
|
|
.PP
|
||
|
|
When \f2target\fP is \%\f3GL_HISTOGRAM\fP, \%\f3glHistogram\fP redefines the current
|
||
|
|
histogram table to have \f2width\fP entries of the specified by
|
||
|
|
\f2internalformat\fP.
|
||
|
|
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 \f2sink\fP is \%\f3GL_TRUE\fP, then pixels are discarded after histogramming;
|
||
|
|
no further processing of the pixels takes place, and no drawing,
|
||
|
|
texture loading, or pixel readback will result.
|
||
|
|
.PP
|
||
|
|
When \f2target\fP is \%\f3GL_PROXY_HISTOGRAM\fP, \%\f3glHistogram\fP 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.
|
||
|
|
.PP
|
||
|
|
.SH NOTES
|
||
|
|
\%\f3glHistogram\fP is present only if \%\f3GL_ARB_imaging\fP is returned when \%\f3glGetString\fP
|
||
|
|
is called with an argument of \%\f3GL_EXTENSIONS\fP.
|
||
|
|
.SH ERRORS
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP is not one of the allowable
|
||
|
|
values.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2width\fP is less than zero or is
|
||
|
|
not a power of 2.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2internalformat\fP is not one of the
|
||
|
|
allowable values.
|
||
|
|
.P
|
||
|
|
\%\f3GL_TABLE_TOO_LARGE\fP is generated if \f2target\fP is \%\f3GL_HISTOGRAM\fP
|
||
|
|
and the histogram table specified is too large for the implementation.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glHistogram\fP is executed
|
||
|
|
between the execution of \%\f3glBegin\fP and the corresponding
|
||
|
|
execution of \%\f3glEnd\fP.
|
||
|
|
.SH ASSOCIATED GETS
|
||
|
|
\%\f3glGetHistogramParameter\fP
|
||
|
|
.SH SEE ALSO
|
||
|
|
\%\f3glGetHistogram(3G)\fP,
|
||
|
|
\%\f3glResetHistogram(3G)\fP
|