arcade.gl package¶

Buffer¶

class arcade.gl.Buffer(ctx: Context, data: Optional[Any] = None, reserve: int = 0, usage: str = 'static')[source]¶

Bases: object

OpenGL buffer object. Buffers store byte data and upload it to graphics memory so shader programs can process the data. They are used for storage of vertex data, element data (vertex indexing), uniform block data etc.

Buffer objects should be created using arcade.gl.Context.buffer()

__init__(ctx: Context, data: Optional[Any] = None, reserve: int = 0, usage: str = 'static')[source]¶

Parameters

ctx (Context) – The context this buffer belongs to
data (Any) – The data this buffer should contain. It can be bytes or any object supporting the buffer protocol.
reserve (int) – Create a buffer of a specific byte size
usage (str) – A hit of this buffer is static or dynamic (can mostly be ignored)

bind_to_uniform_block(binding: int = 0, offset: int = 0, size: int = - 1)[source]¶

Bind this buffer to a uniform block location. In most cases it will be sufficient to only provice a binding location.

Parameters

binding (int) – The binding location
offset (int) – byte offset
size (int) – size of the buffer to bind.

copy_from_buffer(source: arcade.gl.buffer.Buffer, size=- 1, offset=0, source_offset=0)[source]¶

Copy data into this buffer from another buffer

Parameters

source (Buffer) – The buffer to copy from
size (int) – The amount of bytes to copy
offset (int) – The byte offset to write the data in this buffer
source_offset (int) – The byte offset to read from the source buffer

property ctx: Context¶

The context this resource belongs to.

Type: arcade.gl.Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx: Context, glo: ctypes.c_ulong)[source]¶: Release/delete open gl buffer. This is automatically called when the object is garbage collected.

property glo: ctypes.c_ulong¶

The OpenGL resource id

Type: gl.GLuint

orphan(size=- 1, double: bool = False)[source]¶

Re-allocate the entire buffer memory. This can be used to resize a buffer or for re-specification (orphan the buffer to avoid blocking).

If the current buffer is busy in redering operations it will be deallocated by OpenGL when completed.

Parameters

size (int) – New size of buffer. -1 will retain the current size.
double (bool) – Is passed in with True the buffer size will be doubled

read(size=- 1, offset=0) → bytes [source]¶

Read data from the buffer.

Parameters

size (int) – The bytes to read. -1 means the entire buffer (default)
offset (int) – Byte read offset

Return type

bytes

property size: int¶

The byte size of the buffer.

Type: int

write(data: Any, offset: int = 0)[source]¶

Write byte data to the buffer.

Parameters

data (bytes) – The byte data to write. This can be bytes or any object supporting the buffer protocol.
offset (int) – The byte offset

BufferDescription¶

class arcade.gl.BufferDescription(buffer: arcade.gl.buffer.Buffer, formats: str, attributes: Iterable[str], normalized: Optional[Iterable[str]] = None, instanced: bool = False)[source]¶

Bases: object

Buffer Object description used with arcade.gl.Geometry.

This class provides a Buffer object with a description of its content, allowing the a Geometry object to correctly map shader attributes to a program/shader.

The formats is a string providing the number and type of each attribute. Currently we only support f (float), i (integer) and B (unsigned byte).

normalized enumerates the attributes which must have their values normalized. This is useful for instance for colors attributes given as unsigned byte and normalized to floats with values between 0.0 and 1.0.

instanced allows this buffer to be used as instanced buffer. Each value will be used once for the whole geometry. The geometry will be repeated a number of times equal to the number of items in the Buffer.

Example:

# Describe my_buffer
# It contains two floating point numbers being a 2d position
# and two floating point numbers being texture coordinates.
# We expect the shader using this buffer to have an in_pos and in_uv attribute (exact name)
BufferDescription(
    my_buffer,
    '2f 2f',
    ['in_pos', 'in_uv'],
)

Parameters

buffer (Buffer) – The buffer to describe
formats (str) – The format of each attribute
attributes (list) – List of attributes names (strings)
normalized (list) – list of attribute names that should be normalized
instanced (bool) – True if this is per instance data

__init__(buffer: arcade.gl.buffer.Buffer, formats: str, attributes: Iterable[str], normalized: Optional[Iterable[str]] = None, instanced: bool = False)[source]¶

Parameters

buffer (Buffer) – The buffer to describe
formats (str) – The format of each attribute
attributes (list) – List of attributes names (strings)
normalized (list) – list of attribute names that should be normalized
instanced (bool) – True if this is per instance data

