pyglet.graphics.shader

exception MissingAttributeException

Exception for when a Shader has a missing attribute name.

exception MissingUniformException

Exception for when a Shader uniform is missing due to optimization or mispelling.

exception ShaderException
exception UnsupportedShaderType

Exception for trying to create an unsupported shader.

class ComputeShaderProgram(source: str) → None

Backend-agnostic compute shader program container.

Create a resource identity.

class PushConstants(
stages: tuple[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation']],
constants: list[tuple[str, Literal['mat4', 'vec4', 'vec3', 'vec2', 'float', 'int', 'uint', 'bool']]],
) → None
constants: list[tuple[str, Literal['mat4', 'vec4', 'vec3', 'vec2', 'float', 'int', 'uint', 'bool']]]
stages: tuple[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation']]
class Sampler(
name: str,
desc_set: int,
binding: int,
count: int = 1,
stages: Sequence[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation']] = ('fragment',),
) → None
binding: int
count: int = 1
desc_set: int
name: str
stages: Sequence[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation']] = ('fragment',)
class Shader(
source_string: str,
shader_type: Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation'],
) → None

Graphics shader.

Shader objects may be compiled on instantiation if OpenGL or already compiled in Vulkan. You can reuse a Shader object in multiple ShaderPrograms.

Initialize a shader type.

classmethod supported_shaders() → tuple[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation'], ...]

Return the supported shader types for this shader class.

Return type:

tuple[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation'], ...]

static get_string_class() → type[ShaderSource]

Return the proper ShaderSource class used to validate the shader.

Return type:

type[ShaderSource]

delete() → None

Delete the shader program’s backend resource.

Return type:

None

shader_type: ShaderType
class ShaderProgram(
*shaders: _AbstractShader,
vertex_layout: VertexLayout | None,
) → None

Backend-agnostic shader program container.

Concrete backends are responsible for compiling/linking shaders, introspecting attributes and uniforms, and providing API-specific program state management.

Initialize a shader program with an optional default attribute layout.

vertex_layout=None keeps the introspected attribute formats. An VertexLayout changes only the buffer interpretation of the named attributes; their component counts remain defined by the shader.

class ShaderProgramView(
program: _AbstractShaderProgram,
attribute_formats: dict[str, AttributeFormat],
attribute_keys: tuple[tuple[Any, ...], ...],
) → None

An interned ShaderProgram view with a specific vertex layout.

A view shares its owning program’s linked shader and uniforms, but caches its own vertex formats, instance divisors, and vertex-domain metadata.

Initialize a shader program with an optional default attribute layout.

vertex_layout=None keeps the introspected attribute formats. An VertexLayout changes only the buffer interpretation of the named attributes; their component counts remain defined by the shader.

delete() → None

Delete this shader program and release backend resources.

Return type:

None

set_instance_attributes(
**attributes: int,
) → ShaderProgramView

Deprecated adapter for creating a view with layout-owned divisors.

Return type:

ShaderProgramView

stop() → None

Unbind this shader program from rendering commands.

Return type:

None

use() → None

Bind this shader program for rendering commands.

Return type:

None

vertex_list(
count: int,
mode: GeometryMode,
batch: Batch | None = None,
group: Group | None = None,
storage: VertexStorage | None = None,
vertex_layout: VertexLayout | None = None,
**data: Any,
) → VertexList

Create a VertexList using this view’s attribute layout.

Parameters:
  • count (int) – The number of vertices in the list.

  • mode (GeometryMode) – A GeometryMode value determining how the vertices are drawn.

  • batch (Batch | None) – Batch to add the VertexList to, or None to use the default batch.

  • group (Group | None) – Group to add the VertexList to, or None to create a default ShaderGroup for this view.

  • storage (VertexStorage | None) – Storage created by the selected batch to use for the geometry, or None to use that batch’s default storage.

  • vertex_layout (VertexLayout | None) – Optional override for the vertex attribute formats. None uses this view’s geometry layout.

  • data (Any) – Initial data for each vertex attribute.

Return type:

VertexList

vertex_list_indexed(
count: int,
mode: GeometryMode,
indices: Sequence[int],
batch: Batch | None = None,
group: Group | None = None,
**data: Any,
) → IndexedVertexList

Create a IndexedVertexList.

Parameters:
  • count (int) – The number of vertices in the list.

  • mode (GeometryMode) – A GeometryMode value, such as POINTS, LINES, or TRIANGLES. This determines how the list is drawn in the given batch.

  • indices (Sequence[int]) – Sequence of integers giving indices into the vertex list.

  • batch (Batch | None) – Batch to add the VertexList to, or None if a Batch will not be used. Using a Batch is strongly recommended.

  • group (Group | None) – Group to add the VertexList to, or None to create a default ShaderGroup for this program.

  • data (Any) – Initial data for each vertex attribute.

Return type:

IndexedVertexList

vertex_list_instanced(
count: int,
mode: GeometryMode,
batch: Batch | None = None,
group: Group | None = None,
**data: Any,
) → InstanceVertexList
Return type:

InstanceVertexList

vertex_list_instanced_indexed(
count: int,
*,
mode: GeometryMode,
indices: Sequence[int],
batch: Batch | None = None,
group: Group | None = None,
**data: Any,
) → InstanceIndexedVertexList
Return type:

InstanceIndexedVertexList

property attribute_formats: dict[str, AttributeFormat]

Geometry formats used to store values for the shader inputs.

property attribute_key: tuple[Any, ...]

Stable, cached key describing the geometry formats by name.

property attribute_keys: tuple[tuple[Any, ...], ...]

Stable tuple describing geometry formats independently of shader locations.

property attributes: dict[str, ShaderAttribute]

Shader input metadata dictionary.

This property returns a dictionary containing metadata of all Attributes that were introspected in this ShaderProgram. Modifying this dictionary has no effect.

property geometry_layout: VertexLayout

Geometry layout derived by this legacy shader convenience API.

property handle: Any

Backend handle of the program this view represents.

property program: _AbstractShaderProgram

The ShaderProgram that owns this layout.

class ShaderSource(source: str, source_type: Any) → None

String source of shader used during load of a Shader instance.

Initialize source text for a backend shader type.

abstractmethod validate() → str

Return the validated shader source.

Return type:

str

class TransformFeedbackShaderProgram(
*shaders: _AbstractShader,
varyings: Sequence[str],
varying_buffer_type: Literal['interleaved', 'separate'] = 'separate',
vertex_layout: VertexLayout | None,
) → None

Backend-agnostic transform feedback shader program container.

Initialize a transform feedback shader program.

Parameters:
  • shaders (_AbstractShader) – One or more Shader instances.

  • varyings (Sequence[str]) – Names of vertex/geometry shader output variables to capture with transform feedback.

  • varying_buffer_type (Literal['interleaved', 'separate']) – Buffer packing mode for captured outputs: "separate" (one buffer per varying) or "interleaved" (single interleaved buffer).

Notes

This class is replaced by a backend-specific implementation at import time when a supported backend is active.

class UBOBindingManager(max_binding_count: int) → None

Manages global Uniform Block binding assignments.

add_explicit_binding(
shader_program: _AbstractShaderProgram,
ub_name: str,
binding: int,
) → None

Used when a uniform block has set its own binding point.

Return type:

None

binding_exists(binding: int) → bool

Check if a binding index value is in use.

Return type:

bool

get_binding(
shader_program: _AbstractShaderProgram,
ub_name: str,
) → int

Retrieve a global Uniform Block binding ID.

Return type:

int

get_name(binding: int) → str | None

Return the uniform name associated with the binding number.

Return type:

str | None

return_binding(index: int) → None
Return type:

None

property max_value: int
class UniformArrayBase(
uniform: Any,
gl_getter: Callable,
gl_setter: Callable,
gl_type: Any,
is_matrix: bool,
) → None

Backend-agnostic base for uniform array wrappers.

get() → UniformArrayBase
Return type:

UniformArrayBase

set(values: Sequence) → None
Return type:

None

class UniformBase(
*,
name: str,
uniform_type: int,
size: int,
location: Any,
program: Any,
matrix_types: tuple[int, ...],
array_wrapper_factory: Callable[[Any, Callable, Callable, Any, bool], UniformArrayBase],
) → None

Backend-agnostic base for uniform wrappers.

count
get
length
location
name
program
set
size
type
class UniformBlock(
program: _AbstractShaderProgram,
name: str,
index: int,
size: int,
binding: int,
uniforms: dict,
uniform_count: int,
) → None

Initialize a uniform block for a ShaderProgram.

bind(ubo: UniformBufferObject) → None

Bind a UBO to the binding point of this uniform block.

Return type:

None

create_ubo(
*,
copies_per_resource: int = 3,
alignment: int | None = None,
strict: bool = False,
) → UniformBufferObject

Create a new UniformBufferObject from this uniform block.

Return type:

UniformBufferObject

create_ubo_region(
*,
copies_per_resource: int = 3,
alignment: int | None = None,
strict: bool = False,
) → UniformBufferRegion

Create a ring-buffered region for updating and binding this uniform block.

Return type:

UniformBufferRegion

set_binding(binding: int) → None

Rebind the Uniform Block to a new binding index number.

This only affects the program this Uniform Block is derived from.

Binding value of 0 is reserved for the Pyglet’s internal uniform block named WindowBlock.

Warning

By setting a binding manually, the user is expected to manage all Uniform Block bindings for all shader programs manually. Since the internal global ID’s will be unaware of changes set by this function, collisions may occur if you use a lower number.

Note

You must call create_ubo to get another Uniform Buffer Object after calling this, as the previous buffers are still bound to the old binding point.

Return type:

None

binding: int
index: int
name: str
program: CallableProxyType[Callable[..., Any] | Any] | Any
size: int
uniform_count
uniforms: dict
view_cls: type[ctypes.Structure]
class UniformBlockDesc(*args, **kwargs)
bind_num: int
set_num: int
stages: tuple[Literal['vertex', 'fragment', 'geometry', 'compute', 'tesscontrol', 'tessevaluation']]
uniforms: tuple[tuple[str, str]]
get_default_shader() → ShaderProgram

A default shader for rendering primitives.

Return type:

ShaderProgram