Skip to content

FAQ

Jump to bottom
Mark Brooks edited this page Sep 7, 2025 · 2 revisions

PicoGL FAQ

This page answers common questions and expands on the troubleshooting guide to help you work productively with PicoGL.

Installation & Imports

Q: I get No module named 'picogl'. What should I do?

A: Make sure PicoGL is installed into the same Python environment you are using to run code:

pip install picogl
python -c "import picogl"

If the import still fails, verify your PYTHONPATH and that you are in the correct virtual environment.

Q: Do I need PyOpenGL, NumPy, and other packages?

A: Yes. PicoGL depends on:

  • PyOpenGL and optionally PyOpenGL-accelerate
  • numpy
  • pyglm
  • Pillow (for texture images) Install them with:
pip install PyOpenGL PyOpenGL-accelerate numpy pyglm Pillow

OpenGL Context & Rendering

Q: Why do I get No OpenGL context?

A: Ensure you run your script in a desktop session with access to a display. On macOS, run from Terminal.app or iTerm2 (not inside some IDEs). On Linux, check that $DISPLAY is set and X11/Wayland is running.

Q: Why does my window open but stay black?

A: Common causes:

  • Shaders fail to compile (check console for errors)
  • OpenGL version is too low
  • Geometry not uploaded/bound Try running a legacy example to confirm basic rendering works.

Q: Can I mix Modern and Legacy mode?

A: Mixing is not fully supported at this time. Pick one pipeline per context for predictable behavior.

Shader & Texture Issues

Q: Shader compilation failed. How do I debug?

A: Confirm that your shader matches your OpenGL version and GLSL syntax. Print the compilation log using PicoGL utilities. As a fallback, use a legacy example that doesn’t need shaders.

Q: Uniform or attribute not found?

A: Check spelling and data types in both GLSL and Python code. Unused uniforms are optimized away by the compiler.

Q: Texture loading failed.

A: Confirm that the image exists, the path is correct, and Pillow is installed. Also check that your GPU supports the chosen texture format.

Platform Questions

Q: Do I need XQuartz on macOS?

A: If you’re running under X11 or using some Linux-style toolkits, yes. For PicoGL’s default GLUT backend, standard macOS OpenGL works without XQuartz.

Q: Why does Windows give DLL load failed?

A: Usually this is a mismatch between Python architecture and PyOpenGL binaries. Ensure you use 64-bit Python and reinstall PyOpenGL after updating Visual C++ Redistributable.

Q: Linux shows No display available.

A: Check that X11/Wayland is running. Set $DISPLAY properly. Install mesa and GL libraries:

sudo apt install libgl1-mesa-dev libglu1-mesa

Performance & Profiling

Q: Rendering is very slow. How can I improve it?

A:

  • Reduce draw calls by batching geometry
  • Use instanced rendering where possible
  • Optimize shaders (remove unused code, use correct precision)
  • Ensure textures and buffers fit in GPU memory

Q: How do I check FPS?

A: Wrap your render() calls in a timer:

import time
start = time.time()
render_scene()
print(f"FPS: {1/(time.time()-start):.1f}")

Debugging & Diagnostics

Q: How do I inspect my OpenGL state?

A: PicoGL exposes OpenGL directly. Use:

from OpenGL.GL import glGetString, GL_VERSION, GL_VENDOR, GL_RENDERER
print(glGetString(GL_VERSION))
print(glGetString(GL_VENDOR))
print(glGetString(GL_RENDERER))

Q: How can I verify that OpenGL works before running big projects?

A: Run the provided example tests:

python examples/test_opengl_setup.py
python examples/legacy_cube_minimal.py

If these show a window, your environment is healthy.

Common Fixes

  • Update drivers and Python packages:
pip install --upgrade picogl numpy PyOpenGL pyglm Pillow
  • Use legacy examples if modern shaders fail
  • Verify your OpenGL version:
import OpenGL.GL as GL
print(GL.glGetString(GL.GL_VERSION))
  • Try software rendering with Mesa (Linux):
export MESA_GL_VERSION_OVERRIDE=3.3
python examples/cube.py

Reporting Issues

When opening an issue on GitHub, include:

  • OS, Python version, GPU, driver, OpenGL version
  • Error messages and traceback
  • Steps to reproduce and minimal code sample
  • Virtual environment and package versions

This helps maintainers reproduce and fix bugs faster.

Getting Help

When in doubt, start from a minimal example and build up.

Clone this wiki locally