attributes¶: List of string attributes

buffer¶: The Buffer this description object describes

formats¶: Formats of each attribute

instanced¶: Instanced flag (bool)

normalized¶: List of normalied attributes

num_vertices¶: Number of vertices in the buffer

stride¶: The byte stride of the buffer

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_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

__init__(window: pyglet.window.BaseWindow, gc_mode: str = 'auto')[source]¶

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

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

Create a 2D depth texture

Parameters

int] size (Tuple[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(*args)[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)        

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

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

color_attachments (List[arcade.gl.Texture]) – List of textures we want to render into
depth_attachment (arcade.gl.Texture) – Depth texture

Return type

Framebuffer

gc()[source]¶: Run garbage collection of OpenGL objects for this context. This is only needed when gc_mode is context_gc.

property gc_mode: str¶: Set the garbage collection mode for OpenGL resources. Supported modes are:

# default: Auto ctx.gc_mode = “auto”

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¶: 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_ulong] = None, wrap_y: Optional[ctypes.c_ulong] = None, filter: Optional[Tuple[ctypes.c_ulong, ctypes.c_ulong]] = None) → 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

int] size (Tuple[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

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

Framebuffer¶

class arcade.gl.Framebuffer(ctx: Context, *, color_attachments=None, depth_attachment=None)[source]¶

Bases: object

An offscreen render target also called a Framebuffer Object in OpenGL. This implementation is using texture attachments. When creating a Framebuffer we supply it with textures we want our scene rendered into. The advantage of using texture attachments is the ability we get to keep working on the contents of the framebuffer.

The best way to create framebuffer is through arcade.gl.Context.framebuffer():

# Create a 100 x 100 framebuffer with one attachment
ctx.framebuffer(color_attachments=[ctx.texture((100, 100), components=4)])

# Create a 100 x 100 framebuffer with two attachments
# Shaders can be configured writing to the different layers
ctx.framebuffer(
    color_attachments=[
        ctx.texture((100, 100), components=4),
        ctx.texture((100, 100), components=4),
    ]
)

Parameters

ctx (Context) – The context this framebuffer belongs to
color_attachments (List[arcade.gl.Texture]) – List of color attachments.
depth_attachment (arcade.gl.Texture) – A depth attachment (optional)

__init__(ctx: Context, *, color_attachments=None, depth_attachment=None)[source]¶

Parameters

ctx (Context) – The context this framebuffer belongs to
color_attachments (List[arcade.gl.Texture]) – List of color attachments.
depth_attachment (arcade.gl.Texture) – A depth attachment (optional)

clear(color=(0.0, 0.0, 0.0, 0.0), *, depth: float = 1.0, normalized: bool = False)[source]¶

Clears the framebuffer:

# Clear framebuffer using the color red in normalized form
fbo.clear(color=(1.0, 0.0, 0.0, 1.0), normalized=True)
# Clear the framebuffer using arcade's colors (not normalized)
fb.clear(color=arcade.color.WHITE)

Parameters

color (tuple) – A 3 or 4 component tuple containing the color
depth (float) – Value to clear the depth buffer (unused)
normalized (bool) – If the color values are normalized or not

property color_attachments: List[arcade.gl.texture.Texture]¶

A list of color attachments

Type: list of arcade.gl.Texture

property ctx: Context¶

The context this object belongs to.

Type: arcade.gl.Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx, framebuffer_id)[source]¶

Destroys the framebuffer object

Parameters

ctx – OpenGL context
framebuffer_id – Framebuffer to destroy (glo)

property depth_attachment: arcade.gl.texture.Texture¶

Depth attachment

Type: arcade.gl.Texture

property depth_mask: bool¶

Get or set the depth mask (default: True). It determines if depth values should be written to the depth texture when depth testing is enabled.

The depth mask value is persistent all will automatically be applies every time the framebuffer is bound.

Type: bool

property glo: ctypes.c_ulong¶

The OpenGL id/name of the framebuffer

Type: GLuint

property height: int¶

The height of the framebuffer in pixels

Type: int

is_default = False¶: Is this the default framebuffer? (window buffer)

read(*, viewport=None, components=3, attachment=0, dtype='f1') → bytearray [source]¶: Read framebuffer pixels

property samples: int¶

Number of samples (MSAA)

Type: int

property size: Tuple[int, int]¶

Size as a (w, h) tuple

Type: tuple (int, int)

use(*, force: bool = False)[source]¶

Bind the framebuffer making it the target of all redering commands

Parameters: force (bool) – Force the framebuffer binding even if the system already believes it’s already bound.

property viewport: Tuple[int, int, int, int]¶

Get or set the framebuffer’s viewport. The viewport parameter are (x, y, width, height). It determines what part of the framebuffer should be redered to. By default the viewport is (0, 0, width, height).

The viewport value is persistent all will automatically be applies every time the framebuffer is bound.

Two or four integer values can be assigned:

# Explicitly set x, y, width, height
fb.viewport = 100, 100, 200, 200
# Implies 0, 0, 100, 100
fb.viewport = 100, 100

property width: int¶

The width of the framebuffer in pixels

Type: int

Geometry¶

class arcade.gl.Geometry(ctx: Context, content: Optional[Sequence[arcade.gl.types.BufferDescription]], index_buffer: arcade.gl.buffer.Buffer = None, mode=None, index_element_size: int = 4)[source]¶

Bases: object

A higher level abstraction of the VertexArray. It generates VertexArray instances on the fly internally matching the incoming program. This means we can render the same geometry with different programs as long as the Program and BufferDescription have compatible attributes.

Geometry objects should be created through arcade.gl.Context.geometry()

Parameters

ctx (Contex) – The context this object belongs to
content (list) – List of BufferDescriptions
index_buffer (Buffer) – Index/element buffer
mode (int) – The default draw mode

__init__(ctx: Context, content: Optional[Sequence[arcade.gl.types.BufferDescription]], index_buffer: arcade.gl.buffer.Buffer = None, mode=None, index_element_size: int = 4)[source]¶

property ctx: Context¶

The context this geometry belongs to.

Type: Geometry

flush() → None [source]¶: Flush all the internally generated VertexArrays

property index_buffer: Optional[arcade.gl.buffer.Buffer]¶

Index/element buffer if supplied at creation.

Type: Buffer

instance(program: arcade.gl.program.Program) → arcade.gl.vertex_array.VertexArray [source]¶: Get the arcade.gl.VertexArray compatible with this program

property num_vertices: int¶

Get or set the number of vertices. Be careful when modifying this properly and be absolutely sure what you are doing.

Type: int

render(program: arcade.gl.program.Program, *, mode: Optional[ctypes.c_ulong] = None, first: int = 0, vertices: Optional[int] = None, instances: int = 1) → None [source]¶

Render the geometry with a specific program.

Parameters

program (Program) – The Program to render with
mode (gl.GLenum) – Override what primitive mode should be used
first (int) – Offset start vertex
vertices (int) – Number of vertices to render
instances (int) – Number of instances to render

transform(program: arcade.gl.program.Program, buffer: arcade.gl.buffer.Buffer, *, first: int = 0, vertices: Optional[int] = None, instances: int = 1, buffer_offset: int = 0) → None [source]¶

Render with transform feedback. Instead of rendering to the screen or a framebuffer the result will instead end up in the buffer we supply.

If a geometry shader is used the output primitive mode is automatically detected.

Parameters

program (Program) – The Program to render with
buffer (Buffer) – The buffer to write the output
mode (gl.GLenum) – The input primitive mode
first (int) – Offset start vertex
vertices (int) – Number of vertices to render
instances (int) – Number of instances to render
buffer_offset (int) – Byte offset for the buffer

Program¶

class arcade.gl.Program(ctx: Context, *, vertex_shader: str, fragment_shader: str = None, geometry_shader: str = None, tess_control_shader: str = None, tess_evaluation_shader: str = None, out_attributes: List[str] = None)[source]¶

Bases: object

Compiled and linked shader program.

Currently supports vertex, fragment and geometry shaders. Transform feedback also supported when output attributes names are passed in the varyings parameter.

The best way to create a program instance is through arcade.gl.Context.program()

Access Uniforms via the [] operator. Example:

program['MyUniform'] = value

__init__(ctx: Context, *, vertex_shader: str, fragment_shader: str = None, geometry_shader: str = None, tess_control_shader: str = None, tess_evaluation_shader: str = None, out_attributes: List[str] = None)[source]¶

Create a Program.

Parameters

ctx (Context) – The context this program belongs to
vertex_shader (str) – vertex shader source
fragment_shader (str) – fragment shader source
geometry_shader (str) – geometry shader source
tess_control_shader (str) – tessellation control shader source
tess_evaluation_shader (str) – tessellation evaluation shader source
out_attributes (List[str]) – List of out attributes used in transform feedback.

attribute_key¶: Internal cache key used with vertex arrays

property attributes: Iterable[arcade.gl.types.AttribFormat]¶: List of attribute information

static compile_shader(source: str, shader_type: ctypes.c_ulong) → ctypes.c_ulong [source]¶

Compile the shader code of the given type.

shader_type could be GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, …

Returns the shader id as a GLuint

property ctx: Context¶

The context this program belongs to

Type: arcade.gl.Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx, prog_id)[source]¶

