moderngl-window

Common errors

• AttributeError: 'MyWindow' object has no attribute 'render'

  cause Attempting to use old callback names (e.g., `render`) after upgrading to moderngl-window 3.0.0 or later.
  fix Rename the method `render` to `on_render`. Apply this `on_` prefix to all other callback methods like `resize`, `key_event`, etc.

• ModuleNotFoundError: No module named 'moderngl'

  cause The core `moderngl` library, a fundamental dependency, is not installed in the current environment.
  fix Install the `moderngl` library: `pip install moderngl`.

• FileNotFoundError: Cannot find resource: 'my_shader.glsl' in any known resource directories

  cause The `moderngl-window` resource loader cannot locate the specified file because the `resource_dir` is not set or the file path is incorrect.
  fix Ensure `self.resource_dir` is correctly set in your `WindowConfig` to point to the directory containing your resources, or provide an absolute path to `self.load_program()`/`self.load_texture_2d()`. For example, `resource_dir = Path(__file__).parent.resolve() / "resources"`.

Warnings

• breaking All callback methods (e.g., `render`, `resize`, `key_event`) were renamed with an `on_` prefix in version 3.0.0. Existing code using older versions will break if updated to 3.0.0 or later.
  Fix: Rename methods such as `render` to `on_render`, `resize` to `on_resize`, `key_event` to `on_key_event`, etc.
• gotcha Resource loading methods (e.g., `load_program`, `load_texture_2d`) use relative paths by default. If resources are not found, ensure `resource_dir` is set correctly in `WindowConfig` or that resource paths are registered using `moderngl_window.resources`.
  Fix: Set `resource_dir = Path(__file__).parent / "resources"` in your `WindowConfig` subclass or explicitly register resource directories using `moderngl_window.resources.register_dir('path/to/my/resources')`.
• gotcha `moderngl-window` automatically handles ModernGL context creation and activation when using `WindowConfig`. Attempting to manually create and activate a context *within* a `WindowConfig` subclass might lead to unexpected behavior or redundant operations.
  Fix: Rely on `WindowConfig` to manage the OpenGL context (accessible via `self.ctx`). If explicit context control is needed, consider using `moderngl_window.create_window_from_settings()` or lower-level window APIs.

Install

• pip install moderngl-window Install latest version
• pip install "moderngl-window<3" Install pre-3.0.0 (old API)

Imports

• mglw

  import moderngl_window as mglw

  Standard alias for the main library module.
• WindowConfig
  wrong:

  import moderngl_window.WindowConfig

  correct:

  from moderngl_window import WindowConfig

  WindowConfig is typically imported directly from the top-level package for clarity and brevity when extending.

Quickstart

This quickstart demonstrates creating a basic window by extending `moderngl_window.WindowConfig`. It sets up an OpenGL 3.3 context, specifies window dimensions and title, and provides a minimal `on_render` method to clear the screen with a red color. The `run()` method then starts the window's event loop.

import moderngl_window as mglw

class MyWindow(mglw.WindowConfig):
    # Set OpenGL version (e.g., 3.3 for core profile)
    gl_version = (3, 3)
    # Set window size
    window_size = (1280, 720)
    # Set window title
    title = "Hello, moderngl-window!"
    
    # Optionally, specify a resource directory for shaders, textures etc.
    # resource_dir = Path(__file__).parent.resolve() / "resources"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # Any setup for ModernGL context or resources goes here
        print("ModernGL context initialized!")

    def on_render(self, time: float, frametime: float):
        # Clear the framebuffer with a color (e.g., red)
        self.ctx.clear(1.0, 0.0, 0.0, 1.0)

    # You can also implement other event handlers like on_key_event, on_mouse_press_event etc.

if __name__ == '__main__':
    # Run the window config. This creates the window and starts the event loop.
    MyWindow.run()