Arcade’s Graphics Layer

The arcade.gl module is a “graphics layer” around platform-specific backends.

This module is meant to provide advanced users with:

  1. a pluggable backend API for porting to new platforms

  2. consistent abstractions of low-level graphics primitives

  3. avoiding common pitfalls graphics programming

Using This Module

This module does not aim to be a perfect copy of any other graphics API.

Warning

This module assumes you are familiar with low-level graphics programming!

Instead, it takes inspiration from ModernGL to build on pyglet.gl with more ctypes bindings.

The low-level API primitives and their reference implementation include:

Primitive

Base (arcade.gl)

OpenGL Reference Subclass (arcade.gl.backends.opengl)

GPU programs (shaders)

program.Program

Program

low-level texture objects [2]

arcade.gl.texture.Texture

Texture

framebuffers

arcade.gl.framebuffer.Framebuffer

Framebuffer

queries

arcade.gl.query.Query

Query

buffers

arcade.gl.buffer.Buffer

Buffer

vertex arrays/geometry

arcade.gl.vertex_array.VertexArray

VertexArray

Compute shaders [1]

arcade.gl.compute_shader.ComputerShader

ComputerShader

Usage Reference

Reference Backend

arcade.gl.backends.opengl

Abstraction examples

See the experimental examples folder in the GitHub repo

Graphics API Gotchas

No Computer Shaders On Mac

This limitation is due to how macOS handles OpenGL.

Compute shaders became a core OpenGL feature in 4.3. However, Apple froze OpenGL for macOS as a maintenance-only API at OpenGL 4.1 on both Intel and M-series Macs. As a result, there are no compute shaders on Mac.

Alternatives

Clever use of fragments shaders and framebuffer objects (FBOs) can sometimes provide equivalent results for specific cases. Since WebGL also lacks compute shaders, older WebGL code can be a useful reference for implementing Mac-compatible compute functionality within OpenGL.

Two Texture Types?

This module includes low-level and platform-specific classes.

Most users will want to use the high-lever arcade.Texture class. If you are still unsure, consult the table below:

Module

Target Audience

Contents

arcade.texture

Everyday users

Friendly texture object suitable for implementing gameplay

arcade.gl.backends texture submodules

Platform-specific internals

Low-level abstractions which handle platform-specific behavior for:

  • Low-level graphics APIs

  • Operating systems

  • Edge cases too specific to mention here

Supported Backends

Current Backends

OpenGL Backend

The current implemented backend is the OpenGL/GLES wrapper in arcade.gl.backends.opengl.

To maximize hardware support, it requires at least one of the following:

  • OpenGL 3.3+

  • GLES with certain extensions

It avoids binary dependencies by using Python’s built-in ctypes module via both pyglet and Arcade’s added OpenGL bindings.

This ensures Arcade can run on most desktop and laptop hardware from the past decade, just like pyglet. This portability trades away a bit of speed and context-handling flexibility compared to ModernGL.

Future Backends

Web

Web browser support is an ongoing effort.

The current plan is to implement a WebGPU backend running locally in-browser via pyodide. This will ensure better performance and feature parity with desktop environments compared to the archived arcade-web protoype.

Adding Backends

A new backend requires adding a submodule in arcade.gl.backends which handles any initialization tasks to implement the following:

  • concreted versions of the classes in Using This Module

  • exposes a concrete implementation of BaseProvider

Note that all resources are created through the arcade.gl.Context / arcade.ArcadeContext. An instance of this type should be accessible the window (arcade.Window.ctx).

This API can also be used with pyglet by creating an instance of arcade.gl.Context after the window creation. The arcade.ArcadeContext on the other hand extends the default Context with Arcade-specific helper methods and should only be used by arcade.