simvx.graphics.material_slots

GPU material SSBO slot allocation, deduplication, and reclamation.

Extracted from :class:~simvx.graphics.scene_adapter.SceneAdapter so the material subsystem (the registry/dedup dicts, the SSBO numpy array, the free-list, and the weakref finalizers) lives on its own cohesive object rather than tangled into the scene-tree traversal adapter.

Module Contents

Classes

MaterialSlotManager

Allocates, deduplicates, and reclaims rows of the bindless material SSBO.

Data

__all__
log

API

simvx.graphics.material_slots.__all__

[‘MaterialSlotManager’]

simvx.graphics.material_slots.log

‘getLogger(…)’

class simvx.graphics.material_slots.MaterialSlotManager(renderer: Any, load_texture: collections.abc.Callable[..., int])

Allocates, deduplicates, and reclaims rows of the bindless material SSBO.

Converts simvx.core :class:Material objects into integer indices into a flat numpy SSBO array, deduplicating by content so two materials with identical rendering properties share one slot.

A slot is owned by every Material currently registered against it and is freed when the last of them dies: dedup means one row can have several owners, and releasing on the first death would leave the survivors rendering from a row that has been zeroed or handed to something else. Reclamation rides a weakref.finalize per owner, so a session that creates a Material per frame holds a flat slot count instead of walking the SSBO off the end.

Content is re-read on every registration: a Material that has been mutated since its last frame no longer matches the row it was sharing, so it is detached and re-slotted (into an identical row if one exists, otherwise a fresh one). Mutating one member of a dedup group therefore cannot change what its peers render. Registration of an unchanged Material is a dict lookup and a tuple compare.

Texture loading is delegated through the load_texture callable supplied at construction (the adapter owns the bindless texture manager); this class owns only material-slot bookkeeping.

Initialization

register(material: simvx.core.Material | None) → int

Convert a core Material to a Vulkan material index.

Deduplicates materials by content: two Material objects with identical rendering properties share the same SSBO slot, and the slot outlives whichever of them dies first.

release(mat_id: int) → None

Drop a dead Material’s ownership of its slot.

Called by the weakref.finalize attached to a Material when it goes out of scope. The row itself is reclaimed only once no registered Material still owns it.

upload() → None

Upload the material array to the renderer.