_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ $Date$ $Revision$
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_header(CallLists,execute a list of display lists)
_names(CallLists)
.SH PARAMETERS
_phead(_param1)
Specifies the number of display lists to be executed.
_phead(_param2)
Specifies the type of values in _param3.
Symbolic constants
_const(BYTE),
_const(UNSIGNED_BYTE),
_const(SHORT),
_const(UNSIGNED_SHORT),
_const(INT),
_const(UNSIGNED_INT),
_const(FLOAT),
_const(2_BYTES),
_const(3_BYTES), and
_const(4_BYTES) are accepted.
_phead(_param3)
Specifies the address of an array of name offsets in the display list.
The pointer type is void because the offsets can be bytes,
shorts,
ints,
or floats,
depending on the value of _param2.
.SH DESCRIPTION
_cmnd causes each display list in the list of names passed as _param3
to be executed.
As a result,
the commands saved in each display list are executed in order,
just as if they were called without using a display list.
Names of display lists that have not been defined are ignored.
.P
_cmnd provides an efficient means for executing more than one display list.
_param2 allows lists with various name formats to be accepted.
The formats are as follows:
.TP 25
_const(BYTE)
_param3 is treated as an array of signed bytes,
each in the range \-128 through 127.
.TP
_const(UNSIGNED_BYTE)
_param3 is treated as an array of unsigned bytes,
each in the range 0 through 255.
.TP
_const(SHORT)
_param3 is treated as an array of signed two-byte integers,
each in the range \-32768 through 32767.
.TP
_const(UNSIGNED_SHORT)
_param3 is treated as an array of unsigned two-byte integers,
each in the range 0 through 65535.
.TP
_const(INT)
_param3 is treated as an array of signed four-byte integers.
.TP
_const(UNSIGNED_INT)
_param3 is treated as an array of unsigned four-byte integers.
.TP
_const(FLOAT)
_param3 is treated as an array of four-byte floating-point values.
.TP
_const(2_BYTES)
_param3 is treated as an array of unsigned bytes.
Each pair of bytes specifies a single display-list name.
The value of the pair is computed as 256 times the unsigned value
of the first byte plus the unsigned value of the second byte.
.TP
_const(3_BYTES)
_param3 is treated as an array of unsigned bytes.
Each triplet of bytes specifies a single display-list name.
The value of the triplet is computed as 65536 times the unsigned value
of the first byte,
plus 256 times the unsigned value of the second byte,
plus the unsigned value of the third byte.
.TP
_const(4_BYTES)
_param3 is treated as an array of unsigned bytes.
Each quadruplet of bytes specifies a single display-list name.
The value of the quadruplet is computed as 16777216 times the unsigned value 
of the first byte,
plus 65536 times the unsigned value of the second byte,
plus 256 times the unsigned value of the third byte,
plus the unsigned value of the fourth byte.
.P
The list of display-list names is not null-terminated.
Rather,
_param1 specifies how many names are to be taken from _param3.
.P
An additional level of indirection is made available with the
_cmnd(ListBase) command,
which specifies an unsigned offset that is added to each display-list
name specified in _param3 before that display list is executed.
.P
_cmnd can appear inside a display list.
To avoid the possibility of infinite recursion resulting from display lists
calling one another,
a limit is placed on the nesting level of display
lists during display-list execution.
This limit must be at least 64, and it depends on the implementation.
.P
GL state is not saved and restored across a call to _cmnd.
Thus,
changes made to GL state during the execution of the display lists
remain after execution is completed.
Use _cmnd(PushAttrib),
_cmnd(PopAttrib),
_cmnd(PushMatrix),
and _cmnd(PopMatrix) to preserve GL state across _cmnd calls.
.SH NOTES
Display lists can be executed between a call to _cmnd(Begin)
and the corresponding call to _cmnd(End),
as long as the display list includes only commands that are allowed
in this interval.
.SH ERRORS
_const(INVALID_VALUE) is generated if _param1 is negative.
.P
_const(INVALID_ENUM) is generated if _param2 is not one of 
_const(BYTE),
_const(UNSIGNED_BYTE),
_const(SHORT),
_const(UNSIGNED_SHORT),
_const(INT),
_const(UNSIGNED_INT),
_const(FLOAT),
_const(2_BYTES),
_const(3_BYTES),
_const(4_BYTES).
.SH ASSOCIATED GETS
_cmnd(Get) with argument _const(LIST_BASE)
.br
_cmnd(Get) with argument _const(MAX_LIST_NESTING)
.br
_cmnd(IsList)
.SH SEE ALSO
_cmnd(CallList),
_cmnd(DeleteLists),
_cmnd(GenLists),
_cmnd(ListBase),
_cmnd(NewList),
_cmnd(PushAttrib), 
.br
_cmnd(PushMatrix)
