OpenGL Context

arcade.ArcadeContext

class arcade.ArcadeContext(window: pyglet.window.BaseWindow, gc_mode: str = 'auto')[source]

Bases: arcade.gl.context.Context

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

Pyglet users can use the base Context class and extend that as they please.

This is part of the low level rendering API in arcade and is mainly for more advanced usage

Parameters
  • window (pyglet.window.Window) – The pyglet window

  • gc_mode (str) – The garbage collection mode for opengl objects. auto (default) is just what we would expect in python while context_gc 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.

classmethod activate(ctx: arcade.gl.context.Context)

Mark a context as the currently active one

property blend_func: Tuple[int, int]

Get or the blend function:

ctx.blend_func = ctx.ONE, ctx.ONE
Type

tuple (src, dst)

buffer(*, data: Optional[Any] = None, reserve: int = 0, usage: str = 'static') arcade.gl.buffer.Buffer

Create a new OpenGL Buffer object.

Parameters
  • data (Any) – The buffer data, This can be bytes or an object supporting the buffer protocol.

  • reserve (int) – The number of bytes reserve

  • usage (str) – Buffer usage. ‘static’, ‘dynamic’ or ‘stream’

Return type

Buffer

compute_shader(*, source: str)

Create a compute shader

Parameters

source (str) – The glsl source

copy_framebuffer(src: arcade.gl.framebuffer.Framebuffer, dst: arcade.gl.framebuffer.Framebuffer)

Copies/blits a framebuffer to another one.

This operation many restrictions to ensure it works across different platforms and drivers:

  • The source and destination framebuffer must be the same size

  • The formats of the attachments must be the same

  • Only the source framebuffer can be multisampled

  • Framebuffers cannot have interger attachments

Parameters
property default_atlas: arcade.texture_atlas.TextureAtlas

The default texture atlas. This is created when arcade is initialized. All sprite lists will use use this atlas unless a different atlas is passned in the SpriteList constructor.

Type

TextureAtlas

depth_texture(size: Tuple[int, int], *, data=None) arcade.gl.texture.Texture

Create a 2D depth texture

Parameters
  • size (Tuple[int, int]) – The size of the texture

  • data (Any) – The texture data (optional). Can be bytes or an object supporting the buffer protocol.

disable(*args)

Disable one or more context flags:

# Single flag
ctx.disable(ctx.BLEND)
# Multiple flags
ctx.disable(ctx.DEPTH_TEST, ctx.CULL_FACE)
enable(*flags)

Enables one or more context flags:

# Single flag
ctx.enable(ctx.BLEND)
# Multiple flags
ctx.enable(ctx.DEPTH_TEST, ctx.CULL_FACE)
enable_only(*args)

Enable only some flags. This will disable all other flags. This is a simple way to ensure that context flag states are not lingering from other sections of your code base:

# Ensure all flags are disabled (enable no flags)
ctx.enable_only()
# Make sure only blending is enabled
ctx.enable_only(ctx.BLEND)
# Make sure only depth test and culling is enabled
ctx.enable_only(ctx.DEPTH_TEST, ctx.CULL_FACE)        
enabled(*flags)

Temporarily change enabled flags:

with ctx.enabled(ctx.BLEND, ctx.CULL_FACE):
    # Render something
enabled_only(*flags)

Temporarily change enabled flags:

with ctx.enabled_only(ctx.BLEND, ctx.CULL_FACE):
    # Render something
property error: Optional[str]

Check OpenGL error

Returns a string representation of the occurring error or None of no errors has occurred.

Example:

err = ctx.error
if err:
    raise RuntimeError("OpenGL error: {err}")
Type

str

property fbo: arcade.gl.framebuffer.Framebuffer

Get the currently active framebuffer. This property is read-only

Type

arcade.gl.Framebuffer

finish() None

Wait until all OpenGL rendering commands are completed.

This function will actually stall until all work is done and may have severe performance implications.

flush()

A suggestion to the driver to execute all the queued drawing calls even if the queue is not full yet. This is not a blocking call and only a suggestion. This can potentially be used for speedups when we don’t have anything else to render.

framebuffer(*, color_attachments: Optional[Union[arcade.gl.texture.Texture, List[arcade.gl.texture.Texture]]] = None, depth_attachment: Optional[arcade.gl.texture.Texture] = None) arcade.gl.framebuffer.Framebuffer

Create a Framebuffer.

Parameters
Return type

Framebuffer

gc() int

Run garbage collection of OpenGL objects for this context. This is only needed when gc_mode is context_gc.

Returns

The number of resources destroyed

Return type

int

property gc_mode: str

Set the garbage collection mode for OpenGL resources. Supported modes are:

# default: Auto ctx.gc_mode = “auto”

# Defer garbage collection until ctx.gc() is called # This can be useful to enforce the main thread to # run garbage collection of opengl resources ctx.gc_mode = “context_gc”

geometry(content: Optional[Sequence[arcade.gl.types.BufferDescription]] = None, index_buffer: Optional[arcade.gl.buffer.Buffer] = None, mode: Optional[int] = None, index_element_size: int = 4)

Create a Geomtry instance.

Parameters
  • content (list) – List of BufferDescription (optional)

  • index_buffer (Buffer) – Index/element buffer (optional)

  • mode (int) – The default draw mode (optional)

  • mode – The default draw mode (optional)

  • index_element_size (int) – Byte size of the index buffer type. Can be 1, 2 or 4 (8, 16 or 32 bit unsigned integer)

property gl_version: Tuple[int, int]

The OpenGL version as a 2 component tuple

