arcade.gl package

Buffer

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

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')

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)

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)

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

The context this resource belongs to.

Type

arcade.gl.Context

property glo

The OpenGL resource id

Type

gl.GLuint

orphan(size=- 1, double: bool = False)

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

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

static release(ctx: Context, glo: ctypes.c_ulong)

Release/delete open gl buffer. This is automatically called when the object is garbage collected.

property size

The byte size of the buffer.

Type

int

write(data: Any, offset: int = 0)

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)

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)

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)

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)

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

Mark a context as the currently active one

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

The active context

property blend_func

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

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

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)

Disable one or more context flags:

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

enable(*args)

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)        

property error

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

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

Type

arcade.gl.Framebuffer

finish() → None

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

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

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

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

property patch_vertices

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: Get or set the point size.

property primitive_restart_index

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

query()

Create a query object for measuring rendering calls in opengl.

Return type

Query

property screen

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

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

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

The window this context belongs to.

Type

pyglet.Window

Framebuffer

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

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)

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)

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

A list of color attachments

Type

list of arcade.gl.Texture

property ctx

The context this object belongs to.

Type

arcade.gl.Context

property depth_attachment

Depth attachment

Type

arcade.gl.Texture

property depth_mask

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

The OpenGL id/name of the framebuffer

Type

GLuint

property height

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

Read framebuffer pixels

static release(ctx, framebuffer_id)

Destroys the framebuffer object

Parameters

• ctx – OpenGL context

• framebuffer_id – Framebuffer to destroy (glo)

property samples

Number of samples (MSAA)

Type

int

property size

Size as a (w, h) tuple

Type

tuple (int, int)

use(*, force: bool = False)

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

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

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)

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)

property ctx

The context this geometry belongs to.

Type

Geometry

flush() → None

Flush all the internally generated VertexArrays

property index_buffer

Index/element buffer if supplied at creation.

Type

Buffer

instance(program: arcade.gl.program.Program) → arcade.gl.vertex_array.VertexArray

Get the arcade.gl.VertexArray compatible with this program

property num_vertices

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

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

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)

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)

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

List of attribute information

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

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

The context this program belongs to

Type

arcade.gl.Context

property geometry_input

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

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

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

Type

int

property glo

The OpenGL resource id for this program

Type

int

static link(glo)

Link a shader program

property out_attributes

Out attributes names used in transform feedback

Type

list of str

use()

Activates the shader. This is normally done for you automatically.

Query

class arcade.gl.Query(ctx: Context)

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)

property ctx

The context this query object belongs to

Type

arcade.gl.Context

property primitives_generated

How many primitives a vertex or geometry shader processed

Type

int

static release(ctx, glos) → None

Delete this query object. This is automatically called when the object is garbage collected.

property samples_passed

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

Type

int

property time_elapsed

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)

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)

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

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

The byte size of the texture.

Type

int

property compare_func

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

Number of components in the texture

Type

int

property ctx

The context this texture belongs to

Type

Context

property depth

If this is a depth texture.

Type

bool

property dtype

The data type of each component

Type

str

property filter

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

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

• https://www.khronos.org/opengl/wiki/Sampler_Object#Filtering

Type

tuple (min filter, mag filter)

property glo

The OpenGL texture id

Type

GLuint

property height

The height of the texture in pixels

Type

int

read(level: int = 0, alignment: int = 1) → bytearray

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

static release(ctx: Context, glo: ctypes.c_ulong)

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 size

The size of the texture as a tuple

Type

tuple (width, height)

use(unit: int = 0) → None

Bind the texture to a channel,

Parameters

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

property width

The width of the texture in pixels

Type

int

property wrap_x

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

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

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)

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)

property ctx

The Context this object belongs to

Type

arcade.gl.Context

glo

property ibo

Element/index buffer

Type

arcade.gl.Buffer

property num_vertices

The number of vertices

Type

int

property program

The assigned program

Type

arcade.gl.Program

static release(ctx: Context, glo: ctypes.c_ulong)

Delete this object. This is automatically called when this object is garbage collected.

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

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)

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

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

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

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

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

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