{"id":9126,"library":"moderngl-window","title":"moderngl-window","description":"moderngl-window is a cross-platform helper library for ModernGL, simplifying window creation and resource loading for OpenGL applications. It provides a unified API over various windowing backends like Pyglet, GLFW, and SDL2. The library is actively maintained with frequent updates, currently at version 3.1.1, ensuring compatibility and introducing new features.","status":"active","version":"3.1.1","language":"en","source_language":"en","source_url":"https://github.com/moderngl/moderngl_window","tags":["OpenGL","graphics","windowing","game-development","ModernGL","pyglet","glfw","sdl2"],"install":[{"cmd":"pip install moderngl-window","lang":"bash","label":"Install latest version"},{"cmd":"pip install \"moderngl-window<3\"","lang":"bash","label":"Install pre-3.0.0 (old API)"}],"dependencies":[{"reason":"Core OpenGL context library that moderngl-window wraps.","package":"moderngl","optional":false},{"reason":"Default windowing backend used if no other is specified. Automatically installed.","package":"pyglet","optional":true},{"reason":"Used for loading 2D textures, texture arrays, and cube maps.","package":"Pillow","optional":true}],"imports":[{"note":"Standard alias for the main library module.","symbol":"mglw","correct":"import moderngl_window as mglw"},{"note":"WindowConfig is typically imported directly from the top-level package for clarity and brevity when extending.","wrong":"import moderngl_window.WindowConfig","symbol":"WindowConfig","correct":"from moderngl_window import WindowConfig"}],"quickstart":{"code":"import moderngl_window as mglw\n\nclass MyWindow(mglw.WindowConfig):\n    # Set OpenGL version (e.g., 3.3 for core profile)\n    gl_version = (3, 3)\n    # Set window size\n    window_size = (1280, 720)\n    # Set window title\n    title = \"Hello, moderngl-window!\"\n    \n    # Optionally, specify a resource directory for shaders, textures etc.\n    # resource_dir = Path(__file__).parent.resolve() / \"resources\"\n\n    def __init__(self, **kwargs):\n        super().__init__(**kwargs)\n        # Any setup for ModernGL context or resources goes here\n        print(\"ModernGL context initialized!\")\n\n    def on_render(self, time: float, frametime: float):\n        # Clear the framebuffer with a color (e.g., red)\n        self.ctx.clear(1.0, 0.0, 0.0, 1.0)\n\n    # You can also implement other event handlers like on_key_event, on_mouse_press_event etc.\n\nif __name__ == '__main__':\n    # Run the window config. This creates the window and starts the event loop.\n    MyWindow.run()","lang":"python","description":"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."},"warnings":[{"fix":"Rename methods such as `render` to `on_render`, `resize` to `on_resize`, `key_event` to `on_key_event`, etc.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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')`.","message":"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`.","severity":"gotcha","affected_versions":"all"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Rename the method `render` to `on_render`. Apply this `on_` prefix to all other callback methods like `resize`, `key_event`, etc.","cause":"Attempting to use old callback names (e.g., `render`) after upgrading to moderngl-window 3.0.0 or later.","error":"AttributeError: 'MyWindow' object has no attribute 'render'"},{"fix":"Install the `moderngl` library: `pip install moderngl`.","cause":"The core `moderngl` library, a fundamental dependency, is not installed in the current environment.","error":"ModuleNotFoundError: No module named 'moderngl'"},{"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\"`.","cause":"The `moderngl-window` resource loader cannot locate the specified file because the `resource_dir` is not set or the file path is incorrect.","error":"FileNotFoundError: Cannot find resource: 'my_shader.glsl' in any known resource directories"}]}