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 torus and view it from different angles. The most efficient way to do this would be to store the torus in a display list. Then whenever you want to change the view, you would change the modelview matrix and execute the display list to draw the torus. Example 7-1 illustrates this.

Example 7-1 : Creating a Display List: torus.c

#include <GL/gl.h>

#include <GL/glu.h>

#include <stdio.h>

#include <math.h>

#include <GL/glut.h>

#include <stdlib.h>

GLuint theTorus;

/* Draw a torus */

static void torus(int numc, int numt)

{

   int i, j, k;

   double s, t, x, y, z, twopi;

   twopi = 2 * (double)M_PI;

   for (i = 0; i < numc; i++) {

      glBegin(GL_QUAD_STRIP);

      for (j = 0; j <= numt; j++) {

         for (k = 1; k >= 0; k--) {

            s = (i + k) % numc + 0.5;

            t = j % numt;

            x = (1+.1*cos(s*twopi/numc))*cos(t*twopi/numt);

            y = (1+.1*cos(s*twopi/numc))*sin(t*twopi/numt);

            z = .1 * sin(s * twopi / numc);

            glVertex3f(x, y, z);

         }

      }

      glEnd();

   }

}

/* Create display list with Torus and initialize state*/

static void init(void)

{

   theTorus = glGenLists (1);

   glNewList(theTorus, GL_COMPILE);

   torus(8, 25);

   glEndList();

   glShadeModel(GL_FLAT);

   glClearColor(0.0, 0.0, 0.0, 0.0);

}

void display(void)

{

   glClear(GL_COLOR_BUFFER_BIT);

   glColor3f (1.0, 1.0, 1.0);

   glCallList(theTorus);

   glFlush();

}

void reshape(int w, int h)

{

   glViewport(0, 0, (GLsizei) w, (GLsizei) h);

   glMatrixMode(GL_PROJECTION);

   glLoadIdentity();

   gluPerspective(30, (GLfloat) w/(GLfloat) h, 1.0, 100.0);

   glMatrixMode(GL_MODELVIEW);

   glLoadIdentity();

   gluLookAt(0, 0, 10, 0, 0, 0, 0, 1, 0);

}

/* Rotate about x-axis when "x" typed; rotate about y-axis

   when "y" typed; "i" returns torus to original view */

void keyboard(unsigned char key, int x, int y)

{

   switch (key) {

   case `x':

   case `X':

      glRotatef(30.,1.0,0.0,0.0);

      glutPostRedisplay();

      break;

   case `y':

   case `Y':

      glRotatef(30.,0.0,1.0,0.0);

      glutPostRedisplay();

      break;

   case `i':

   case `I':

      glLoadIdentity();

      gluLookAt(0, 0, 10, 0, 0, 0, 0, 1, 0);

      glutPostRedisplay();

      break;

   case 27:

      exit(0);

      break;

   }

}

int main(int argc, char **argv)

{

   glutInitWindowSize(200, 200);

   glutInit(&argc, argv);

   glutInitDisplayMode(GLUT_SINGLE | GLUT_RGB);

   glutCreateWindow(argv[0]);

   init();

   glutReshapeFunc(reshape);

   glutKeyboardFunc(keyboard);

   glutDisplayFunc(display);

   glutMainLoop();

   return 0;

}

Let's start by looking at init(). It creates a display list for the torus and initializes the viewing matrices and other rendering state. Note that the routine for drawing a torus (torus()) is bracketed by glNewList() and glEndList(), which defines a display list. The argument listName for glNewList() is an integer index, generated by glGenLists(), that uniquely identifies this display list.

The user can rotate the torus about the x- or y-axis by pressing the `x' or `y' key when the window has focus. Whenever this happens, the callback function keyboard() is called, which concatenates a 30-degree rotation matrix (about the x- or y-axis) with the current modelview matrix. Then glutPostRedisplay() is called, which will cause glutMainLoop() to call display() and render the torus after other events have been processed. When the `i' key is pressed, keyboard() restores the initial modelview matrix and returns the torus to its original location.

The display() function is very simple: It clears the window and then calls glCallList() to execute the commands in the display list. If we hadn't used display lists, display() would have to reissue the commands to draw the torus each time it was called.

A display list contains only OpenGL commands. In Example 7-1, only the glBegin(), glVertex(), and glEnd() calls are stored in the display list. The parameters for the calls are evaluated, and their values are copied into the display list when it is created. All the trigonometry to create the torus is done only once, which should increase rendering performance. However, the values in the display list can't be changed later. And once a command has been stored in a list it is not possible to remove it. Neither can you add any new commands to the list after it has been defined. You can delete the entire display list and create a new one, but you can't edit it.

Note: Display lists also work well with GLU commands, since those operations are ultimately broken down into low-level OpenGL commands, which can easily be stored in display lists. Use of display lists with GLU is particularly important for optimizing performance of GLU tessellators and NURBS.