OpenGLContext Documentation

Installation

OpenGLContext needs Python 3.10 or newer. Install it and its core dependencies (NumPy, PyOpenGL, Pillow, PyVRML97, TTFQuery, SimpleParse, PyDispatcher, pygltflib, omi_audio and omi_physics) from PyPI:

pip install OpenGLContext

Optional extras pull in the pieces you need for particular features:

OpenGLContext[glfw] -- the GLFW backend (recommended for core-profile and PBR rendering)
OpenGLContext[draco] -- Draco-compressed glTF geometry (pulls in DracoPy). The glTF loader itself is core, so the oglc-view viewer reads .gltf/.glb out of the base install
OpenGLContext[audio] -- the playback backend that reaches a sound card. Audio is core and mixes without it; this is what makes it audible
OpenGLContext[pygame], OpenGLContext[wx] -- the PyGame and wxPython backends
OpenGLContext[all] -- every backend, plus Draco and audio playback

Using `uv`

uv resolves and installs the whole dependency set (including SimpleParse, PyVRML97 and TTFQuery) from PyPI. In a checkout:

uv venv
uv pip install -e ".[glfw,gltf]"

or, to run a script without managing a virtual environment yourself:

uv run --with "OpenGLContext[glfw,gltf]" oglc-view model.glb

Console commands

Installing the package puts these on your path:

oglc-view: The viewer — open and walk around a glTF, VRML97, OBJ or 3D Tiles scene. The format is chosen from the source, so one command opens all four. See The viewer.
oglc-terrain: Generate and walk a streamed terrain world: rolling hills, a river canyon, a lake and snow-capped mountains, with gravity, collision against the surface you can see, distance-LOD conifers and a translucent water surface. Takes a real heightmap with --dem, or an existing 3D Tiles tileset. See Terrain & 3D Tiles.
oglc-gltf-demo: Browse the Khronos glTF sample models — a gallery of the conformance roster, each shown by its own picture, over the same viewer. See Sample Gallery.
oglc-gltf-regression: Render every glTF demo and diff it against a verified baseline, for checking that a rendering change moved only what it meant to.
oglc-ui-demo: The overlay UI, demonstrated: the settings screen, the key-binding editor, the console and a skin. See The overlay UI.
oglc-test: Run a context's automated tests — the test runner behind the visual-regression suite.
oglc-lorentz: A Lorentz attractor drawn as a ten-thousand-point line set. A small standing demonstration of animated line geometry.

oglc-gltf, oglc-vrml and oglc-tiles are deprecated aliases for oglc-view, kept for one release cycle; each prints a notice and forwards. Use oglc-view in anything new.

OpenGLContext-Specific Documentation

Start with the Rendering documents if you want to understand how a frame is drawn, Supporting Features for the systems that run beside the renderer — how the player moves, what the world does, what it sounds like — and Content for loading and displaying models and worlds. The NeHe tutorial translations are a good starting point for beginning OpenGL programmers.

Tutorials -- Documentation for users unfamiliar with OpenGL

NeHe translations
Introduction to Shaders
Special Effects

Rendering

Flat Rendering -- The current client-side "flat" rendering pass used for both profiles
Core-Profile Rendering -- The shader-based core-profile pass, its shader programs and passes
Physically Based Rendering -- The PBR metallic/roughness pass, materials and image-based lighting
The PBR Uber-Shader -- Line-by-line walkthrough of the fragment shader: textures, uniforms and lobes
Shadows -- Dynamic shadow mapping shared by the core lighting and PBR passes
Instanced Geometry -- Collapsing many copies of one shape into a single draw call: how grouping, per-instance data, picking, caching and cluster culling work
Overlay UI -- Panels drawn over a live frame and driven by the pointer: a settings screen generated from the ContextDefinition's fields, key rebinding, dialogs, a scrolling licence notice, a console, and nine-slice skinning. The whole interface scales with the window, so it stays readable and hittable at 4K -- plus the oglc-ui demo
HUD & Developer Overlay -- Screen furniture drawn over a live world and never taking an event: a reticule that belongs to the weapon, meters that colour themselves from thresholds, an icon-and-number readout and a fading message queue -- plus the developer overlay, fed by registered providers, where the frame rate is now drawn
Particle Effects -- Fire, smoke, sparks, explosions and trails as camera-facing quads in one instanced draw: a numpy pool with a packed live set, emitters as declared nodes, life curves as uniforms, and named presets
Terrain & Landscapes -- Streamed OGC 3D Tiles terrain with screen-space-error LOD, frustum-culled paging, per-tile walkable colliders, procedural & DEM heightmaps, caves/overhangs, and distance-LOD vegetation -- plus the oglc-terrain viewer, the height-field path a splat-textured landscape is walked by, and exporting a city from OpenStreetMap as a tileset to stream (3D Tiles support is experimental)

Supporting Features

Movement Modes & Navigation -- Walking, flying, swimming and mouse-look as declared nodes: sampled input, key bindings a settings screen can rewrite, world-imposed modes and pointer capture
Physics & Collision -- Real-time rigid-body physics built on the OMI glTF model: collision, gravity zones, triggers, joints, shape cooking, a character controller with safe viewpoint binding, a motion debug overlay, and walking as a capability of every interactive context
Spatial Audio -- Sound placed in the scene on glTF's KHR_audio_emitter model: distance curves, directional cones, equal-power panning, a fixed voice pool with priority stealing, an underwater muffle, and silence as a first-class backend. The engine is the standalone omi_audio package; OpenGLContext supplies the scenegraph nodes and the per-context engine

Content

The viewer -- oglc-view: one command that opens a glTF model, a VRML97 world, an OBJ or a streamed 3D Tiles dataset, its library of samples, its screens and controls, embedding it as a component and adding a format
Loading glTF -- The glTF 2.0 loader: what it supports, and using it from your own code
Rendering Text -- The Text and FontStyle nodes and the font providers
Using VRML97 -- Using the (partial) VRML97 loader and the nodes it creates

Event Model -- The event model which manages changes to the VRML97 scenegraph
PyDoc References (Automatically generated documentation)

OpenGLContext

OpenGLContext_qt (PyQt4 context, a separate module due to licensing restrictions)

PyVRML97 (module vrml)
TTFQuery (module ttfquery)
PyOpenGL (module OpenGL)

Structural Overview -- OpenGLContext's architecture and implementation
Rendering Text -- Overview of the Text and FontStyle scenegraph nodes, general notes regarding support of text in OpenGLContext
Using NumPy Arrays -- Array math within OpenGLContext and PyOpenGL: creating arrays, the dtypes that match each GL type, slicing, the vector utilities, and handing an array to the driver as geometry

Sample Code (Where to Look)

The râison d'ętre (apologies for my rusty French) for OpenGLContext is to provide a platform for testing and sample code, so you'll find a lot of it lurking about in the project. In particular, in the source-code release, you can find sample code for: