OpenGL Programming Guide

Chapter 4Display Lists

Creating and Executing a Display List

Executing a Display List

After you've created a display list, you can execute it by calling glCallList(). Naturally, you can execute the same display list many times, and you can mix calls to execute display lists with calls to perform immediate-mode graphics, as you've already seen. void glCallList (GLuint list);

This routine executes the display list specified by list. The commands in the display list are executed in the order they were saved, just as if they were issued without using a display list. If list hasn't been defined, nothing happens.

Since a display list can contain calls that change the value of OpenGL state variables, these values change as the display list is executed, just as if the commands were called in immediate mode. The changes to OpenGL state persist after execution of the display list is completed. In Example 4-2 , the changes to the current color and current matrix made during the execution of the display list remain in effect after it's been called, as shown in Example 4-3 .

Example 4-3 : Persistence of State Changes after Execution of a Display List

glNewList(listIndex,GL_COMPILE);
   glColor3f(1.0, 0.0, 0.0);
   glBegin(GL_POLYGON);
      glVertex2f(0.0,0.0);
      glVertex2f(1.0,0.0);
      glVertex2f(0.0,1.0);
   glEnd();
   glTranslatef(1.5,0.0,0.0);
glEndList();

Sometimes you want state changes to persist, but other times you want to save the values of state variables before executing a display list and then restore these values after the list has executed. Use glPushAttrib() to save a group of state variables and glPopAttrib() to restore the values when you're ready for them. (See Appendix B for more information about these commands.) To save and restore the current matrix, use glPushMatrix() and glPopMatrix() as described in "Manipulating the Matrix Stacks." To restore the state variables in Example 4-3 , you might use the code shown in Example 4-4 .

Example 4-4 : Restoring State Variables within a Display List

glNewList(listIndex,GL_COMPILE);
   glPushMatrix();
   glPushAttrib(GL_CURRENT_BIT);
      glColor3f(1.0, 0.0, 0.0);
      glBegin(GL_POLYGON);
         glVertex2f(0.0,0.0);
         glVertex2f(1.0,0.0);
         glVertex2f(0.0,1.0);
      glEnd();
   glTranslatef(1.5,0.0,0.0);
   glPopAttrib();
   glPopMatrix();
glEndList();

Thus, if you used this kind of a display list that restores values, the code in Example 4-5 would draw a green, untranslated line. With the display list in Example 4-3 that doesn't save and restore values, the line drawn would be red, and its position would be translated.

Example 4-5 : Using a Display List That Restores State Variables

void display(void)
{
    GLint i;

    glClear (GL_COLOR_BUFFER_BIT);
    glColor3f(0.0, 1.0, 0.0);
    for (i = 0; i < 10; i++)
      glCallList (listIndex);
    drawLine ();
    glFlush ();
}

You can call glCallList() from anywhere within a program, as long as its OpenGL context is still active. A display list can be created in one routine and executed in a different one, since its index uniquely identifies it. Also, there is no facility to save the contents of a display list into a data file, nor a facility to create a display list from a file. In this sense, a display list is designed for temporary use. Also, a display list is destroyed when its OpenGL context is destroyed.

OpenGL Programming Guide