upstream-doc/man2/glCallLists.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="glCallLists">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCallLists</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCallLists</refname>
  17         <refpurpose>execute a list of display lists</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCallLists</function></funcdef>
  23                 <paramdef>GLsizei <parameter>n</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  25                 <paramdef>const GLvoid * <parameter>lists</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>n</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies the number of display lists to be executed.
  36                 </para>
  37             </listitem>
  38         </varlistentry>
  39         <varlistentry>
  40             <term><parameter>type</parameter></term>
  41             <listitem>
  42                 <para>
  43                     Specifies the type of values in <parameter>lists</parameter>.
  44                     Symbolic constants
  45                     <constant>GL_BYTE</constant>,
  46                     <constant>GL_UNSIGNED_BYTE</constant>,
  47                     <constant>GL_SHORT</constant>,
  48                     <constant>GL_UNSIGNED_SHORT</constant>,
  49                     <constant>GL_INT</constant>,
  50                     <constant>GL_UNSIGNED_INT</constant>,
  51                     <constant>GL_FLOAT</constant>,
  52                     <constant>GL_2_BYTES</constant>,
  53                     <constant>GL_3_BYTES</constant>, and
  54                     <constant>GL_4_BYTES</constant> are accepted.
  55                 </para>
  56             </listitem>
  57         </varlistentry>
  58         <varlistentry>
  59             <term><parameter>lists</parameter></term>
  60             <listitem>
  61                 <para>
  62                     Specifies the address of an array of name offsets in the display list.
  63                     The pointer type is void because the offsets can be bytes,
  64                     shorts,
  65                     ints,
  66                     or floats,
  67                     depending on the value of <parameter>type</parameter>.
  68                 </para>
  69             </listitem>
  70         </varlistentry>
  71         </variablelist>
  72     </refsect1>
  73     <refsect1 id="description"><title>Description</title>
  74         <para>
  75             <function>glCallLists</function> causes each display list in the list of names passed as <parameter>lists</parameter>
  76             to be executed.
  77             As a result,
  78             the commands saved in each display list are executed in order,
  79             just as if they were called without using a display list.
  80             Names of display lists that have not been defined are ignored.
  81         </para>
  82         <para>
  83             <function>glCallLists</function> provides an efficient means for executing more than one display list.
  84             <parameter>type</parameter> allows lists with various name formats to be accepted.
  85             The formats are as
  86             follows:
  87         </para>
  88         <variablelist>
  89             <varlistentry>
  90                 <term><constant>GL_BYTE</constant></term>
  91                 <listitem>
  92                     <para>
  93                         <parameter>lists</parameter> is treated as an array of signed bytes,
  94                         each in the range
  95                         <inlineequation><mml:math>
  96                             <!-- eqn: -128:-->
  97                             <mml:mn>-128</mml:mn>
  98                         </mml:math></inlineequation>
  99                         through 127.
 100                     </para>
 101                 </listitem>
 102             </varlistentry>
 103             <varlistentry>
 104                 <term><constant>GL_UNSIGNED_BYTE</constant></term>
 105                 <listitem>
 106                     <para>
 107                         <parameter>lists</parameter> is treated as an array of unsigned bytes,
 108                         each in the range 0 through 255.
 109                     </para>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term><constant>GL_SHORT</constant></term>
 114                 <listitem>
 115                     <para>
 116                         <parameter>lists</parameter> is treated as an array of signed two-byte integers,
 117                         each in the range
 118                         <inlineequation><mml:math>
 119                             <!-- eqn: -32768:-->
 120                             <mml:mn>-32768</mml:mn>
 121                         </mml:math></inlineequation>
 122                         through 32767.
 123                     </para>
 124                 </listitem>
 125             </varlistentry>
 126             <varlistentry>
 127                 <term><constant>GL_UNSIGNED_SHORT</constant></term>
 128                 <listitem>
 129                     <para>
 130                         <parameter>lists</parameter> is treated as an array of unsigned two-byte integers,
 131                         each in the range 0 through 65535.
 132                     </para>
 133                 </listitem>
 134             </varlistentry>
 135             <varlistentry>
 136                 <term><constant>GL_INT</constant></term>
 137                 <listitem>
 138                     <para>
 139                         <parameter>lists</parameter> is treated as an array of signed four-byte integers.
 140                     </para>
 141                 </listitem>
 142             </varlistentry>
 143             <varlistentry>
 144                 <term><constant>GL_UNSIGNED_INT</constant></term>
 145                 <listitem>
 146                     <para>
 147                         <parameter>lists</parameter> is treated as an array of unsigned four-byte integers.
 148                     </para>
 149                 </listitem>
 150             </varlistentry>
 151             <varlistentry>
 152                 <term><constant>GL_FLOAT</constant></term>
 153                 <listitem>
 154                     <para>
 155                         <parameter>lists</parameter> is treated as an array of four-byte floating-point values.
 156                     </para>
 157                 </listitem>
 158             </varlistentry>
 159             <varlistentry>
 160                 <term><constant>GL_2_BYTES</constant></term>
 161                 <listitem>
 162                     <para>
 163                         <parameter>lists</parameter> is treated as an array of unsigned bytes.
 164                         Each pair of bytes specifies a single display-list name.
 165                         The value of the pair is computed as 256 times the unsigned value
 166                         of the first byte plus the unsigned value of the second byte.
 167                     </para>
 168                 </listitem>
 169             </varlistentry>
 170             <varlistentry>
 171                 <term><constant>GL_3_BYTES</constant></term>
 172                 <listitem>
 173                     <para>
 174                         <parameter>lists</parameter> is treated as an array of unsigned bytes.
 175                         Each triplet of bytes specifies a single display-list name.
 176                         The value of the triplet is computed as 65536 times the unsigned value
 177                         of the first byte,
 178                         plus 256 times the unsigned value of the second byte,
 179                         plus the unsigned value of the third byte.
 180                     </para>
 181                 </listitem>
 182             </varlistentry>
 183             <varlistentry>
 184                 <term><constant>GL_4_BYTES</constant></term>
 185                 <listitem>
 186                     <para>
 187                         <parameter>lists</parameter> is treated as an array of unsigned bytes.
 188                         Each quadruplet of bytes specifies a single display-list name.
 189                         The value of the quadruplet is computed as 16777216 times the unsigned value
 190                         of the first byte,
 191                         plus 65536 times the unsigned value of the second byte,
 192                         plus 256 times the unsigned value of the third byte,
 193                         plus the unsigned value of the fourth byte.
 194                     </para>
 195                 </listitem>
 196             </varlistentry>
 197         </variablelist>
 198         <para>
 199             The list of display-list names is not null-terminated.
 200             Rather,
 201             <parameter>n</parameter> specifies how many names are to be taken from <parameter>lists</parameter>.
 202         </para>
 203         <para>
 204             An additional level of indirection is made available with the
 205             <citerefentry><refentrytitle>glListBase</refentrytitle></citerefentry> command,
 206             which specifies an unsigned offset that is added to each display-list
 207             name specified in <parameter>lists</parameter> before that display list is executed.
 208         </para>
 209         <para>
 210             <function>glCallLists</function> can appear inside a display list.
 211             To avoid the possibility of infinite recursion resulting from display lists
 212             calling one another,
 213             a limit is placed on the nesting level of display
 214             lists during display-list execution.
 215             This limit must be at least 64, and it depends on the implementation.
 216         </para>
 217         <para>
 218             GL state is not saved and restored across a call to <function>glCallLists</function>.
 219             Thus,
 220             changes made to GL state during the execution of the display lists
 221             remain after execution is completed.
 222             Use <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
 223             <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>,
 224             <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
 225             and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to preserve GL state across <function>glCallLists</function> calls.
 226         </para>
 227     </refsect1>
 228     <refsect1 id="notes"><title>Notes</title>
 229         <para>
 230             Display lists can be executed between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 231             and the corresponding call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
 232             as long as the display list includes only commands that are allowed
 233             in this interval.
 234         </para>
 235     </refsect1>
 236     <refsect1 id="errors"><title>Errors</title>
 237         <para>
 238             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter> is negative.
 239         </para>
 240         <para>
 241             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of
 242             <constant>GL_BYTE</constant>,
 243             <constant>GL_UNSIGNED_BYTE</constant>,
 244             <constant>GL_SHORT</constant>,
 245             <constant>GL_UNSIGNED_SHORT</constant>,
 246             <constant>GL_INT</constant>,
 247             <constant>GL_UNSIGNED_INT</constant>,
 248             <constant>GL_FLOAT</constant>,
 249             <constant>GL_2_BYTES</constant>,
 250             <constant>GL_3_BYTES</constant>,
 251             <constant>GL_4_BYTES</constant>.
 252         </para>
 253     </refsect1>
 254     <refsect1 id="associatedgets"><title>Associated Gets</title>
 255         <para>
 256             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LIST_BASE</constant>
 257         </para>
 258         <para>
 259             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_LIST_NESTING</constant>
 260         </para>
 261         <para>
 262             <citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>
 263         </para>
 264     </refsect1>
 265     <refsect1 id="seealso"><title>See Also</title>
 266         <para>
 267             <citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
 268             <citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
 269             <citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>,
 270             <citerefentry><refentrytitle>glListBase</refentrytitle></citerefentry>,
 271             <citerefentry><refentrytitle>glNewList</refentrytitle></citerefentry>,
 272             <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>,
 273             <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>
 274         </para>
 275     </refsect1>
 276     <refsect1 id="Copyright"><title>Copyright</title>
 277         <para>
 278             Copyright <trademark class="copyright"></trademark> 1991-2006
 279             Silicon Graphics, Inc. This document is licensed under the SGI
 280             Free Software B License. For details, see
 281             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 282         </para>
 283     </refsect1>
 284 </refentry>