ModernGL

5.12.0 · active · verified Tue Apr 14

ModernGL is a high-performance Python wrapper over OpenGL Core, simplifying the creation of graphics applications like scientific simulations, games, or user interfaces. It aims to provide a more Pythonic and less boilerplate-heavy API compared to direct OpenGL bindings like PyOpenGL. The current stable version is 5.12.0, with releases occurring periodically, often including breaking changes.

Warnings

breaking Python 3.7 support was removed in ModernGL 5.9.0. Ensure your environment uses Python 3.8 or newer.
Fix: Upgrade Python to version 3.8 or higher.
breaking Global constants (e.g., `moderngl.BLEND`, `moderngl.DEPTH_TEST`, `moderngl.CULL_FACE`) were moved to the `Context` object in version 5.9.0. Direct access to these from the `moderngl` module will raise an `AttributeError`.
Fix: Access these constants directly from the `Context` instance, e.g., `ctx.BLEND` instead of `moderngl.BLEND`.
gotcha ModernGL context creation (`moderngl.create_context()`) requires an existing OpenGL context (e.g., from a windowing library) or the `standalone=True` flag for headless rendering. Incorrect setup is a common source of errors.
Fix: If integrating with a window, ensure `create_context()` is called after the window's OpenGL context is active. For headless use, always pass `standalone=True`. Consider `moderngl-window` for simplified window management.
gotcha Shader compilation errors, especially with compute shaders, can sometimes lead to silent crashes without clear Python exceptions. This can be due to insufficient OpenGL version support or driver issues.
Fix: When creating a context, explicitly require the necessary OpenGL version, e.g., `ctx = moderngl.create_context(standalone=True, require=430)` for compute shaders. Check shader source for syntax errors.
gotcha OpenGL resources (buffers, textures, programs) should be created once during initialization and reused. Creating them repeatedly (e.g., in a rendering loop) leads to severe performance degradation and memory leaks.
Fix: Allocate all ModernGL objects at program startup or when resources are first needed, and store references for reuse. Release them when no longer required or at program termination.
gotcha When rendering transparent objects with depth testing and blending enabled, objects must be drawn in a specific order (typically back-to-front relative to the camera) to ensure correct blending results. Incorrect order leads to visual artifacts.
Fix: Sort transparent objects by depth before rendering. Consider alternative blending techniques if sorting is not feasible for complex scenes.

Install

pip install moderngl Install stable version

Imports

moderngl
```
import moderngl
```
create_context
```
from moderngl import create_context
```
get_context
```
from moderngl import get_context
```
BLEND
```
ctx.BLEND
```
Constants like BLEND, DEPTH_TEST, etc., were moved from the top-level module to the Context object in version 5.9.0.

Quickstart

This quickstart demonstrates creating a ModernGL context (headless in this example), allocating a buffer on the GPU, writing data to it, and reading it back. For graphical applications, `moderngl.create_context()` would typically be called after setting up a window with an OpenGL-capable library.

import moderngl

# Create a headless context or attach to an existing one
# For a windowed application, ctx = moderngl.create_context()
# after a window is created by a library like Pygame, GLFW, etc.
ctx = moderngl.create_context(standalone=True)

# Create a buffer on the GPU
buf = ctx.buffer(b"Hello ModernGL World!")

# Read data back from the buffer
print(buf.read())

# Release resources (important for standalone contexts)
# For windowed contexts, resource management is often handled by the windowing library.
ctx.release()

view raw JSON →