_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_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_header(NewList,create or replace a display list)
_names(NewList)
.SH PARAMETERS
_phead(_param1)
Specifies the display-list name.
_phead(_param2)
Specifies the compilation mode,
which can be
_const(COMPILE) or
_const(COMPILE_AND_EXECUTE).
_names(EndList)
.SH DESCRIPTION
Display lists are groups of GL commands that have been stored
for subsequent execution.
Display lists are created with _cmnd.
All subsequent commands are placed in the display list,
in the order issued,
until _cmnd(EndList) is called. 
.P
_cmnd has two arguments.
The first argument,
_param1(1),
is a positive integer that becomes the unique name for the display list.
Names can be created and reserved with _cmnd(GenLists)
and tested for uniqueness with _cmnd(IsList).
The second argument,
_param2(1),
is a symbolic constant that can assume one of two values: 
.TP 30
_const(COMPILE)
Commands are merely compiled.
.TP 
_const(COMPILE_AND_EXECUTE)
Commands are executed as they are compiled into the display list.
.P
Certain commands are not compiled into the display list
but are executed immediately,
regardless of the display-list mode.
These commands are
_cmnd(AreTexturesResident),
_cmnd(ColorPointer),
_cmnd(DeleteLists),
_cmnd(DeleteTextures),
_cmnd(DisableClientState),
_cmnd(EdgeFlagPointer),
_cmnd(EnableClientState),
_cmnd(FeedbackBuffer),
_cmnd(Finish),
_cmnd(Flush),
_cmnd(GenLists),
_cmnd(GenTextures),
_cmnd(IndexPointer),
_cmnd(InterleavedArrays),
_cmnd(IsEnabled),
_cmnd(IsList),
_cmnd(IsTexture),
_cmnd(NormalPointer),
_cmnd(PopClientAttrib),
_cmnd(PixelStore),
_cmnd(PushClientAttrib),
_cmnd(ReadPixels),
_cmnd(RenderMode),
_cmnd(SelectBuffer),
_cmnd(TexCoordPointer),
_cmnd(VertexPointer),
and all of the _cmnd(Get) commands.
.P
Similarly, 
_cmnd(TexImage1D), _cmnd(TexImage2D), and _cmnd(TexImage3D)
are executed immediately and not compiled into the display list when their
first argument is _const(PROXY_TEXTURE_1D), _const(PROXY_TEXTURE_1D), or
_const(PROXY_TEXTURE_3D), respectively.
.P
When the _arbstring(imaging) extension is supported,
_cmnd(Histogram) executes immediately when its argument is
_const(PROXY_HISTOGRAM).  Similarly, _cmnd(ColorTable) executes
immediately when its first argument is _cmnd(PROXY_COLOR_TABLE),
_cmnd(PROXY_POST_CONVOLUTION_COLOR_TABLE), or
_cmnd(PROXY_POST_COLOR_MATRIX_COLOR_TABLE).
.P
When the _arbstring(multitexture) extension is supported,
_cmnd(ClientActiveTextureARB) is not compiled into display lists, but
executed immediately.
.P
When _cmnd(EndList) is encountered,
the display-list definition is completed by associating the list
with the unique name _param1(1)
(specified in the _cmnd(NewList) command). 
If a display list with name _param1(1) already exists,
it is replaced only when _cmnd(EndList) is called.
.SH NOTES
_cmnd(CallList) and _cmnd(CallLists) can be entered into display lists.
Commands in the display list or lists executed by _cmnd(CallList)
or _cmnd(CallLists) are not included in the display list being created,
even if the list creation mode is _const(COMPILE_AND_EXECUTE).
.P
A display list is just a group of commands and arguments, so errors
generated by commands in a display list must be generated when the list is
executed. If the list is created in _const(COMPILE) mode, errors are
not generated until the list is executed.
.SH ERRORS
_const(INVALID_VALUE) is generated if _param1(1) is 0.
.P
_const(INVALID_ENUM) is generated if _param2(1) is not an accepted value.
.P
_const(INVALID_OPERATION) is generated if _cmnd(EndList) is called
without a preceding _cmnd(NewList), 
or if _cmnd(NewList) is called while a display list is being defined.
.P
_const(INVALID_OPERATION) is generated if _cmnd(NewList) or _cmnd(EndList)
is executed between the execution of _cmnd(Begin)
and the corresponding execution of _cmnd(End).
.P
_const(OUT_OF_MEMORY) is generated if there is insufficient memory to
compile the display list. If the GL version is 1.1 or greater, no
change is made to the previous contents of the display list, if any,
and no other change is made to the GL state. (It is as if no attempt
had been made to create the new display list.) 
.SH ASSOCIATED GETS
_cmnd(IsList)
.br
_cmnd(Get) with argument _const(LIST_INDEX)
.br
_cmnd(Get) with argument _const(LIST_MODE)
.SH SEE ALSO
_cmnd(CallList),
_cmnd(CallLists),
_cmnd(DeleteLists), 
_cmnd(GenLists)