OpenGL 3.x Deprecations

This document describes the OpenGL 3.x (and above) deprecation model and attempts to provide advice on how to migrate your (PyOpenGL) code to be OpenGL 3.1 "legacy free" or "forward compatible".

Note, however, that most vendors have committed to providing legacy-compatible drivers for all of their products, so it is unlikely that you need to rewrite old code, though you should consider using legacy-free operations for new code.

Background

The OpenGL 3.0 specification has for the first time introduced the concept of deprecations to the OpenGL API. Before this, OpenGL has never before deprecated any entry point in close to 17 years of development.

Originally it was intended that OpenGL 3.0 would be a "hard break" with previous OpenGL versions that would allow for a sleek and simple API for game-engine developers, sacrificing the "newbie friendliness" of the legacy API in order to better match the behaviour of modern GPU hardware. (This was the "Longs Peak" proposal, which had been eagerly awaited by the few remaining OpenGL game developers.)

The ARB, however did not implement the "Longs Peak" proposal in OpenGL 3.0, instead introducing just a set of deprecations which includes almost all of the original OpenGL API, including most entry points that OpenGL users have seen as "characterizing" the API such as those related to individual vertices and display-list behaviour. With OpenGL 3.1+ these APIs will only be available upon loading of the legacy extension.

The deprecated APIs are often referred to as "legacy" APIs, while "forward compatible" or "legacy free" is used to describe those APIs which are part of the OpenGL 3.1 subset. You should not be using legacy APIs in new code, but as noted above, the major vendors have committed to supporting the legacy APIs for the foreseeable future.

For more background, you may wish to view the PyCon 2009 presentation on the topic (note, however, that this was before the vendors committed to supporting the legacy API).

Changes Required

The biggest changes you will likely need to accomplish in order to be legacy free:

If you have any per-vertex rendering code, you will need to convert it to array-based rendering. You can safely do this for all current video cards, as array-based rendering has been standard since OpenGL 1.1

Once you have done this, it is a trivial change to begin using Vertex Buffer Objects (VBOs), which usage is required by OpenGL 3.1 and provides a significant performance win for most non-streaming array usage.
The actual change to arrays will normally slow down display-list-based code, but when then converted to VBO usage the performance will normally be better than display-list performance

If you use display lists, you will need to stop using them and convert to array-based geometry
If you are using the individual quad anti-pattern for fonts/sprites, you will need to recode, likely as arrays/shaders

This is the pattern where you push a matrix, transform, draw a quad, pop the matrix (repeating for each quad)
Use a buffer, a per-vertex set of offsets (and a shader to apply textures to them if you can)
Use a "texture atlas" to pack your textures into a single OpenGL texture and use up to maximum-textures enabled on the back-end so that you can maximize the number of textures being drawn per-call

You will need to calculate your own transformation matrices.

We may wind up providing a C extension to make this more efficient for PyOpenGL code.

You will need to begin using shaders, and eventually convert to only using shaders (rather than legacy OpenGL shading/texturing)

Tools

PyOpenGL includes a flag OpenGL.FORWARD_COMPATIBLE_ONLY, which this flag is set to True before importing OpenGL.GL then the OpenGL.GL entry points which are not forward compatible are disabled and will raise OpenGL.error.NullFunctionError exceptions on any attempt to call them.

import OpenGL
OpenGL.FORWARD_COMPATIBLE_ONLY = True
from OpenGL.GL import *
from OpenGL.GLU import *
...

You would normally only set the flag once you've finished what you believe to be your whole conversion, to check that you've cleaned up all of the entry points.

Note that this flag does not attempt to disable GLU, GLUT, GLE or GLX functions which are deprecated, as we don't currently know which of those entry points will be deprecated and which will be re-implemented.