Legacy Examples

PicoGL includes comprehensive legacy examples designed to work on systems with limited OpenGL support, including older macOS systems and systems without modern shader support.

Overview

The legacy examples provide multiple fallback renderers that work on systems with limited OpenGL support:

  • Minimal versions: Use only PyOpenGL, maximum compatibility

  • Fixed versions: Use PicoGL with legacy rendering, medium compatibility

  • Original versions: Use modern OpenGL 3.3+, low compatibility

Why Legacy Examples?

Modern OpenGL (3.3+) requires: * Shader compilation support * Vertex Array Objects (VAOs) * Modern graphics drivers * Specific OpenGL context requirements

Legacy examples work on: * Older macOS systems * Systems without shader support * Systems with limited OpenGL drivers * Headless environments (with proper setup) * Educational environments with restricted OpenGL

Legacy Teapot Examples

Legacy Teapot (Minimal)

File: examples/legacy_teapot_minimal.py

The most compatible teapot renderer, using only built-in OpenGL primitives.

Features: * Uses glutSolidTeapot() built-in primitive * No external dependencies beyond PyOpenGL * OpenGL 1.x immediate mode rendering * Interactive rotation and zoom * Multiple rendering modes

Controls: * Mouse drag: Rotate view * Mouse wheel: Zoom in/out * R: Reset rotation * W: Toggle wireframe mode * F: Fill mode * +/-: Zoom in/out * Space: Toggle auto-rotation * ESC: Exit

Run:

python examples/legacy_teapot_minimal.py

Compatibility: Maximum (works on any OpenGL system)

Legacy Teapot (Fixed)

File: examples/legacy_teapot_fixed.py

PicoGL-integrated legacy teapot with OBJ file support.

Features: * Uses LegacyGLMesh for OpenGL 1.x/2.x compatibility * Loads teapot data from OBJ file * Falls back to wireframe teapot if OBJ loading fails * Full PicoGL integration * Interactive controls

Controls: * Mouse drag: Rotate view * Mouse wheel: Zoom in/out * R: Reset rotation * W: Toggle wireframe mode * F: Fill mode * +/-: Zoom in/out * Space: Toggle auto-rotation * ESC: Exit

Run:

python examples/legacy_teapot_fixed.py

Compatibility: Medium (requires PicoGL library)

Legacy Cube Examples

Legacy Cube (Minimal)

File: examples/legacy_cube_minimal.py

The most compatible cube renderer, using immediate mode OpenGL.

Features: * Uses immediate mode OpenGL (glBegin/glEnd) * No external dependencies beyond PyOpenGL * Same vertex and color data as original cube * Interactive rotation and zoom * Multiple rendering modes * Normal vector display

Controls: * Mouse drag: Rotate view * Mouse wheel: Zoom in/out * R: Reset rotation * W: Toggle wireframe mode * F: Fill mode * N: Toggle normals display * +/-: Zoom in/out * Space: Toggle auto-rotation * ESC: Exit

Run:

python examples/legacy_cube_minimal.py

Compatibility: Maximum (works on any OpenGL system)

Legacy Cube (Fixed)

File: examples/legacy_cube_fixed.py

PicoGL-integrated legacy cube using LegacyGLMesh.

Features: * Uses LegacyGLMesh for OpenGL 1.x/2.x compatibility * Loads cube data using PicoGL MeshData * Falls back to wireframe cube if mesh loading fails * Full PicoGL integration * Interactive controls

Controls: * Mouse drag: Rotate view * Mouse wheel: Zoom in/out * R: Reset rotation * W: Toggle wireframe mode * F: Fill mode * +/-: Zoom in/out * Space: Toggle auto-rotation * ESC: Exit

Run:

python examples/legacy_cube_fixed.py

Compatibility: Medium (requires PicoGL library)

Diagnostic Tools

OpenGL Setup Test

File: examples/test_opengl_setup.py

Comprehensive diagnostic tool for OpenGL setup issues.

Features: * Tests OpenGL imports * Tests display environment * Tests OpenGL context creation * Tests PicoGL imports * Provides troubleshooting guidance

Run:

python examples/test_opengl_setup.py

Output: Detailed report of OpenGL capabilities and issues

Cube Data Test

File: examples/test_cube_data.py

Tests cube data structure and PicoGL imports without requiring a display.

Features: * Validates cube vertex and color data * Tests triangle structure * Tests PicoGL imports * Tests mesh creation * Provides troubleshooting guidance

Run:

python examples/test_cube_data.py

Output: Validation report of cube data and imports

Installation and Setup

Prerequisites

Minimal Examples: * Python 3.7+ * PyOpenGL * GLUT (usually included with PyOpenGL)

