upstream-man-pages/man2/glColorSubTable.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glColorSubTable">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glColorSubTable</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glColorSubTable</refname>
  17         <refpurpose>respecify a portion of a color table</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glColorSubTable</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLsizei <parameter>start</parameter></paramdef>
  25                 <paramdef>GLsizei <parameter>count</parameter></paramdef>
  26                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  27                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  28                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  29             </funcprototype>
  30         </funcsynopsis>
  31     </refsynopsisdiv>
  32     <refsect1 id="parameters"><title>Parameters</title>
  33         <variablelist>
  34         <varlistentry>
  35             <term><parameter>target</parameter></term>
  36             <listitem>
  37                 <para>
  38                     Must be one of
  39                     <constant>GL_COLOR_TABLE</constant>,
  40                     <constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, or
  41                     <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
  42                 </para>
  43             </listitem>
  44         </varlistentry>
  45         <varlistentry>
  46             <term><parameter>start</parameter></term>
  47             <listitem>
  48                 <para>
  49                     The starting index of the portion of the color table to be replaced.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>count</parameter></term>
  55             <listitem>
  56                 <para>
  57                     The number of table entries to replace.
  58                 </para>
  59             </listitem>
  60         </varlistentry>
  61         <varlistentry>
  62             <term><parameter>format</parameter></term>
  63             <listitem>
  64                 <para>
  65                     The format of the pixel data in <parameter>data</parameter>.
  66                     The allowable values are
  67                     <constant>GL_RED</constant>,
  68                     <constant>GL_GREEN</constant>,
  69                     <constant>GL_BLUE</constant>,
  70                     <constant>GL_ALPHA</constant>,
  71                     <constant>GL_LUMINANCE</constant>,
  72                     <constant>GL_LUMINANCE_ALPHA</constant>,
  73                     <constant>GL_RGB</constant>,
  74                     <constant>GL_BGR</constant>,
  75                     <constant>GL_RGBA</constant>, and
  76                     <constant>GL_BGRA</constant>.
  77                 </para>
  78             </listitem>
  79         </varlistentry>
  80         <varlistentry>
  81             <term><parameter>type</parameter></term>
  82             <listitem>
  83                 <para>
  84                     The type of the pixel data in <parameter>data</parameter>.
  85                     The allowable values are
  86                     <constant>GL_UNSIGNED_BYTE</constant>,
  87                     <constant>GL_BYTE</constant>,
  88                     <constant>GL_UNSIGNED_SHORT</constant>,
  89                     <constant>GL_SHORT</constant>,
  90                     <constant>GL_UNSIGNED_INT</constant>,
  91                     <constant>GL_INT</constant>,
  92                     <constant>GL_FLOAT</constant>,
  93                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
  94                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
  95                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
  96                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
  97                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
  98                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
  99                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 100                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 101                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 102                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 103                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 104                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 105                 </para>
 106             </listitem>
 107         </varlistentry>
 108         <varlistentry>
 109             <term><parameter>data</parameter></term>
 110             <listitem>
 111                 <para>
 112                     Pointer to a one-dimensional array of pixel data that is processed to
 113                     replace the specified region of the color table.
 114                 </para>
 115             </listitem>
 116         </varlistentry>
 117         </variablelist>
 118     </refsect1>
 119     <refsect1 id="description"><title>Description</title>
 120         <para>
 121             <function>glColorSubTable</function> is used to respecify a contiguous portion of a color table previously
 122             defined using <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>.  The pixels referenced by <parameter>data</parameter> replace the
 123             portion of the existing table from indices <parameter>start</parameter> to
 124             <inlineequation><mml:math>
 125                 <!-- eqn: start + count - 1:-->
 126                 <mml:mrow>
 127                     <mml:mi mathvariant="italic">start</mml:mi>
 128                     <mml:mo>+</mml:mo>
 129                     <mml:mi mathvariant="italic">count</mml:mi>
 130                     <mml:mo>-</mml:mo>
 131                     <mml:mn>1</mml:mn>
 132                 </mml:mrow>
 133             </mml:math></inlineequation>,
 134             inclusive.  This region may not include any
 135             entries outside the range of the color table as it was originally specified.
 136             It is not an error to specify a subtexture with width of 0, but such a
 137             specification has no effect.
 138         </para>
 139         <para>
 140             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 141             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a portion of a color table is
 142             respecified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 143         </para>
 144     </refsect1>
 145     <refsect1 id="notes"><title>Notes</title>
 146         <para>
 147             <function>glColorSubTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
 148             is called with an argument of <constant>GL_EXTENSIONS</constant>.
 149         </para>
 150         <para>
 151         </para>
 152     </refsect1>
 153     <refsect1 id="errors"><title>Errors</title>
 154         <para>
 155             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
 156             values.
 157         </para>
 158         <para>
 159             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
 160             values.
 161         </para>
 162         <para>
 163             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
 164             values.
 165         </para>
 166         <para>
 167             <constant>GL_INVALID_VALUE</constant> is generated if
 168             <inlineequation><mml:math>
 169                 <!-- eqn: start + count > width:-->
 170                 <mml:mrow>
 171                     <mml:mrow>
 172                         <mml:mi mathvariant="italic">start</mml:mi>
 173                         <mml:mo>+</mml:mo>
 174                         <mml:mi mathvariant="italic">count</mml:mi>
 175                     </mml:mrow>
 176                     <mml:mo>&gt;</mml:mo>
 177                     <mml:mi mathvariant="italic">width</mml:mi>
 178                 </mml:mrow>
 179             </mml:math></inlineequation>.
 180         </para>
 181         <para>
 182             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 183             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 184         </para>
 185         <para>
 186             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 187             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 188             object such that the memory reads required would exceed the data store size.
 189         </para>
 190         <para>
 191             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 192             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 193             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 194         </para>
 195         <para>
 196             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorSubTable</function> is executed
 197             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 198             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 199         </para>
 200     </refsect1>
 201     <refsect1 id="associatedgets"><title>Associated Gets</title>
 202         <para>
 203             <citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>,
 204             <citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
 205         </para>
 206         <para>
 207             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 208         </para>
 209     </refsect1>
 210     <refsect1 id="seealso"><title>See Also</title>
 211         <para>
 212             <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
 213             <citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>,
 214             <citerefentry><refentrytitle>glCopyColorTable</refentrytitle></citerefentry>,
 215             <citerefentry><refentrytitle>glCopyColorSubTable</refentrytitle></citerefentry>,
 216             <citerefentry><refentrytitle>glGetColorTable</refentrytitle></citerefentry>
 217         </para>
 218     </refsect1>
 219     <refsect1 id="Copyright"><title>Copyright</title>
 220         <para>
 221             Copyright <trademark class="copyright"></trademark> 1991-2006
 222             Silicon Graphics, Inc. This document is licensed under the SGI
 223             Free Software B License. For details, see
 224             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 225         </para>
 226     </refsect1>
 227 </refentry>