upstream-man-pages/man2/xhtml/glHistogram.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glHistogram</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glHistogram"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glHistogram — define histogram table</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glHistogram</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">internalformat</var>, </td></tr><tr><td> </td><td>GLboolean  </td><td><var class="pdparam">sink</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
   4                     The histogram whose parameters are to be set.
   5                     Must be one of
   6                     <code class="constant">GL_HISTOGRAM</code> or
   7                     <code class="constant">GL_PROXY_HISTOGRAM</code>.
   8                 </p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>
   9                     The number of entries in the histogram table.  Must be a power of 2.
  10                 </p></dd><dt><span class="term"><em class="parameter"><code>internalformat</code></em></span></dt><dd><p>
  11                     The format of entries in the histogram table.
  12                     Must be one of
  13                     <code class="constant">GL_ALPHA</code>,
  14                     <code class="constant">GL_ALPHA4</code>,
  15                     <code class="constant">GL_ALPHA8</code>,
  16                     <code class="constant">GL_ALPHA12</code>,
  17                     <code class="constant">GL_ALPHA16</code>,
  18                     <code class="constant">GL_LUMINANCE</code>,
  19                     <code class="constant">GL_LUMINANCE4</code>,
  20                     <code class="constant">GL_LUMINANCE8</code>,
  21                     <code class="constant">GL_LUMINANCE12</code>,
  22                     <code class="constant">GL_LUMINANCE16</code>,
  23                     <code class="constant">GL_LUMINANCE_ALPHA</code>,
  24                     <code class="constant">GL_LUMINANCE4_ALPHA4</code>,
  25                     <code class="constant">GL_LUMINANCE6_ALPHA2</code>,
  26                     <code class="constant">GL_LUMINANCE8_ALPHA8</code>,
  27                     <code class="constant">GL_LUMINANCE12_ALPHA4</code>,
  28                     <code class="constant">GL_LUMINANCE12_ALPHA12</code>,
  29                     <code class="constant">GL_LUMINANCE16_ALPHA16</code>,
  30                     <code class="constant">GL_R3_G3_B2</code>,
  31                     <code class="constant">GL_RGB</code>,
  32                     <code class="constant">GL_RGB4</code>,
  33                     <code class="constant">GL_RGB5</code>,
  34                     <code class="constant">GL_RGB8</code>,
  35                     <code class="constant">GL_RGB10</code>,
  36                     <code class="constant">GL_RGB12</code>,
  37                     <code class="constant">GL_RGB16</code>,
  38                     <code class="constant">GL_RGBA</code>,
  39                     <code class="constant">GL_RGBA2</code>,
  40                     <code class="constant">GL_RGBA4</code>,
  41                     <code class="constant">GL_RGB5_A1</code>,
  42                     <code class="constant">GL_RGBA8</code>,
  43                     <code class="constant">GL_RGB10_A2</code>,
  44                     <code class="constant">GL_RGBA12</code>, or
  45                     <code class="constant">GL_RGBA16</code>.
  46                 </p></dd><dt><span class="term"><em class="parameter"><code>sink</code></em></span></dt><dd><p>
  47                     If <code class="constant">GL_TRUE</code>, pixels will be consumed by the histogramming
  48                     process and no drawing or texture loading will take place.
  49                     If <code class="constant">GL_FALSE</code>, pixels will proceed to the minmax process after
  50                     histogramming.
  51                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  52             When <code class="constant">GL_HISTOGRAM</code> is enabled, RGBA color components are converted to
  53             histogram table indices by clamping to the range [0,1], multiplying by
  54             the width of the histogram table, and rounding to the nearest integer.
  55             The table entries selected by the RGBA indices are then incremented.
  56             (If the internal format of the histogram table includes luminance, then
  57             the index derived from the R color component determines the luminance
  58             table entry to be incremented.)  If a histogram table entry is incremented
  59             beyond its maximum value, then its value becomes undefined.  (This is
  60             not an error.)
  61         </p><p>
  62             Histogramming is performed only for RGBA pixels (though these may
  63             be specified originally as color indices and converted to RGBA by
  64             index table lookup).
  65             Histogramming is enabled with <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and disabled with <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a>.
  66         </p><p>
  67             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_HISTOGRAM</code>, <code class="function">glHistogram</code> redefines the current
  68             histogram table to have <em class="parameter"><code>width</code></em> entries of the format specified by
  69             <em class="parameter"><code>internalformat</code></em>.
  70             The entries are indexed 0 through
  71             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  72
  73                 <mml:mrow>
  74                     <mml:mi mathvariant="italic">width</mml:mi>
  75                     <mml:mo>-</mml:mo>
  76                     <mml:mn>1</mml:mn>
  77                 </mml:mrow>
  78             </mml:math>,
  79             and
  80             all entries are initialized to zero.
  81             The values in the previous histogram table, if any, are lost.
  82             If <em class="parameter"><code>sink</code></em> is <code class="constant">GL_TRUE</code>, then pixels are discarded after histogramming;
  83             no further processing of the pixels takes place, and no drawing,
  84             texture loading, or pixel readback will result.
  85         </p><p>
  86             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_PROXY_HISTOGRAM</code>, <code class="function">glHistogram</code> computes all
  87             state information as if the histogram table were to be redefined,
  88             but does not actually define the new table.
  89             If the requested histogram table is too large to be supported, then the
  90             state information will be set to zero.
  91             This provides a way to determine if a histogram table with the given
  92             parameters can be supported.
  93         </p><p>
  94         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  95             <code class="function">glHistogram</code> is present only if <code class="code">ARB_imaging</code> is returned when <a class="citerefentry" href="glGetString.xml"><span class="citerefentry"><span class="refentrytitle">glGetString</span></span></a>
  96             is called with an argument of <code class="constant">GL_EXTENSIONS</code>.
  97         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  98             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not one of the allowable
  99             values.
 100         </p><p>
 101             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em> is less than zero or is
 102             not a power of 2.
 103         </p><p>
 104             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>internalformat</code></em> is not one of the
 105             allowable values.
 106         </p><p>
 107             <code class="constant">GL_TABLE_TOO_LARGE</code> is generated if <em class="parameter"><code>target</code></em> is <code class="constant">GL_HISTOGRAM</code>
 108             and the histogram table specified is too large for the implementation.
 109         </p><p>
 110             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glHistogram</code> is executed
 111             between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding
 112             execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 113         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 114             <a class="citerefentry" href="glGetHistogramParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetHistogramParameter</span></span></a>
 115         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 116             <a class="citerefentry" href="glGetHistogram.xml"><span class="citerefentry"><span class="refentrytitle">glGetHistogram</span></span></a>,
 117             <a class="citerefentry" href="glResetHistogram.xml"><span class="citerefentry"><span class="refentrytitle">glResetHistogram</span></span></a>
 118         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 119             Copyright <span class="trademark"></span>© 1991-2006
 120             Silicon Graphics, Inc. This document is licensed under the SGI
 121             Free Software B License. For details, see
 122             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 123         </p></div></div></body></html>