property geometry_input: int¶

The geometry shader’s input primitive type. This an be compared with GL_TRIANGLES, GL_POINTS etc. and is queried when the program is created.

Type: int

property geometry_output: int¶

The geometry shader’s output primitive type. This an be compared with GL_TRIANGLES, GL_POINTS etc. and is queried when the program is created.

Type: int

property geometry_vertices: int¶

The maximum number of vertices that can be emitted. This is queried when the program is created.

Type: int

property glo: int¶

The OpenGL resource id for this program

Type: int

static link(glo)[source]¶: Link a shader program

property out_attributes: List[str]¶

Out attributes names used in transform feedback

Type: list of str

use()[source]¶: Activates the shader. This is normally done for you automatically.

Query¶

class arcade.gl.Query(ctx: Context)[source]¶

Bases: object

A query object to perform low level measurements of OpenGL rendering calls.

The best way to create a program instance is through arcade.gl.Context.query()

Example usage:

query = ctx.query()
with query:
    geometry.render(..)

print('samples_passed:', query.samples_passed)
print('time_elapsed:', query.time_elapsed)
print('primitives_generated:', query.primitives_generated)

__init__(ctx: Context)[source]¶

property ctx: Context¶

The context this query object belongs to

Type: arcade.gl.Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx, glos) → None [source]¶: Delete this query object. This is automatically called when the object is garbage collected.

