PyOpenGL and PyOpenGL_Accelerate

PyOpenGL is normally distributed via PyPI using standard pip:

$ pip install PyOpenGL PyOpenGL_accelerate

You can install this repository by branching/cloning and running pip:

$ cd pyopengl
$ pip install -e .
$ cd accelerate
$ pip install -e .

Note that to compile PyOpenGL_accelerate you will need to have a functioning Python extension-compiling environment.

Learning PyOpenGL

If you are new to PyOpenGL, you likely want to start with the OpenGLContext tutorial page. Those tutorials require OpenGLContext, (which is a big wrapper including a whole scenegraph engine, VRML97 parser, lots of demos, etc) you can install that with:

$ pip2.7 install "OpenGLContext-full==3.1.1"

Or you can clone it (including the tutorial sources) with:

$ git clone https://github.com/mcfletch/openglcontext.git

or (for GitHub usage):

$ git clone https://github.com/mcfletch/pyopengl.git

The documentation pages are useful for looking up the parameters and semantics of PyOpenGL calls.

Running Tests

You can run the PyOpenGL test suite from a source-code checkout, the easiest way to run the tests with the uv runner:

• git (for the checkout)
• GLUT (FreeGLUT)
• GLExtrusion library (libgle)
• GLU (normally available on any OpenGL-capable machine)
• [uv](https://docs.astral.sh/uv/)

Running the test suite from a top-level checkout looks like:

$ uv run --with tox,tox-uv tox

The result being a lot of tests being run in a matrix of environments. All of the environments will pull in glfw, some will also pull in numpy. Some will have accelerate, and some will not.

Test Suite Concerns

The test suite takes a long time to complete due to the matrix of supported configurations; it will open many windows, so it will be difficult to interact with your machine's keyboard as it runs.

On a powerful linux machine a single test run when uv has already cached all dependencies is around 90s (i.e. just for actually running the tests). There is a matrix of 6 python versions, 2 numpy conditions, and 2 acceleration conditions for around 40 minutes to run the full tox suite if you already have all dependencies built and cached.

You can run parallel test suites with tox's -p flag, but beware that you can crash your desktop that way.

The glfw window generally will not proceed if your Wayland session has locked or is otherwise preventing display of the windows.

You can set TEST_VISIBLE=false in your environment and many of the tests will run "headless" (i.e. will not create an on-screen display):

$ TEST_VISIBLE=false uv run --with tox,tox-uv tox

there are, however, a number of tests which do not respect this flag (mostly the test_checks.py suite which runs out-of-process scripts), for those which do the speedup and ergonimic improvement is considerable.

You can control the inter-test pause (dwell time) by setting the environment variable TEST_DWELL to a floating point value. Note that there is no point having a long dwell on non-visible runs, since the rendered frames will not be visible to you anyway.

You can use the pygame context for many test cases, to do so:

$ TEST_WINDOWING=pygame uv run --with tox,tox-uv tox

Keep in mind that pygame versions for python3.9 often do not support Wayland desktops.

The TEST_WINDOWING flag selects the windowing backend used by the tests/gl, tests/gles and tests/glu suites:

• glfw (the default) and pygame create an on-screen window. On a desktop these render on your GPU; inside a container whose compositor is software-rendered they will use llvmpipe regardless of the GPU present.

• egl is a headless backend that renders directly on a GPU through the EGL_EXT_platform_device extension, with no window system at all:

  $ TEST_WINDOWING=egl uv run --with tox,tox-uv tox
  

  This is the right choice for CI / containers (e.g. with the NVIDIA container runtime), where it reaches the real GPU even though the on-screen path would fall back to llvmpipe. It forces PYOPENGL_PLATFORM=egl and serves both desktop OpenGL and OpenGL-ES contexts via an offscreen pbuffer; because there is no window, TEST_VISIBLE and the inter-test dwell do not apply. By default it picks the first non-software EGL device; set TEST_EGL_DEVICE=<n> to pin a specific device index. The legacy root-level tests/*.py have no headless equivalent and fall back to a windowed backend under this setting.