simvx.core.graphics.shader_bindings

The per-material resources a custom shader declares, read from its source.

A ShaderMaterial reaches its own resources through group 2 of the custom shader ABI: binding 0 is the std140 uniform block, and binding 1 upwards are SEPARATED textures and samplers. Which name lives at which binding is stated by the shader author, in the shader, so both backends have to read it back out of the source to bind anything to it.

This module is that reader, and it is deliberately backend-free: the Vulkan renderer parses the GLSL a material was written in, the web exporter parses the WGSL naga emitted from it, and the two must agree on the same (name, binding) pairs or a texture would land on the wrong sampler in the browser. Keeping one implementation of the model, with one notion of what is supported, is what makes that agreement checkable rather than hopeful.

Anything the model cannot express – a combined sampler, a storage image, a cube or array texture, a second uniform block – raises :class:ShaderBindingError naming the declaration and its line, so an author hears about it from the tool that read the file rather than from a pipeline failure three layers down.

The reader is a lexical one. Comments are stripped before anything is matched, so commenting a declaration out really does remove it from the model, but the preprocessor is NOT evaluated: a declaration inside #if 0, one produced by a macro, and one living in an #included chunk are all invisible to it (an included texture would then fail pipeline creation, having never been declared in the layout). Declare a material’s textures and samplers in the stage source itself.

Module Contents

Classes

ResourceBinding	One texture or sampler a shader declares in the material group.
MaterialBindings	The material group’s declared textures and samplers, sorted by binding.

Functions

parse_material_bindings	Read the material group’s texture and sampler declarations from one stage.
material_bindings_for_stages	The material-group model of a whole material, from whichever stages it has.

Data

__all__
MATERIAL_GROUP
UNIFORM_BINDING
MAX_MATERIAL_TEXTURES
MAX_MATERIAL_SAMPLERS

API

simvx.core.graphics.shader_bindings.__all__

[‘MATERIAL_GROUP’, ‘MAX_MATERIAL_SAMPLERS’, ‘MAX_MATERIAL_TEXTURES’, ‘MaterialBindings’, ‘ResourceBi…

simvx.core.graphics.shader_bindings.MATERIAL_GROUP

2

simvx.core.graphics.shader_bindings.UNIFORM_BINDING

0

simvx.core.graphics.shader_bindings.MAX_MATERIAL_TEXTURES

8

simvx.core.graphics.shader_bindings.MAX_MATERIAL_SAMPLERS

4

exception simvx.core.graphics.shader_bindings.ShaderBindingError

Bases: ValueError

A custom shader declares a per-material resource neither backend can bind.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

class simvx.core.graphics.shader_bindings.ResourceBinding

One texture or sampler a shader declares in the material group.

name: str

None

binding: int

None

line: int

None

class simvx.core.graphics.shader_bindings.MaterialBindings

The material group’s declared textures and samplers, sorted by binding.

textures: tuple[simvx.core.graphics.shader_bindings.ResourceBinding, ...]

()

samplers: tuple[simvx.core.graphics.shader_bindings.ResourceBinding, ...]

()

property is_empty: bool

True when the shader declares no texture and no sampler.

texture_binding(name: str) → int

The binding number the named texture is declared at, or -1 if absent.

merged_with(other: simvx.core.graphics.shader_bindings.MaterialBindings) → simvx.core.graphics.shader_bindings.MaterialBindings

Combine two stages’ models, requiring any shared name to agree.

A vertex and a fragment stage may each declare the same texture (a displacement map read in both), and they must place it at the same binding: there is one descriptor set behind both stages.

simvx.core.graphics.shader_bindings.parse_material_bindings(source: str | None, *, language: str = 'glsl') → simvx.core.graphics.shader_bindings.MaterialBindings

Read the material group’s texture and sampler declarations from one stage.

language is "glsl" (a desktop shader stage) or "wgsl" (what the web exporter transpiled, or a hand-written escape hatch stage). Returns an empty model for None / textureless sources. Raises

Class:

ShaderBindingError on a declaration the ABI cannot express, naming the offending line.

simvx.core.graphics.shader_bindings.material_bindings_for_stages(vertex_source: str | None, fragment_source: str | None, *, wgsl_vertex: str | None = None, wgsl_fragment: str | None = None) → simvx.core.graphics.shader_bindings.MaterialBindings

The material-group model of a whole material, from whichever stages it has.

Hand-written WGSL wins over GLSL for a stage, matching the escape hatch the web exporter honours, so a material written in WGSL reports the bindings the browser will actually see. The two stages are merged: a name declared in both must sit at the same binding.