property primitives_generated: int¶

How many primitives a vertex or geometry shader processed

Type: int

property samples_passed: int¶

How many samples was written. These are per component (RGBA)

Type: int

property time_elapsed: int¶

The time elapsed in nanoseconds

Type: int

Texture¶

class arcade.gl.Texture(ctx: Context, size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Any = None, filter: Tuple[ctypes.c_ulong, ctypes.c_ulong] = None, wrap_x: ctypes.c_ulong = None, wrap_y: ctypes.c_ulong = None, target=3553, depth=False)[source]¶

Bases: object

An OpenGL texture. We can create an empty black texture or a texture from byte data. A texture can also be created with different datatypes such as float, integer or unsigned integer.

The best way to create a texture instance is through arcade.gl.Context.texture()

Supported dtype values are:

# Float formats
'f1': UNSIGNED_BYTE
'f2': HALF_FLOAT
'f4': FLOAT
# int formats
'i1': BYTE
'i2': SHORT
'i4': INT
# uint formats
'u1': UNSIGNED_BYTE
'u2': UNSIGNED_SHORT
'u4': UNSIGNED_INT

Parameters

ctx (Context) – The context the object belongs to
int] size (Tuple[int,) – The size of the texture
components (int) – The 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 any object supporting the buffer protocol.
data – The byte data of the texture. bytes or anything supporting the buffer protocol.
filter (Tuple[gl.GLuint,gl.GLuint]) – The minification/magnification filter of the texture
wrap_x (gl.GLuint) – Wrap mode x
wrap_y (gl.GLuint) – Wrap mode y

__init__(ctx: Context, size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Any = None, filter: Tuple[ctypes.c_ulong, ctypes.c_ulong] = None, wrap_x: ctypes.c_ulong = None, wrap_y: ctypes.c_ulong = None, target=3553, depth=False)[source]¶

A texture can be created with or without initial data. NOTE: Currently does not support multisample textures even thought samples is exposed.

Parameters

ctx (Context) – The context the object belongs to
size (Tuple[int,int]) – The size of the texture
components (int) – The 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 byte data of the texture. bytes or anything supporting the buffer protocol.
gl.GLuint] filter (Tuple[gl.GLuint,) – The minification/magnification filter of the texture
wrap_x (gl.GLuint) – Wrap mode x
wrap_y (gl.GLuint) – Wrap mode y
target (int) – The texture type
depth (bool) – creates a depth texture if True

build_mipmaps(base: int = 0, max_level: int = 1000) → None [source]¶

Generate mipmaps for this texture. Leaveing the default arguments will usually does the job. Building mipmaps will create several smaller versions of the texture (256 x 256, 128 x 128, 64 x 64, 32 x 32 etc) helping OpenGL in rendering a nicer version of texture when it’s rendered to the screen in smaller version.

Note that mipmaps will only be used if the texture filter is configured with a mipmap-type minification:

# Set up linear interpolating minification filter
texture.filter = ctx.LINEAR_MIPMAP_LINEAR, ctx.LINEAR

Parameters

base (int) – Level the mipmaps start at (usually 0)
max_level (int) – The maximum levels to generate

Also see: https://www.khronos.org/opengl/wiki/Texture#Mip_maps

property byte_size: int¶

The byte size of the texture.

Type: int

property compare_func: Optional[str]¶

Get or set the compare function for a depth texture:

texture.compare_func = None  # Disable depth comparison completely
texture.compare_func = '<='  # GL_LEQUAL
texture.compare_func = '<'   # GL_LESS
texture.compare_func = '>='  # GL_GEQUAL
texture.compare_func = '>'   # GL_GREATER
texture.compare_func = '=='  # GL_EQUAL
texture.compare_func = '!='  # GL_NOTEQUAL
texture.compare_func = '0'   # GL_NEVER
texture.compare_func = '1'   # GL_ALWAYS

Type: str

property components: int¶

Number of components in the texture

Type: int

property ctx: Context¶

The context this texture belongs to

Type: Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx: Context, glo: ctypes.c_ulong)[source]¶

