Shader / Program

class arcade.gl.Program(ctx: Context, *, vertex_shader: str, fragment_shader: str | None = None, geometry_shader: str | None = None, tess_control_shader: str | None = None, tess_evaluation_shader: str | None = None, varyings: list[str] | None = None, varyings_capture_mode: str = 'interleaved')[source]

Bases:

Compiled and linked shader program.

Currently supports

  • vertex shader

  • fragment shader

  • geometry shader

  • tessellation control shader

  • tessellation evaluation shader

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

Parameters:
  • ctx – The context this program belongs to

  • vertex_shader (optional) – Vertex shader source

  • fragment_shader (optional) – Fragment shader source

  • geometry_shader (optional) – Geometry shader source

  • tess_control_shader (optional) – Tessellation control shader source

  • tess_evaluation_shader (optional) – Tessellation evaluation shader source

  • varyings (optional) – List of out attributes used in transform feedback.

  • varyings_capture_mode (optional) – The capture mode for transforms. "interleaved" means all out attribute will be written to a single buffer. "separate" means each out attribute will be written separate buffers. Based on these settings the transform() method will accept a single buffer or a list of buffer.

attribute_key: str

Internal cache key used with vertex arrays

property ctx: Context

The context this program belongs to.

property glo: int

The OpenGL resource id for this program.

property attributes: Iterable[AttribFormat]

List of attribute information.

property varyings: list[str]

Out attributes names used in transform feedback.

property out_attributes: list[str]

Out attributes names used in transform feedback.

Alias for varyings.

property varyings_capture_mode: str

Get the capture more for transform feedback (single, multiple).

This is a read only property since capture mode can only be set before the program is linked.

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.

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.

property geometry_vertices: int

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

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]

Deletes a program. This is normally called automatically when the program is garbage collected.

Parameters:
  • ctx – The context this program belongs to

  • prog_id – The OpenGL resource id

🧙 self[item] Uniform | UniformBlock[source]

Get a uniform or uniform block

🧙 self[key] = value[source]

Set a uniform value.

Example:

program['color'] = 1.0, 1.0, 1.0, 1.0
program['mvp'] = projection @ view @ model
Parameters:
  • key – The uniform name

  • value – The uniform value

set_uniform_safe(name: str, value: Any)[source]

Safely set a uniform catching KeyError.

Parameters:
  • name – The uniform name

  • value – The uniform value

set_uniform_array_safe(name: str, value: list[Any])[source]

Safely set a uniform array.

Arrays can be shortened by the glsl compiler not all elements are determined to be in use. This function checks the length of the actual array and sets a subset of the values if needed. If the uniform don’t exist no action will be done.

Parameters:
  • name – Name of uniform

  • value – List of values

use()[source]

Activates the shader.

This is normally done for you automatically.

static compile_shader(source: str, shader_type: int) c_uint[source]

Compile the shader code of the given type.

Parameters:
  • source – The shader source code

  • shader_type – The type of shader to compile. GL_VERTEX_SHADER, GL_FRAGMENT_SHADER etc.

Returns:

The created shader id

Link a shader program

class arcade.gl.ComputeShader(ctx: Context, glsl_source: str)[source]

Bases:

A higher level wrapper for an OpenGL compute shader.

Parameters:
  • ctx – The context this shader belongs to.

  • glsl_source – The GLSL source code for the compute shader.

property glo: int

The name/id of the OpenGL resource

run(group_x=1, group_y=1, group_z=1) None[source]

Run the compute shader.

When running a compute shader we specify how many work groups should be executed on the x, y and z dimension. The size of the work group is defined in the compute shader.

// Work group with one dimension. 16 work groups executed.
layout(local_size_x=16) in;
// Work group with two dimensions. 256 work groups executed.
layout(local_size_x=16, local_size_y=16) in;
// Work group with three dimensions. 4096 work groups executed.
layout(local_size_x=16, local_size_y=16, local_size_z=16) in;

Group sizes are 1 by default. If your compute shader doesn’t specify a size for a dimension or uses 1 as size you don’t have to supply this parameter.

Parameters:
  • group_x – The number of work groups to be launched in the X dimension.

  • group_y – The number of work groups to be launched in the y dimension.

  • group_z – The number of work groups to be launched in the z dimension.

🧙 self[item] Uniform | UniformBlock[source]

Get a uniform or uniform block

🧙 self[key] = value[source]

Set a uniform value

delete() None[source]

Destroy the internal compute shader object.

This is normally not necessary, but depends on the garbage collection configured in the context.

static delete_glo(ctx, prog_id)[source]

Low level method for destroying a compute shader by id.

Parameters:
  • ctx – The context this program belongs to.

  • prog_id – The OpenGL id of the program.

class arcade.gl.uniform.Uniform(ctx, program_id, location, name, data_type, array_length)[source]

Bases:

A Program uniform

Parameters:
  • ctx – The context

  • program_id – The program id to which this uniform belongs

  • location – The uniform location

  • name – The uniform name

  • data_type – The data type of the uniform

  • array_length – The array length of the uniform

property location: int

The location of the uniform in the program

property name: str

Name of the uniform

property array_length: int

Length of the uniform array. If not an array 1 will be returned

property components: int

How many components for the uniform.

A vec4 will for example have 4 components.

getter
setter
class arcade.gl.uniform.UniformBlock(glo: int, index: int, size: int, name: str)[source]

Bases:

Wrapper for a uniform block in shaders.

Parameters:
  • glo – The OpenGL object handle

  • index – The index of the uniform block

  • size – The size of the uniform block

  • name – The name of the uniform

glo

The OpenGL object handle

index

The index of the uniform block

size

The size of the uniform block

name

The name of the uniform block

property binding: int

Get or set the binding index for this uniform block

getter()[source]

The getter function for this uniform block.

Returns self.

setter(value: int)[source]

The setter function for this uniform block.

Parameters:

value – The binding index to set.

class arcade.gl.glsl.ShaderSource(ctx: ArcadeGlContext, source: str, common: Iterable[str] | None, source_type: PyGLenum)[source]

Bases:

GLSL source container for making source parsing simpler.

We support locating out attributes, applying #defines values and injecting common source.

Parameters:
  • ctx – The context this framebuffer belongs to

  • source – The GLSL source code

  • common – Common source code to inject

  • source_type – The shader type

property version: int

The glsl version

property out_attributes: list[str]

The out attributes for this program

inject_common_sources(common: Iterable[str] | None) None[source]

Inject common source code into the shader source.

Parameters:

common – A list of common source code strings to inject

get_source(*, defines: dict[str, str] | None = None) str[source]

Return the shader source

Parameters:

defines – Defines to replace in the source.

static apply_defines(lines: list[str], defines: dict[str, str]) list[str][source]

Locate and apply #define values

Parameters:
  • lines – List of source lines

  • defines – dict with name: value pairs.