OpenGL Context

class arcade.ArcadeContext(window: Window, gc_mode: str = 'context_gc', gl_api: str = 'gl')

Bases: Context

An OpenGL context implementation for Arcade with added custom features. This context is normally accessed through arcade.Window.ctx.

Parameters:

• window – The pyglet window

• gc_mode – The garbage collection mode for OpenGL objects. auto is just what we would expect in python while context_gc (default) requires you to call Context.gc(). The latter can be useful when using multiple threads when it’s not clear what thread will gc the object.

• gl_api – The OpenGL API to use. By default it’s set to gl which is the standard OpenGL API. If you want to use OpenGL ES you can set it to gles.

atlas_size: tuple[int, int] = (512, 512)

bind_window_block() → None

Binds the global projection and view uniform buffer object.

This should always be bound to index 0 so all shaders have access to them.

property default_atlas: TextureAtlasBase

The default texture atlas.

This is created when Arcade is initialized. All sprite lists will use use this atlas unless a different atlas is passed in the arcade.SpriteList constructor.

get_framebuffer_image(fbo: Framebuffer, components: int = 4, flip: bool = True) → Image

Shortcut method for reading data from a framebuffer and converting it to a PIL image.

Parameters:

• fbo – Framebuffer to get image from

• components – Number of components to read. Default is 4 (RGBA). Valid values are 1, 2, 3, 4.

• flip – Flip the image upside down. This is useful because OpenGL has the origin at the bottom left corner while PIL has it at the top left.

load_compute_shader(path: str | Path, common: Iterable[str | Path] = ()) → ComputeShader

Loads a compute shader from file. This methods supports resource handles.

Example:

ctx.load_compute_shader(":shader:compute/do_work.glsl")

Parameters:

• path – Path to texture

• common (optional) – Common sources injected into compute shader

load_program(*, vertex_shader: str | Path, fragment_shader: str | Path | None = None, geometry_shader: str | Path | None = None, tess_control_shader: str | Path | None = None, tess_evaluation_shader: str | Path | None = None, common: Iterable[str | Path] = (), defines: dict[str, Any] | None = None, varyings: Sequence[str] | None = None, varyings_capture_mode: str = 'interleaved') → Program

Create a new program given file names that contain the vertex shader and fragment shader. Note that the fragment and geometry shaders are optional when transform shaders are loaded.

This method also supports resource handles.

Example:

# The most common use case is having a vertex and fragment shader
program = window.ctx.load_program(
    vertex_shader="vert.glsl",
    fragment_shader="frag.glsl",
)

Parameters:

• vertex_shader – Path to the vertex shader.

• fragment_shader (optional) – Path to the fragment shader (optional).

• geometry_shader (optional) – Path to the geometry shader (optional).

• tess_control_shader (optional) – Tessellation Control Shader.

• tess_evaluation_shader (optional) – Tessellation Evaluation Shader.

• common (optional) – Common files to be included in all shaders.

• defines (optional) – Substitute #define values in the source.

• varyings (optional) – The name of the out attributes in a transform shader. This is normally not necessary since we auto detect them, but some more complex out structures we can’t detect.

• varyings_capture_mode (optional) –

  The capture mode for transforms.

  Based on these settings, the transform() method will accept a single buffer or a list of buffers.

  • "interleaved" means all out attributes will be written to a single buffer.

  • "separate" means each out attribute will be written to separate buffers.

load_texture(path: str | Path, *, flip: bool = True, wrap_x: int | None = None, wrap_y: int | None = None, filter: tuple[int, int] | None = None, build_mipmaps: bool = False, internal_format: int | None = None, immutable: bool = False, compressed: bool = False) → Texture2D

Loads and creates an OpenGL 2D texture. Currently, all textures are converted to RGBA for simplicity.

Examples:

# Load a texture in current working directory
texture = window.ctx.load_texture("background.png")

# Load a texture using Arcade resource handle
texture = window.ctx.load_texture(":textures:background.png")

# Load and compress a texture
texture = window.ctx.load_texture(
    ":textures:background.png",
    internal_format=gl.GL_COMPRESSED_RGBA_S3TC_DXT5_EXT,
    compressed=True,
)

Parameters:

• path – Path to texture

• flip – Flips the image upside down. Default is True.

• wrap_x – The wrap mode for the x-axis. Default is None.

• wrap_y – The wrap mode for the y-axis. Default is None.

• filter – The min and mag filter. Default is None.

• build_mipmaps – Build mipmaps for the texture. Default is False.

• internal_format (optional) – The internal format of the texture. This can be used to override the default internal format when using sRGBA or compressed textures.

• immutable (optional) – Make the storage (not the contents) immutable. This can sometimes be required when using textures with compute shaders.

• compressed (optional) – If the internal format is a compressed format meaning your texture will be compressed by the GPU.

property projection_matrix: Mat4

Get or set the current projection matrix.

This 4x4 float32 matrix is usually calculated by a cameras but can be modified directly if you know what you are doing.

This property simply gets and sets pyglet’s projection matrix.

reset() → None

Reset context flags and other states. This is mostly used in unit testing.

shader_inc(source: str) → str

Parse a shader source looking for #include directives and replace them with the contents of the included file.

The #include directive must be on its own line and the file and the path should use a resource handle.

Example:

#include :my_resource_handle:lib/common.glsl

Parameters:

source – The shader source code

property view_matrix: Mat4

Get or set the current view matrix.

This 4x4 float32 matrix is usually calculated by a cameras but can be modified directly if you know what you are doing.

This property simply gets and sets pyglet’s view matrix.

property viewport: tuple[int, int, int, int]

Get or set the viewport for the currently active framebuffer.

The viewport simply describes what pixels of the screen OpenGL should render to. Format is (x, y, width, height). Normally it would be the size of the window’s framebuffer:

# 4:3 screen
ctx.viewport = 0, 0, 800, 600
# 1080p
ctx.viewport = 0, 0, 1920, 1080
# Using the current framebuffer size
ctx.viewport = 0, 0, *ctx.screen.size