"""Material: pure data (no GPU dependencies).
Backends (SDL3, Vulkan) extend this to add texture/GPU management.
"""
import logging
from typing import Literal
import numpy as np
log = logging.getLogger(__name__)
def _coerce_texture_source(source, field: str):
"""Coerce an ndarray texture source to ``uint8`` (warn on lossy converts).
String / bytes / ``None`` / ``Resource`` / ``Traversable`` sources pass
through unchanged: they are resolved later by the backend's texture
loader. Float arrays in ``[0, 1]`` are scaled to ``[0, 255]`` and cast
to ``uint8``; values outside that range trigger a one-line WARNING so
callers spot a stale gamma assumption.
"""
if not isinstance(source, np.ndarray):
return source
if source.dtype == np.uint8:
return source
if np.issubdtype(source.dtype, np.floating):
lo, hi = float(source.min()), float(source.max())
if lo < -1e-3 or hi > 1.0 + 1e-3:
log.warning(
"%s ndarray (dtype=%s) outside [0, 1] (min=%.3f, max=%.3f): "
"clipping before uint8 conversion drops detail.",
field, source.dtype, lo, hi,
)
return (np.clip(source, 0.0, 1.0) * 255.0 + 0.5).astype(np.uint8)
# Integer types other than uint8: clip to byte range and cast.
if np.issubdtype(source.dtype, np.integer):
log.warning(
"%s ndarray (dtype=%s): coercing to uint8; values outside [0, 255] are clipped.",
field, source.dtype,
)
return np.clip(source, 0, 255).astype(np.uint8)
raise TypeError(f"Unsupported {field} ndarray dtype: {source.dtype}")
[docs]
class Material:
"""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
"""
_next_uid: int = 0
__slots__ = (
"_uid",
"colour",
"metallic",
"roughness",
"blend",
"wireframe",
"double_sided",
"unlit",
"albedo_uri",
"normal_uri",
"metallic_roughness_uri",
"emissive_uri",
"ao_uri",
"albedo_tex_index",
"emissive_colour",
)
def __init__(
self,
colour: tuple[float, ...] | np.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,
):
"""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``).
"""
Material._next_uid += 1
self._uid = Material._next_uid
# Normalize colour to 4-component RGBA (as Python floats)
c = np.asarray(colour, dtype=np.float32).ravel()
if len(c) == 3:
c = np.append(c, 1.0)
self.colour = tuple(float(x) for x in c[:4])
self.metallic = float(metallic)
self.roughness = float(roughness)
self.blend = blend
self.wireframe = bool(wireframe)
self.double_sided = bool(double_sided)
self.unlit = bool(unlit)
# Texture URIs (backend loads actual GPU textures). ndarray sources
# are coerced to uint8 RGBA at construction time so backends never
# silently drop a float32 array because they only know how to
# upload one byte per channel.
self.albedo_uri = _coerce_texture_source(albedo_map, "albedo_map")
self.normal_uri = _coerce_texture_source(normal_map, "normal_map")
self.metallic_roughness_uri = _coerce_texture_source(
metallic_roughness_map, "metallic_roughness_map",
)
self.emissive_uri = _coerce_texture_source(emissive_map, "emissive_map")
self.ao_uri = _coerce_texture_source(ao_map, "ao_map")
# Direct GPU texture index (set by backend, overrides albedo_uri)
self.albedo_tex_index: int = -1
# Emissive colour packed as ``(R, G, B, intensity)``. ``None`` means no
# emissive contribution. ``emissive_strength`` is the explicit scalar
# form: if supplied, it folds into the 4th slot. When the caller
# passes a 3-tuple plus a strength we reuse the strength as the
# intensity; a 4-tuple plus a strength multiplies the two so both
# legacy and new call sites compose cleanly.
if emissive_colour is None and emissive_strength is None:
self.emissive_colour = None
else:
if emissive_colour is None:
rgb = (1.0, 1.0, 1.0)
intensity = float(emissive_strength)
else:
ec = tuple(float(x) for x in emissive_colour)
if len(ec) == 3:
rgb = ec
intensity = 1.0 if emissive_strength is None else float(emissive_strength)
elif len(ec) == 4:
rgb = ec[:3]
intensity = ec[3] * (1.0 if emissive_strength is None else float(emissive_strength))
else:
raise ValueError(
f"emissive_colour must be a 3- or 4-tuple, got length {len(ec)}",
)
self.emissive_colour = (*rgb, intensity)
[docs]
@property
def content_key(self) -> tuple:
"""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.
"""
def _h(v):
if v is None or isinstance(v, str | bytes | int | float | bool | tuple):
return v
try:
hash(v)
return v
except TypeError:
return ("<unhashable>", type(v).__name__, id(v))
return (
self.colour, self.metallic, self.roughness, self.blend,
self.wireframe, self.double_sided, self.unlit,
_h(self.albedo_uri), _h(self.normal_uri), _h(self.metallic_roughness_uri),
_h(self.emissive_uri), _h(self.ao_uri), self.albedo_tex_index,
self.emissive_colour,
)
[docs]
@property
def colour_bytes(self) -> bytes:
"""RGBA as 16 bytes (4x float32) for GPU upload."""
return np.array(self.colour, dtype=np.float32).tobytes()
@property
def emissive_strength(self) -> float:
"""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.
"""
return 0.0 if self.emissive_colour is None else float(self.emissive_colour[3])
[docs]
@emissive_strength.setter
def emissive_strength(self, value: float) -> None:
if self.emissive_colour is None:
self.emissive_colour = (1.0, 1.0, 1.0, float(value))
else:
self.emissive_colour = (*self.emissive_colour[:3], float(value))