simvx.core.graphics.material

Material: pure data (no GPU dependencies).

Backends (SDL3, Vulkan) extend this to add texture/GPU management.

Module Contents

Classes

Material

Pure material data for rendering. Backend-agnostic.

Data

log

API

simvx.core.graphics.material.log

‘getLogger(…)’

class simvx.core.graphics.material.Material(colour: tuple[float, ...] | numpy.ndarray = (1.0, 1.0, 1.0, 1.0), metallic: float = 0.0, roughness: float = 0.5, blend: Literal[opaque, alpha, additive] = 'opaque', wireframe: bool = False, double_sided: bool = False, unlit: bool = False, albedo_map: str | bytes | None = None, normal_map: str | bytes | None = None, metallic_roughness_map: str | bytes | None = None, emissive_map: str | bytes | None = None, ao_map: str | bytes | None = None, emissive_colour: tuple[float, ...] | None = None, emissive_strength: float | None = None)[source]

Pure material data for rendering. Backend-agnostic.

Every map kwarg (albedo_map, normal_map, metallic_roughness_map, emissive_map, ao_map) accepts three forms:

  • str: filesystem path or asset URI; backend loads from disk via TextureManager.

  • bytes: raw image bytes (PNG / JPEG / etc.) decoded by the backend’s image loader.

  • numpy.ndarray: an in-memory texture, shape (H, W, C) where C is 1, 3, or 4. Coerced to uint8 at construction time so the GPU always sees byte-per-channel data; float32 arrays in [0, 1] are scaled, out-of-range floats log a WARNING and clip, and unsupported dtypes raise TypeError. Used by Procedural Planets and Q1K3 to bake gradient ramps without shipping PNGs.

Example: mat = Material(colour=(1, 0, 0, 1)) # Red mat = Material(colour=(0, 1, 0), blend=”alpha”) # Translucent green mat = Material(albedo_map=”textures/brick.png”) # On-disk texture mat = Material(albedo_map=numpy_rgba_uint8) # Numpy texture

Initialization

Initialize material with colour and properties.

Args: colour: RGBA (or RGB auto-expanded to 1.0 alpha) in [0-1] metallic: [0-1] metallic factor roughness: [0-1] roughness factor blend: “opaque”, “alpha”, “additive” wireframe: Render as wireframe double_sided: Disable backface culling unlit: Disable lighting (flat colour) albedo_map: Path or embedded bytes for albedo/diffuse texture (optional) normal_map: Path or embedded bytes for normal map texture (optional) metallic_roughness_map: Path or embedded bytes for metallic-roughness texture (optional) emissive_map: Path or embedded bytes for emissive texture (optional) ao_map: Path or embedded bytes for ambient occlusion texture (optional) emissive_colour: (R, G, B) or (R, G, B, intensity) packing. If a 4-tuple, the fourth component is the intensity multiplier (legacy/round-trip form). Prefer the 3-tuple form with the separate emissive_strength kwarg. emissive_strength: Scalar multiplier applied to the emissive RGB. Stored as the 4th component of emissive_colour. May be combined with a 3-tuple emissive_colour or used alone (an opaque-white default is supplied when emissive_colour is None).

__slots__

(‘_uid’, ‘colour’, ‘metallic’, ‘roughness’, ‘blend’, ‘wireframe’, ‘double_sided’, ‘unlit’, ‘albedo_u…

property content_key: tuple[source]

Hashable key representing all rendering-relevant properties.

Two materials with the same content_key are visually identical and can share a single GPU material slot. Texture fields that hold an unhashable source (e.g. a numpy ndarray passed via TextureManager) are fingerprinted by id() so the key stays hashable without mutating the source.

property colour_bytes: bytes[source]

RGBA as 16 bytes (4x float32) for GPU upload.

property emissive_strength: float[source]

Scalar emissive intensity (the 4th slot of emissive_colour).

Returns 0.0 when no emissive colour is configured. Setting this mutates the intensity component without changing the RGB; a default of opaque white is supplied when no colour is present yet.