Destroy the texture. This is called automatically when the object is garbage collected.

Parameters

ctx (arcade.gl.Context) – OpenGL Context
glo (gl.GLuint) – The OpenGL texture id

property depth: bool¶

If this is a depth texture.

Type: bool

property dtype: str¶

The data type of each component

Type: str

property filter: Tuple[int, int]¶

Get or set the (min, mag) filter for this texture. These are rules for how a texture interpolates. The filter is specified for minification and magnification.

Default value is LINEAR, LINEAR. Can be set to NEAREST, NEAREST for pixelated graphics.

When mipmapping is used the min filter needs to be one of the MIPMAP variants.

Accepted values:

# Enums can be accessed on the context or arcade.gl
NEAREST                # Nearest pixel
LINEAR                 # Linear interpolate
NEAREST_MIPMAP_NEAREST # Minification filter for mipmaps
LINEAR_MIPMAP_NEAREST  # Minification filter for mipmaps
NEAREST_MIPMAP_LINEAR  # Minification filter for mipmaps
LINEAR_MIPMAP_LINEAR   # Minification filter for mipmaps

Also see

Type: tuple (min filter, mag filter)

property glo: ctypes.c_ulong¶

The OpenGL texture id

Type: GLuint

property height: int¶

The height of the texture in pixels

Type: int

read(level: int = 0, alignment: int = 1) → bytearray [source]¶

Read the contents of the texture.

Parameters

level (int) – The texture level to read
alignment (int) – Alignment of the start of each row in memory in number of bytes. Possible values: 1,2,4

Return type

bytearray

property size: Tuple[int, int]¶

The size of the texture as a tuple

Type: tuple (width, height)

use(unit: int = 0) → None [source]¶

Bind the texture to a channel,

Parameters: unit (int) – The texture unit to bind the texture.

property width: int¶

The width of the texture in pixels

Type: int

property wrap_x: int¶

Get or set the horizontal wrapping of the texture. This decides how textures are read when texture coordinates are outside the [0.0, 1.0] area. Default value is REPEAT.

Valid options are:

# Note: Enums can also be accessed in arcade.gl
# Repeat pixels on the y axis
texture.wrap_x = ctx.REPEAT
# Repeat pixels on the y axis mirrored
texture.wrap_x = ctx.MIRRORED_REPEAT
# Repeat the edge pixels when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_EDGE
# Use the border color (black by default) when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_BORDER

Type: int

property wrap_y: int¶

Get or set the horizontal wrapping of the texture. This decides how textures are read when texture coordinates are outside the [0.0, 1.0] area. Default value is REPEAT.

Valid options are:

