A display list is simply a group of GL commands and arguments that has been stored for subsequent execution. The GL may be instructed to process a particular display list (possibly repeatedly) by providing a number that uniquely specifies it. Doing so causes the commands within the list to be executed just as if they were given normally. The only exception pertains to commands that rely upon client state. When such a command is accumulated into the display list (that is, when issued, not when executed), the client state in effect at that time applies to the command. Only server state is affected when the command is executed. As always, pointers which are passed as arguments to commands are dereferenced when the command is issued. (Vertex array pointers are dereferenced when the commands ArrayElement , DrawArrays , or DrawElements are accumulated into a display list.)
A display list is begun by calling
void NewList ( uint n, enum mode ) ;
n is a positive integer to which the display list that follows is assigned, and mode is a symbolic constant that controls the behavior of the GL during display list creation. If mode is COMPILE, then commands are not executed as they are placed in the display list. If mode is COMPILE_AND_EXECUTE then commands are executed as they are encountered, then placed in the display list. If , then the error INVALID_VALUE is generated.
After calling NewList all subsequent GL commands are placed in the display list (in the order the commands are issued) until a call to
void EndList ( void ) ;
occurs, after which the GL returns to its normal command execution state. It is only when EndList occurs that the specified display list is actually associated with the index indicated with NewList . The error INVALID_OPERATION is generated if EndList is called without a previous matching NewList , or if NewList is called a second time before calling EndList . The error OUT_OF_MEMORY is generated if EndList is called and the specified display list cannot be stored because insufficient memory is available. In this case GL implementations of revision 1.1 or greater insure that no change is made to the previous contents of the display list, if any, and that no other change is made to the GL state, except for the state changed by execution of GL commands when the display list mode is COMPILE_AND_EXECUTE.
Once defined, a display list is executed by calling
void CallList ( uint n ) ;
n gives the index of the display list to be called. This causes the commands saved in the display list to be executed, in order, just as if they were issued without using a display list. If , then the error INVALID_VALUE is generated.
void CallLists ( sizei n, enum type, void *lists ) ;
provides an efficient means for executing a number of display lists. n is an integer indicating the number of display lists to be called, and *lists is a pointer that points to an array of offsets. Each offset is constructed as determined by *lists as follows. First, type may be one of the constants BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT, UNSIGNED_INT, or FLOAT indicating that the array pointed to by *lists is an array of bytes, unsigned bytes, shorts, unsigned shorts, integers, unsigned integers, or floats, respectively. In this case each offset is found by simply converting each array element to an integer (floating point values are truncated). Further, type may be one of 2_BYTES, 3_BYTES, or 4_BYTES, indicating that the array contains sequences of 2, 3, or 4 unsigned bytes, in which case each integer offset is constructed according to the following algorithm:
b is 2, 3, or 4, as indicated by type. If n=0, CallLists does nothing.
Each of the n constructed offsets is taken in order and added to a display list base to obtain a display list number. For each number, the indicated display list is executed. The base is set by calling
void ListBase ( uint base ) ;
to specify the offset.
Indicating a display list index that does not correspond to any display list has no effect. CallList or CallLists may appear inside a display list. (If the mode supplied to NewList is COMPILE_AND_EXECUTE, then the appropriate lists are executed, but the CallList or CallLists , rather than those lists' constituent commands, is placed in the list under construction.) To avoid the possibility of infinite recursion resulting from display lists calling one another, an implementation dependent limit is placed on the nesting level of display lists during display list execution. This limit must be at least 64.
Two commands are provided to manage display list indices.
uint GenLists ( sizei s ) ;
returns an integer n such that the indices are previously unused (i.e. there are s previously unused display list indices starting at n). GenLists also has the effect of creating an empty display list for each of the indices , so that these indices all become used. GenLists returns 0 if there is no group of s contiguous previously unused display list indices, or if s=0.
boolean IsList ( uint list ) ;
returns TRUE if list is the index of some display list.
A contiguous group of display lists may be deleted by calling
void DeleteLists ( uint list, sizei range ) ;
where list is the index of the first display list to be deleted and range is the number of display lists to be deleted. All information about the display lists is lost, and the indices become unused. Indices to which no display list corresponds are ignored. If , nothing happens.
Certain commands, when called while compiling a display list, are not compiled into the display list but are executed immediately. These are: IsList , GenLists , DeleteLists , FeedbackBuffer , SelectBuffer , RenderMode , VertexPointer , NormalPointer , ColorPointer , IndexPointer , TexCoordPointer , EdgeFlagPointer , InterleavedArrays , EnableClientState , DisableClientState , PushClientAttrib , PopClientAttrib , ReadPixels , PixelStore , GenTextures , DeleteTextures , AreTexturesResident , IsTexture , Flush , Finish , as well as IsEnabled and all of the Get commands (see Chapter 6). TexImage2D is executed immediately only when the target argument is PROXY_TEXTURE_2D, and TexImage1D is executed immediatedly only when the target argument is PROXY_TEXTURE_1D.
Display lists require one bit of state to indicate whether a GL command should be executed immediately or placed in a display list. In the initial state, commands are executed immediately. If the bit indicates display list creation, an index is required to indicate the current display list being defined. Another bit indicates, during display list creation, whether or not commands should be executed as they are compiled into the display list. One integer is required for the current ListBase setting; its initial value is zero. Finally, state must be maintained to indicate which integers are currently in use as display list indices. In the initial state, no indices are in use.