Specific Problems and Troubleshooting

Specific Problems and Troubleshooting

This section looks at some specific problems frequently encountered by OpenGL users. Note that one generally useful approach is to experiment with an ogldebug trace of the first few frames. See "Creating a Trace File to Discover OpenGL Problems" .

Blank Window

A common problem encountered in graphics programming is a blank window. If you find your display doesn't show what you expected, do the following:

To make sure you're bound to the right window, try clearing the image buffers with glClear(). If you can't clear, you may be bound to the wrong window (or no window at all).
To make sure you're not rendering in the background color, use an unusual color to clear the window with glClear().
To make sure you're not clipping everything inadvertently, temporarily move the near and far clipping planes to extreme distances (such as 0.001 and 1000000.0). (Note that a range like this is totally inappropriate for actual use in a program).
Try backing the viewpoint up to see more of the space.
Check the section "Troubleshooting Transformations" in Chapter 3 of the OpenGL Programming Guide.
Make sure you're using the correct projection matrix.
Remember that glOrtho() and glPerspective() calls multiply onto the current projection matrix; they don't replace it.
In a double-buffered program, make sure you're calling glXSwapBuffers().
Make sure you requested a depth buffer if the program is using depth buffering.
Check the aspect ratio of the viewing frustrum. Don't set up your program using:
GLfloat aspect = event.xconfigure.width/event.xconfigure.height
/* 0 by integer division */

Rotation and Translation Problems

Z axis direction. Remember that by default you start out looking down the negative z axis. Unless you move the viewpoint, objects should have negative z coordinates to be visible.
Rotation. Make sure you've translated back to the origin before rotating (unless you intend to rotate about some other point).
Transformation order. First translating, then rotating an object yields a different result than first rotating, then translating. The order of rotation is also important, for example, R(x), R(y), R(z) is not the same as R(z), R(y), R(x).

Depth Buffering Problems

When your program uses depth testing, be sure to:

Enable depth testing, using glEnable() with a GL_DEPTH_TEST argument--depth testing is off by default. Set the depth function to the desired function, using glDepthFunc() --the default function is GL_LESS.
Request a visual that supports a depth buffer. Note that on some platforms a depth buffer is automatically returned for certain color configuration (for example, RGBA on Indy systems), while on other platforms a depth buffer is only returned when one is specifically requested (RealityEngine systems for example). To guarantee that your program is portable, always ask for a depth buffer explicitly.

Animation Problems

Double-buffering. After drawing to the back buffer, make sure you swap buffers with glXSwapBuffers().
Observing the image during drawing. If you have a performance problem and want to see which part of the image takes the longest to draw, use a single-buffered visual. You can then observe the image as it's drawn. If you don't use resources to control visual selection, call glDrawBuffer() with a GL_FRONT argument before rendering.

Lighting Problems

Turn off specular shading in the early debugging stages. It's harder to visualize where specular highlights should be than where diffuse highlights should be.
For local light sources, try drawing lines from the light source to the object you are trying to light. This helps make sure the spacial and directional nature of the light is right.
Make sure you have both GL_LIGHTING enabled and the appropriate GL_LIGHT#'s enabled.
Try enabling GL_NORMALIZE to see whether normals are being scaled and causing lighting problems. This is particularly important if you call glScale().
Make sure normals are pointing in the right direction.
Make sure the light is actually at the intended position. Positions are affected by the current model-view matrix. Enabling light without any glLight(GL_POSITION) provides a headlight if called before gluLookAt() and so on.

X Window System Problems

X and OpenGL have different notions of the Y direction. X has the origin (0, 0) in the upper left corner of the window; OpenGL has it in the lower left corner. If you try to track the mouse but find that the object is moving in the "wrong" direction vertically, this is probably the cause.
Display lists defined in one context aren't visible to other contexts unless they explicitly share contexts.
glXUseXFont() creates display lists for characters. The display lists are only visible in contexts that share objects with the one they were created in.

Pixel and Texture Write Problems

Make sure the pixel storage mode GL_UNPACK_ALIGNMENT is set to the correct value depending on the type of data. For example:
GLubyte buf[] = {0x9D, ... 0xA7};
/* a lot of bitmap images are passed as bytes! */
glBitmap(w, h, x, y, 0, 0, buf);
The default GL_UNPACK_ALIGNMENT is 4. It should be 1 in the case above.

The same thing applies to textures.

System-Specific Problems

Make sure you don't exceed implementation-specific resource limits such as maximum projection stack depth.
When moving an application from a RealityEngine system to a low-end system, make sure you're not using destination alpha planes. The current low-end machines don't support them.