# Note: Enums can also be accessed in arcade.gl
# Repeat pixels on the x axis
texture.wrap_x = ctx.REPEAT
# Repeat pixels on the x axis mirrored
texture.wrap_x = ctx.MIRRORED_REPEAT
# Repeat the edge pixels when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_EDGE
# Use the border color (black by default) when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_BORDER

Type: int

write(data: Union[bytes, arcade.gl.buffer.Buffer], level: int = 0, viewport=None) → None [source]¶

Write byte data to the texture. This can be bytes or a Buffer.

Parameters

data (Union[bytes,Buffer]) – bytes or a Buffer with data to write
level (int) – The texture level to write
viewport (tuple) – The are of the texture to write. 2 or 4 component tuple

VertexArray¶

class arcade.gl.VertexArray(ctx: Context, program: arcade.gl.program.Program, content: Sequence[arcade.gl.types.BufferDescription], index_buffer: arcade.gl.buffer.Buffer = None, index_element_size: int = 4)[source]¶

Bases: object

Wrapper for Vertex Array Objects (VAOs). This objects should not be instantiated from user code. Use arcade.gl.Geometry instead. It will create VAO instances for you automatically. There is a lot of complex interaction between programs and vertex arrays that will be done for you automatically.

__init__(ctx: Context, program: arcade.gl.program.Program, content: Sequence[arcade.gl.types.BufferDescription], index_buffer: arcade.gl.buffer.Buffer = None, index_element_size: int = 4)[source]¶

property ctx: Context¶

The Context this object belongs to

Type: arcade.gl.Context

delete()[source]¶: Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx: Context, glo: ctypes.c_ulong)[source]¶: Delete this object. This is automatically called when this object is garbage collected.

glo¶

property ibo: Optional[arcade.gl.buffer.Buffer]¶

Element/index buffer

Type: arcade.gl.Buffer

property num_vertices: int¶

The number of vertices

Type: int

property program: arcade.gl.program.Program¶

The assigned program

Type: arcade.gl.Program

render(mode: ctypes.c_ulong, first: int = 0, vertices: int = 0, instances: int = 1)[source]¶

Render the VertexArray to the currently active framebuffer.

Parameters

mode (GLuint) – Primitive type to render. TRIANGLES, LINES etc.
first (int) – The first vertex to render from
vertices (int) – Number of vertices to render
instances (int) – OpenGL instance, used in using vertices over and over

transform(buffer: arcade.gl.buffer.Buffer, mode: ctypes.c_ulong, output_mode: ctypes.c_ulong, first: int = 0, vertices: int = 0, instances: int = 1, buffer_offset=0)[source]¶

Run a transform feedback.

Parameters

buffer (Buffer) – The buffer to write the output
mode (gl.GLenum) – The input primitive mode
output:mode (gl.GLenum) – The output primitive mode
first (int) – Offset start vertex
vertices (int) – Number of vertices to render
instances (int) – Number of instances to render
buffer_offset (int) – Byte offset for the buffer (target)

ShaderException¶

class arcade.gl.ShaderException[source]¶

Bases: Exception

Exception class for shader-specific problems.

geometry¶

A module providing commonly used geometry

arcade.gl.geometry.cube(size=(1.0, 1.0, 1.0), center=(0.0, 0.0, 0.0)) → arcade.gl.vertex_array.Geometry [source]¶

Creates a cube with normals and texture coordinates.

Parameters

size (tuple) – size of the cube as a 3-component tuple
center (tuple) – center of the cube as a 3-component tuple

Return type

arcade.gl.Geometry

Returns

A cube

arcade.gl.geometry.quad_2d(size: Tuple[float, float] = (1.0, 1.0), pos: Tuple[float, float] = (0.0, 0.0)) → arcade.gl.vertex_array.Geometry [source]¶

Creates 2D quad Geometry using 2 triangle strip with texture coordinates.

Parameters

size (tuple) – width and height
pos (float) – Center position x and y

Return type

A Geometry instance.

arcade.gl.geometry.quad_2d_fs() → arcade.gl.vertex_array.Geometry [source]¶: Creates a screen aligned quad using normalized device coordinates

arcade.gl.geometry.screen_rectangle(bottom_left_x: float, bottom_left_y: float, width: float, height: float) → arcade.gl.vertex_array.Geometry [source]¶

Creates screen rectangle using 2 triangle strip with texture coordinates.

Parameters

bottom_left_x (float) – Bottom left x position
bottom_left_y (float) – Bottom left y position
width (float) – Width of the rectangle
height (float) – Height of the rectangle