OpenGL Programming Guide

Chapter 4Display Lists

Creating and Executing a Display List

As you've already seen, glNewList() and glEndList() are used to begin and end the definition of a display list, which is then invoked by supplying its identifying index with glCallList(). In Example 4-2 , a display list is created in the makeList() routine. This display list contains OpenGL commands to draw a red triangle. Then, in the display() routine, the display list is executed ten times. In addition, a line is drawn in immediate mode. Note that the display list allocates memory to store the commands and the values of any necessary variables.

Example 4-2 : Using a Display List: list.c

#include <GL/gl.h>
#include <GL/glu.h>
#include "aux.h"

GLuint listName = 1;

void myinit (void)
{
glNewList (listName, GL_COMPILE);
        glColor3f(1.0, 0.0, 0.0);
        glBegin (GL_TRIANGLES);
            glVertex2f (0.0, 0.0);
            glVertex2f (1.0, 0.0);
            glVertex2f (0.0, 1.0);
        glEnd ();
        glTranslatef (1.5, 0.0, 0.0);
    glEndList ();
    glShadeModel (GL_FLAT);
}

void drawLine (void)
{
    glBegin (GL_LINES);
        glVertex2f (0.0, 0.5);
        glVertex2f (15.0, 0.5);
    glEnd ();
}

void display(void)
{
    GLuint i;
    glClear (GL_COLOR_BUFFER_BIT);
    glColor3f(0.0, 1.0, 0.0);
    for (i = 0; i < 10; i++)
        glCallList (listName);
    drawLine ();
    glFlush ();
}

void myReshape(GLsizei w, GLsizei h)
{
    glViewport(0, 0, w, h);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    if (w <= h) 
        gluOrtho2D (0.0, 2.0, -0.5 * (GLfloat) h/(GLfloat) w, 
              1.5 * (GLfloat) h/(GLfloat) w);
    else 
        gluOrtho2D (0.0, 2.0 * (GLfloat) w/(GLfloat) h, -0.5,
              1.5); 
    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity();
}


int main(int argc, char** argv)
{
    auxInitDisplayMode (AUX_SINGLE | AUX_RGBA);
    auxInitPosition (0, 0, 400, 50);
    auxInitWindow (argv[0]);
    myinit ();
    auxReshapeFunc (myReshape);
    auxMainLoop(display);
}

The glTranslatef() routine in the display list alters the position of the next object to be drawn. Without it, calling the display list twice would just draw the triangle on top of itself. The drawLine() routine, which is called in immediate mode, is also affected by the ten glTranslatef() calls that precede it. Thus, if you call transformation commands within a display list, don't forget to take the effect of those commands into account later in your program.

Only one display list can be created at a time. In other words, you must eventually follow glNewList() with glEndList() to end the creation of a display list before starting another one. As you might expect, calling glEndList() without having started a display list generates the error GL_INVALID_OPERATION. void glNewList (GLuint list, GLenum mode);

Specifies the start of a display list. OpenGL routines that are called subsequently (until glEndList() is called to end the display list) are stored in a display list, except for a few restricted OpenGL routines that can't be stored. (Those restricted routines are executed immediately, during the creation of the display list.) The list parameter is a unique positive integer that identifies the display list. The possible values for the mode parameter are GL_COMPILE and GL_COMPILE_AND_EXECUTE. Use GL_COMPILE if you don't want the following OpenGL commands executed as they're placed in the display list; to cause the commands to be executed immediately as well as placed in the display list for later use, specify GL_COMPILE_AND_EXECUTE.

void glEndList (void);

Marks the end of a display list.

What's Stored in a Display List
Executing a Display List
Hierarchical Display Lists

OpenGL Programming Guide