Context

Context

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

Bases: object

Represents an OpenGL context. This context belongs to a pyglet.Window normally accessed through window.ctx.

The Context class contains methods for creating resources, global states and commonly used enums. All enums also exist in the gl module. (ctx.BLEND or arcade.gl.BLEND).

BLEND = 3042

Context flag: Blending

BLEND_ADDITIVE = (1, 1)

Blend mode shortcut for additive blending: ONE, ONE

BLEND_DEFAULT = (770, 771)

Blend mode shortcut for default blend mode: SRC_ALPHA, ONE_MINUS_SRC_ALPHA

BLEND_PREMULTIPLIED_ALPHA = (770, 1)

Blend mode shortcut for premultipled alpha: SRC_ALPHA, ONE

CLAMP_TO_BORDER = 33069
CLAMP_TO_EDGE = 33071
CULL_FACE = 2884

Context flag: Face culling

DEPTH_TEST = 2929

Context flag: Depth testing

DST_ALPHA = 772

Blend function

DST_COLOR = 774

Blend function

FUNC_ADD = 32774

source + destination

FUNC_REVERSE_SUBTRACT = 32779

Blend equations: destination - source

FUNC_SUBTRACT = 32778

Blend equations: source - destination

LINEAR = 9729

Texture interpolation: Linear interpolate

LINEAR_MIPMAP_LINEAR = 9987

Texture interpolation: Minification filter for mipmaps

LINEAR_MIPMAP_NEAREST = 9985

Texture interpolation: Minification filter for mipmaps

LINES = 1

Primitive mode

LINES_ADJACENCY = 10

Primitive mode

LINE_LOOP = 2

Primitive mode

LINE_STRIP = 3

Primitive mode

LINE_STRIP_ADJACENCY = 11

Primitive mode

MAX = 32776

Blend equations: Maximum of source and destination

MIN = 32775

Blend equations: Minimum of source and destination

MIRRORED_REPEAT = 33648
NEAREST = 9728

Texture interpolation: Nearest pixel

NEAREST_MIPMAP_LINEAR = 9986

Texture interpolation: Minification filter for mipmaps

NEAREST_MIPMAP_NEAREST = 9984

Texture interpolation: Minification filter for mipmaps

ONE = 1

Blend function

ONE_MINUS_DST_ALPHA = 773

Blend function

ONE_MINUS_DST_COLOR = 775

Blend function

ONE_MINUS_SRC_ALPHA = 771

Blend function

ONE_MINUS_SRC_COLOR = 769

Blend function

PATCHES = 14

Patch mode (tessellation)

POINTS = 0

Primitive mode

PROGRAM_POINT_SIZE = 34370

Context flag: Enable gl_PointSize in shaders.

REPEAT = 10497

Texture wrap mode: Repeat

SRC_ALPHA = 770

Blend function

SRC_COLOR = 768

Blend function

TRIANGLES = 4

Primitive mode

TRIANGLES_ADJACENCY = 12

Primitive mode

TRIANGLE_FAN = 6

Primitive mode

TRIANGLE_STRIP = 5

Primitive mode

TRIANGLE_STRIP_ADJACENCY = 13

Primitive mode

ZERO = 0

Blend function

classmethod activate(ctx: arcade.gl.context.Context)[source]

Mark a context as the currently active one

active: Optional[arcade.gl.context.Context] = None

The active context

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[source]

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)[source]

Create a compute shader

Parameters

source (str) – The glsl source

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

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
depth_texture(size: Tuple[int, int], *, data=None) arcade.gl.texture.Texture[source]

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)[source]

Disable one or more context flags:

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

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)[source]

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)[source]

Temporarily change enabled flags:

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

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[source]

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()[source]

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[source]

Create a Framebuffer.

Parameters
Return type

Framebuffer

gc() int[source]

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)[source]

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[source]

Check if a context flag is enabled

Type

bool

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[source]

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

query()[source]

Create a query object for measuring rendering calls in opengl.

Return type

Query

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[source]

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

ContextStats

class arcade.gl.context.ContextStats(warn_threshold=100)[source]

Bases: object

decr(key)[source]
incr(key)[source]

ContextStats

class arcade.gl.context.Limits(ctx)[source]

Bases: object

OpenGL Limitations

CONTEXT_PROFILE_MASK

A mask value indicating what context profile is used (core, compat etc.)

MAJOR_VERSION

Major version number of the OpenGL API supported by the current context.

MAX_3D_TEXTURE_SIZE

A rough estimate of the largest 3D texture that the GL can handle. The value must be at least 64

MAX_ARRAY_TEXTURE_LAYERS

Value indicates the maximum number of layers allowed in an array texture, and must be at least 256

MAX_COLOR_ATTACHMENTS

Maximum number of color attachments in a framebuffer

MAX_COLOR_TEXTURE_SAMPLES