Type

tuple (major, minor) version

is_enabled(flag) bool

Check if a context flag is enabled

Type

bool

load_compute_shader(path: Union[str, pathlib.Path]) arcade.gl.compute_shader.ComputeShader[source]

Loads a compute shader.

Parameters

path (Union[str,pathlib.Path]) – Path to texture

load_program(*, vertex_shader: Union[str, pathlib.Path], fragment_shader: Optional[Union[str, pathlib.Path]] = None, geometry_shader: Optional[Union[str, pathlib.Path]] = None, tess_control_shader: Optional[Union[str, pathlib.Path]] = None, tess_evaluation_shader: Optional[Union[str, pathlib.Path]] = None, defines: Optional[dict] = None) arcade.gl.program.Program[source]

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

This method also supports the :resources: prefix. It’s recommended to use absolute paths, but not required.

Example:

# The most common use case if having a vertex and fragment shader
program = window.ctx.load_program(
    vertex_shader="vert.glsl",
    fragment_shader="frag.glsl",
)
Parameters
  • vertex_shader (Union[str,pathlib.Path]) – path to vertex shader

  • fragment_shader (Union[str,pathlib.Path]) – path to fragment shader (optional)

  • geometry_shader (Union[str,pathlib.Path]) – path to geometry shader (optional)

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

  • tess_control_shader (Union[str,pathlib.Path]) – Tessellation Control Shader

  • tess_evaluation_shader (Union[str,pathlib.Path]) – Tessellation Evaluation Shader

load_texture(path: Union[str, pathlib.Path], *, flip: bool = True, build_mipmaps: bool = False) arcade.gl.texture.Texture[source]

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

Example:

texture = window.ctx.load_texture("background.png")
Parameters
  • path (Union[str,pathlib.Path]) – Path to texture

  • flip (bool) – Flips the image upside down

  • build_mipmaps (bool) – Build mipmaps for the texture

objects: Deque[Any]

Collected objects to gc when gc_mode is “context_gc”

property patch_vertices: int

Get or set number of vertices that will be used to make up a single patch primitive. Patch primitives are consumed by the tessellation control shader (if present) and subsequently used for tessellation.

Type

int

property point_size: float

float: Get or set the point size.

property primitive_restart_index: int

Get or set the primitive restart index. Default is -1

program(*, vertex_shader: str, fragment_shader: Optional[str] = None, geometry_shader: Optional[str] = None, tess_control_shader: Optional[str] = None, tess_evaluation_shader: Optional[str] = None, defines: Optional[Dict[str, str]] = None) arcade.gl.program.Program

Create a Program given the vertex, fragment and geometry shader.

Parameters
  • vertex_shader (str) – vertex shader source

  • fragment_shader (str) – fragment shader source (optional)

  • geometry_shader (str) – geometry shader source (optional)

  • tess_control_shader (str) – tessellation control shader source (optional)

  • tess_evaluation_shader (str) – tessellation evaluation shader source (optional)

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

Return type

Program

property projection_2d: Tuple[float, float, float, float]

Get or set the global orthogonal projection for arcade.

This projection is used by sprites and shapes and is represented by four floats: (left, right, bottom, top)

Type

Tuple[float, float, float, float]

property projection_2d_matrix: pyglet.math.Mat4

Get the current projection matrix. This 4x4 float32 matrix is calculated when setting projection_2d.

Type

Mat4

pyglet_rendering()[source]

Context manager for pyglet rendering. Since arcade and pyglet needs slightly different states we needs some initialization and cleanup.

Examples:

with window.ctx.pyglet_rendering():
    # Draw with pyglet here
query(*, samples=True, time=True, primitives=True)

Create a query object for measuring rendering calls in opengl.

Parameters
  • sampled (bool) – Collect written samples

  • time (bool) – Measure redering duration

  • primitives (bool) – Collect the number of primitives emitted

Return type

Query

reset() None[source]

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

property screen: arcade.gl.framebuffer.Framebuffer

The framebuffer for the window.

Type

Framebuffer

texture(size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Optional[Any] = None, wrap_x: Optional[ctypes.c_uint] = None, wrap_y: Optional[ctypes.c_uint] = None, filter: Optional[Tuple[ctypes.c_uint, ctypes.c_uint]] = None, samples: int = 0) arcade.gl.texture.Texture

Create a 2D Texture.

Wrap modes: GL_REPEAT, GL_MIRRORED_REPEAT, GL_CLAMP_TO_EDGE, GL_CLAMP_TO_BORDER

Minifying filters: GL_NEAREST, GL_LINEAR, GL_NEAREST_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_NEAREST GL_NEAREST_MIPMAP_LINEAR, GL_LINEAR_MIPMAP_LINEAR

Magnifying filters: GL_NEAREST, GL_LINEAR

Parameters
  • size (Tuple[int, int]) – The size of the texture

  • components (int) – Number of components (1: R, 2: RG, 3: RGB, 4: RGBA)

  • dtype (str) – The data type of each component: f1, f2, f4 / i1, i2, i4 / u1, u2, u4

  • data (Any) – The texture data (optional). Can be bytes or an object supporting the buffer protocol.

  • wrap_x (GLenum) – How the texture wraps in x direction

  • wrap_y (GLenum) – How the texture wraps in y direction

  • filter (Tuple[GLenum,GLenum]) – Minification and magnification filter

  • samples (int) – Creates a multisampled texture for values > 0

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. 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
Type

tuple (x, y, width, height)

property window: pyglet.window.BaseWindow

The window this context belongs to.

Type

pyglet.Window