225 lines
12 KiB
XML
225 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
|
<refentry id="glNewList">
|
|
<refmeta>
|
|
<refmetainfo>
|
|
<copyright>
|
|
<year>1991-2006</year>
|
|
<holder>Silicon Graphics, Inc.</holder>
|
|
</copyright>
|
|
</refmetainfo>
|
|
<refentrytitle>glNewList</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glNewList</refname>
|
|
<refpurpose>create or replace a display list</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glNewList</function></funcdef>
|
|
<paramdef>GLuint <parameter>list</parameter></paramdef>
|
|
<paramdef>GLenum <parameter>mode</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>list</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the display-list name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>mode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the compilation mode,
|
|
which can be
|
|
<constant>GL_COMPILE</constant> or
|
|
<constant>GL_COMPILE_AND_EXECUTE</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glEndList</function></funcdef>
|
|
<paramdef> <parameter>void</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
Display lists are groups of GL commands that have been stored
|
|
for subsequent execution.
|
|
Display lists are created with <function>glNewList</function>.
|
|
All subsequent commands are placed in the display list,
|
|
in the order issued,
|
|
until <citerefentry><refentrytitle>glEndList</refentrytitle></citerefentry> is called.
|
|
</para>
|
|
<para>
|
|
<function>glNewList</function> has two arguments.
|
|
The first argument,
|
|
<parameter>list</parameter>,
|
|
is a positive integer that becomes the unique name for the display list.
|
|
Names can be created and reserved with <citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>
|
|
and tested for uniqueness with <citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>.
|
|
The second argument,
|
|
<parameter>mode</parameter>,
|
|
is a symbolic constant that can assume one of two values:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>GL_COMPILE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Commands are merely compiled.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_COMPILE_AND_EXECUTE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Commands are executed as they are compiled into the display list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
Certain commands are not compiled into the display list
|
|
but are executed immediately,
|
|
regardless of the display-list mode.
|
|
These commands are
|
|
<citerefentry><refentrytitle>glAreTexturesResident</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glDeleteTextures</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glDisableClientState</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glEnableClientState</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glFeedbackBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glIsTexture</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glSelectBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>,
|
|
and all of the <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> commands.
|
|
</para>
|
|
<para>
|
|
Similarly,
|
|
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>
|
|
are executed immediately and not compiled into the display list when their
|
|
first argument is <constant>GL_PROXY_TEXTURE_1D</constant>, <constant>GL_PROXY_TEXTURE_1D</constant>, or
|
|
<constant>GL_PROXY_TEXTURE_3D</constant>, respectively.
|
|
</para>
|
|
<para>
|
|
When the <code>ARB_imaging</code> extension is supported,
|
|
<citerefentry><refentrytitle>glHistogram</refentrytitle></citerefentry> executes immediately when its argument is
|
|
<constant>GL_PROXY_HISTOGRAM</constant>. Similarly, <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry> executes
|
|
immediately when its first argument is <constant>GL_PROXY_COLOR_TABLE</constant>,
|
|
<constant>GL_PROXY_POST_CONVOLUTION_COLOR_TABLE</constant>, or
|
|
<constant>GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
|
|
</para>
|
|
<para>
|
|
For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported,
|
|
<citerefentry><refentrytitle>glClientActiveTexture</refentrytitle></citerefentry> is not compiled into display lists, but
|
|
executed immediately.
|
|
</para>
|
|
<para>
|
|
When <citerefentry><refentrytitle>glEndList</refentrytitle></citerefentry> is encountered,
|
|
the display-list definition is completed by associating the list
|
|
with the unique name <parameter>list</parameter>
|
|
(specified in the <function>glNewList</function> command).
|
|
If a display list with name <parameter>list</parameter> already exists,
|
|
it is replaced only when <citerefentry><refentrytitle>glEndList</refentrytitle></citerefentry> is called.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry> can be entered into display lists.
|
|
Commands in the display list or lists executed by <citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>
|
|
or <citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry> are not included in the display list being created,
|
|
even if the list creation mode is <constant>GL_COMPILE_AND_EXECUTE</constant>.
|
|
</para>
|
|
<para>
|
|
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 <constant>GL_COMPILE</constant> mode, errors are
|
|
not generated until the list is executed.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>list</parameter> is 0.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not an accepted value.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if <citerefentry><refentrytitle>glEndList</refentrytitle></citerefentry> is called
|
|
without a preceding <function>glNewList</function>,
|
|
or if <function>glNewList</function> is called while a display list is being defined.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glNewList</function> or <citerefentry><refentrytitle>glEndList</refentrytitle></citerefentry>
|
|
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
|
|
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
|
|
</para>
|
|
<para>
|
|
<constant>GL_OUT_OF_MEMORY</constant> 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.)
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="associatedgets"><title>Associated Gets</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glIsList</refentrytitle></citerefentry>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LIST_INDEX</constant>
|
|
</para>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LIST_MODE</constant>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glCallList</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glCallLists</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glDeleteLists</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glGenLists</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright <trademark class="copyright"></trademark> 1991-2006
|
|
Silicon Graphics, Inc. This document is licensed under the SGI
|
|
Free Software B License. For details, see
|
|
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|