OpenGL Programming Guide

Chapter 4Display Lists

An Example of Using a Display List

A display list is a convenient and efficient way to name and organize a set of OpenGL commands. For example, suppose you want to draw a circle with 100 line segments. Without using display lists, you might write immediate-mode code like this:

drawCircle()
{
   GLint i;
   GLfloat cosine, sine;

   glBegin(GL_POLYGON);
      for(i=0;i<100;i++){
         cosine=cos(i*2*PI/100.0);
         sine=sin(i*2*PI/100.0);
         glVertex2f(cosine,sine);
      }
   glEnd();
}

This method is terribly inefficient because the trigonometry has to be performed each time the circle is rendered. Instead, you could save the coordinates in a table, and then pull the coordinates out of the table as needed:

drawCircle()
{
   GLint i;
   GLfloat cosine, sine;
   static GLfloat circoords[100][2];
   static GLint inited=0;

   if(inited==0){
      inited=1;
      for(i=0;i<100;i++){
         circcoords[i][0]=cos(i*2*PI/100.0);
         circcoords[i][1]=sin(i*2*PI/100.0);
      }
   }
   glBegin(GL_POLYGON);
      for(i=0;i<100;i++)
         glVertex2fv(&circcoords[i][0]);
   glEnd();
}

Even with this improved method, you still incur a slight penalty from incrementing and testing the variable i. What you really want to do is draw the circle once and have OpenGL remember how to draw it for later use. This is exactly what a display list is for, as shown in Example 4-1 .

Example 4-1 : Creating a Display List

#define MY_CIRCLE_LIST 1

buildCircle()
{
   GLint i;
   GLfloat cosine, sine;

   glNewList(MY_CIRCLE_LIST, GL_COMPILE);
      glBegin(GL_POLYGON);
         for(i=0;i<100;i++){
            cosine=cos(i*2*PI/100.0);
            sine=sin(i*2*PI/100.0);
            glVertex2f(cosine,sine);
         }
      glEnd();
   glEndList();
}

Note that the code for drawing a circle is bracketed by glNewList() and glEndList(). As you might have guessed, these commands define a display list. The argument MY_CIRCLE_LIST for glNewList() is an integer index that uniquely identifies this display list. You can execute the display list later with this glCallList() command:

glCallList(MY_CIRCLE_LIST);

A display list contains only OpenGL calls. Other calls - in Example 4-1 , the C functions cos() and sin() - aren't stored in the display list. Instead, the coordinates and other variables (such as array contents) are evaluated and copied into the display list with the values they have when the list is compiled. After such a list has been compiled, these values can't be changed. You can delete a display list and create a new one, but you can't edit an existing display list.

OpenGL Programming Guide