Maximum number of samples in a color multisample texture

MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS

the number of words for fragment shader uniform variables in all uniform blocks

MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS

Number of words for geometry shader uniform variables in all uniform blocks

MAX_COMBINED_TEXTURE_IMAGE_UNITS

Maximum supported texture image units that can be used to access texture maps from the vertex shader

MAX_COMBINED_UNIFORM_BLOCKS

Maximum number of uniform blocks per program

MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS

Number of words for vertex shader uniform variables in all uniform blocks

MAX_CUBE_MAP_TEXTURE_SIZE

A rough estimate of the largest cube-map texture that the GL can handle

MAX_DEPTH_TEXTURE_SAMPLES

Maximum number of samples in a multisample depth or depth-stencil texture

MAX_DRAW_BUFFERS

Maximum number of simultaneous outputs that may be written in a fragment shader

MAX_DUAL_SOURCE_DRAW_BUFFERS

Maximum number of active draw buffers when using dual-source blending

MAX_ELEMENTS_INDICES

Recommended maximum number of vertex array indices

MAX_ELEMENTS_VERTICES

Recommended maximum number of vertex array vertices

MAX_FRAGMENT_INPUT_COMPONENTS

Maximum number of components of the inputs read by the fragment shader

MAX_FRAGMENT_UNIFORM_BLOCKS

Maximum number of uniform blocks per fragment shader.

MAX_FRAGMENT_UNIFORM_COMPONENTS

Maximum number of individual floating-point, integer, or boolean values that can be held in uniform variable storage for a fragment shader

MAX_FRAGMENT_UNIFORM_VECTORS

maximum number of individual 4-vectors of floating-point, integer, or boolean values that can be held in uniform variable storage for a fragment shader

MAX_GEOMETRY_INPUT_COMPONENTS

Maximum number of components of inputs read by a geometry shader

MAX_GEOMETRY_OUTPUT_COMPONENTS

Maximum number of components of outputs written by a geometry shader

MAX_GEOMETRY_TEXTURE_IMAGE_UNITS

Maximum supported texture image units that can be used to access texture maps from the geometry shader

MAX_GEOMETRY_UNIFORM_BLOCKS

Maximum number of uniform blocks per geometry shader

MAX_GEOMETRY_UNIFORM_COMPONENTS

Maximum number of individual floating-point, integer, or boolean values that can be held in uniform variable storage for a geometry shader

MAX_INTEGER_SAMPLES

Maximum number of samples supported in integer format multisample buffers

MAX_RECTANGLE_TEXTURE_SIZE

A rough estimate of the largest rectangular texture that the GL can handle

MAX_RENDERBUFFER_SIZE

Maximum supported size for renderbuffers

MAX_SAMPLES

Maximum samples for a framebuffer

MAX_SAMPLE_MASK_WORDS

Maximum number of sample mask words

MAX_TEXTURE_BUFFER_SIZE

Maximum number of texels allowed in the texel array of a texture buffer object

MAX_TEXTURE_SIZE

The value gives a rough estimate of the largest texture that the GL can handle

MAX_UNIFORM_BLOCK_SIZE

Maximum size in basic machine units of a uniform block

MAX_UNIFORM_BUFFER_BINDINGS

Maximum number of uniform buffer binding points on the context

MAX_VARYING_VECTORS

The number 4-vectors for varying variables

MAX_VERTEX_ATTRIBS

Maximum number of 4-component generic vertex attributes accessible to a vertex shader.

MAX_VERTEX_OUTPUT_COMPONENTS

Maximum number of components of output written by a vertex shader

MAX_VERTEX_TEXTURE_IMAGE_UNITS

Maximum supported texture image units that can be used to access texture maps from the vertex shader.

MAX_VERTEX_UNIFORM_BLOCKS

Maximum number of uniform blocks per vertex shader.

MAX_VERTEX_UNIFORM_COMPONENTS

Maximum number of individual floating-point, integer, or boolean values that can be held in uniform variable storage for a vertex shader

MAX_VERTEX_UNIFORM_VECTORS

Maximum number of 4-vectors that may be held in uniform variable storage for the vertex shader

MINOR_VERSION

Minor version number of the OpenGL API supported by the current context

SAMPLE_BUFFERS

Value indicating the number of sample buffers associated with the framebuffer

SUBPIXEL_BITS

An estimate of the number of bits of subpixel resolution that are used to position rasterized geometry in window coordinates

UNIFORM_BUFFER_OFFSET_ALIGNMENT

Minimum required alignment for uniform buffer sizes and offset

get(enum: ctypes.c_uint) int[source]

Get an integer limit

get_float(enum: ctypes.c_uint) float[source]

Get a float limit

get_int_tuple(enum: ctypes.c_uint, length: int)[source]

Get an enum as an int tuple

get_str(enum: ctypes.c_uint) str[source]

Get a string limit