glHistogramEXT(3G)	       OpenGL Reference		    glHistogramEXT(3G)

NAME    [Toc]    [Back]

     glHistogramEXT - define histogram table

C SPECIFICATION    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

     target	     The histogram whose parameters are	to be set.  Must be
		     one of GL_HISTOGRAM_EXT or	GL_PROXY_HISTOGRAM_EXT.

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

     internalformat  The format	of entries in the histogram table.  Must be
		     one of GL_ALPHA, GL_ALPHA4_EXT, GL_ALPHA8_EXT,
		     GL_ALPHA12_EXT, GL_ALPHA16_EXT, GL_LUMINANCE,
		     GL_LUMINANCE4_EXT,	GL_LUMINANCE8_EXT, GL_LUMINANCE12_EXT,
		     GL_LUMINANCE16_EXT, GL_LUMINANCE_ALPHA,
		     GL_LUMINANCE4_ALPHA4_EXT, GL_LUMINANCE6_ALPHA2_EXT,
		     GL_LUMINANCE8_ALPHA8_EXT, GL_LUMINANCE12_ALPHA4_EXT,
		     GL_LUMINANCE12_ALPHA12_EXT, GL_LUMINANCE16_ALPHA16_EXT,
		     GL_RGB, GL_RGB2_EXT, GL_RGB4_EXT, GL_RGB5_EXT,
		     GL_RGB8_EXT, GL_RGB10_EXT,	GL_RGB12_EXT, GL_RGB16_EXT,
		     GL_RGBA, GL_RGBA2_EXT, GL_RGBA4_EXT, GL_RGB5_A1_EXT,
		     GL_RGBA8_EXT, GL_RGB10_A2_EXT, GL_RGBA12_EXT, or
		     GL_RGBA16_EXT.

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

DESCRIPTION    [Toc]    [Back]

     Histogramming is part of the OpenGL pixel transfer	process.  It takes
     place immediately after index lookup.  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 GL_HISTOGRAM_EXT 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 format 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



									Page 1






glHistogramEXT(3G)	       OpenGL Reference		    glHistogramEXT(3G)



     an	error.)

     When target is GL_HISTOGRAM_EXT, glHistogramEXT redefines the current
     histogram table to	have width entries of the format 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_EXT, glHistogramEXT computes all	state
     information as if the histogram table was 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.

     The histogram state information may be queried by calling
     glGetHistogramParameterEXT	with a target of GL_HISTOGRAM_EXT (to obtain
     information for the current histogram table) or GL_PROXY_HISTOGRAM_EXT
     (to obtain	information from the most recent proxy request)	and one	of the
     following values for the pname argument:

    Parameter			      Description
    ___________________________________________________________________________
    GL_HISTOGRAM_WIDTH_EXT	      Histogram	table width
    GL_HISTOGRAM_FORMAT_EXT	      Internal format
    GL_HISTOGRAM_RED_SIZE_EXT	      Red component counter size, in bits
    GL_HISTOGRAM_GREEN_SIZE_EXT	      Green component counter size, in bits
    GL_HISTOGRAM_BLUE_SIZE_EXT	      Blue component counter size, in bits
    GL_HISTOGRAM_ALPHA_SIZE_EXT	      Alpha component counter size, in bits
    GL_HISTOGRAM_LUMINANCE_SIZE_EXT   Luminance	component counter size,	in bits
    GL_HISTOGRAM_SINK_EXT	      Value of the sink	parameter

ERRORS    [Toc]    [Back]

     GL_INVALID_ENUM is	generated if target is not one of the allowable
     values.

     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
     allowable values.

     GL_TABLE_TOO_LARGE_EXT is generated if target is GL_HISTOGRAM_EXT and the
     histogram table specified is too large for	the implementation.

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






									Page 2






glHistogramEXT(3G)	       OpenGL Reference		    glHistogramEXT(3G)

ASSOCIATED GETS    [Toc]    [Back]

     glGetHistogramParameterEXT.


MACHINE	DEPENDENCIES
     On	RealityEngine, RealityEngine2, and VTX systems,	histogram and minmax
     may not be	used when rendering to pixmaps.

SEE ALSO    [Toc]    [Back]

     glGetHistogramEXT,	glResetHistogramEXT.


									PPPPaaaaggggeeee 3333