Fixed Examples: * Python 3.7+ * PyOpenGL * GLUT * NumPy * PicoGL library

Installation

# Install minimal requirements
pip install PyOpenGL PyOpenGL_accelerate numpy

# For fixed examples (PicoGL integration)
pip install picogl

Platform-Specific Setup

macOS

  1. Install XQuartz (for X11 support): .. code-block:: bash

    brew install –cask xquartz

  2. Run from Terminal.app or iTerm2 (not from IDE)

  3. Check OpenGL support: .. code-block:: python

    import OpenGL.GL as GL print(GL.glGetString(GL.GL_VERSION))

Windows

  1. Update graphics drivers to latest version

  2. Install Visual C++ Redistributable if needed

  3. Run from command prompt (not from IDE)

Linux

  1. Install OpenGL libraries: .. code-block:: bash

    # Ubuntu/Debian sudo apt install libgl1-mesa-dev libglu1-mesa

    # CentOS/RHEL sudo yum install mesa-libGL mesa-libGLU

  2. Ensure X11 or Wayland is running

  3. Check display environment: .. code-block:: bash

    echo $DISPLAY

Troubleshooting

Common Issues

“No OpenGL context” error

  • Use minimal versions instead

  • Run from Terminal.app (macOS) or command prompt (Windows)

  • Check display environment

“Shader compilation failed” error

  • Use minimal versions (no shaders required)

  • Check OpenGL version support

  • Update graphics drivers

“PicoGL import failed” error

  • Use minimal versions (no PicoGL required)

  • Or install PicoGL: pip install picogl

“Segmentation fault” error

  • Use minimal versions

  • Check OpenGL drivers

  • Try software rendering

“Black screen” error

  • Check OpenGL support

  • Use minimal versions

  • Try different OpenGL settings

“No display available” error

  • Check display environment

  • Install XQuartz (macOS)

  • Ensure X11/Wayland is running (Linux)

macOS Specific Issues

OpenGL context creation fails

  • Run from Terminal.app or iTerm2

  • Check if XQuartz is installed and running

  • Try software rendering: export MESA_GL_VERSION_OVERRIDE=3.3

Segmentation fault

  • Run from Terminal.app

  • Check OpenGL drivers

  • Try different OpenGL settings

“No display available” error

  • Install XQuartz: brew install --cask xquartz

  • Check DISPLAY environment variable

  • Restart XQuartz

Windows Specific Issues

“DLL load failed” error

  • Install Visual C++ Redistributable

  • Check Python architecture (32-bit vs 64-bit)

“OpenGL not supported” error

  • Update graphics drivers

  • Check OpenGL support in graphics settings

“Microsoft Visual C++ 14.0 is required”

  • Install Visual Studio Build Tools

  • Or install pre-compiled wheels

Linux Specific Issues

“No display available” error

  • Ensure X11 or Wayland is running

  • Check DISPLAY environment variable

“OpenGL not supported” error

  • Install mesa libraries

  • Check graphics drivers

“Permission denied” error

  • Run with appropriate permissions

  • Check file permissions

Performance Notes

Minimal Versions: * Fastest performance * Uses hardware-optimized primitives * Immediate mode rendering * No shader compilation overhead

Fixed Versions: * Medium performance * Uses legacy VBOs * Some shader compilation * Better integration with PicoGL

Original Versions: * Slowest performance * Full shader pipeline * Modern VAO/VBO usage * Maximum feature set

Choosing the Right Version

Use Minimal Versions When: * Maximum compatibility is required * OpenGL support is limited * Performance is critical * No PicoGL integration needed

Use Fixed Versions When: * PicoGL integration is desired * Some OpenGL support is available * Balance between compatibility and features * OBJ file loading is needed

Use Original Versions When: * Full OpenGL 3.3+ support is available * Maximum features are needed * Modern shader pipeline is required * Best visual quality is desired

Development Notes

Adding New Legacy Examples:

  1. Follow the naming convention: legacy_<name>_<type>.py

  2. Provide both minimal and fixed versions when possible

  3. Include comprehensive error handling

  4. Test on multiple platforms

  5. Document compatibility requirements

Example Structure:

class LegacyExampleRenderer:
    def __init__(self, width=800, height=600, title="Example"):
        # Initialize renderer

    def init_glut(self):
        # Initialize GLUT window

    def init_gl(self):
        # Initialize OpenGL state

    def display(self):
        # Render the scene

    def run(self):
        # Main loop

Error Handling:

try:
    # OpenGL operations
except Exception as e:
    print(f"Warning: OpenGL issue: {e}")
    # Fallback behavior

For more information, see the Contributing guide.

License

The legacy examples are part of the PicoGL project and follow the same license terms.