Custom Shader Textures

sampling a texture and blending from a ShaderMaterial.

▶ Run in browser

Tags: 3d

Demonstrates:

• ShaderMaterial.set_texture() bound to the texture2D the shader declares

• Separated texture + sampler declarations in the material’s own group

• transparent=True: an alpha-blended custom material over opaque geometry

• A tiled floor receding to the horizon: the minified half of the mip chain

• Rebinding a texture on a LIVE material: T swaps all three surfaces to a second image mid-frame, and the next frame samples it

• The same scene rendering identically on the Vulkan and web backends

Controls: A / D - Orbit camera T - Swap the texture every surface samples Escape - Quit

Usage: uv run python examples/features/3d/custom_shader_texture.py uv run python examples/features/3d/custom_shader_texture.py –test

Source

"""Custom Shader Textures: sampling a texture and blending from a ShaderMaterial.

Demonstrates:
  - ShaderMaterial.set_texture() bound to the texture2D the shader declares
  - Separated texture + sampler declarations in the material's own group
  - transparent=True: an alpha-blended custom material over opaque geometry
  - A tiled floor receding to the horizon: the minified half of the mip chain
  - Rebinding a texture on a LIVE material: T swaps all three surfaces to a
    second image mid-frame, and the next frame samples it
  - The same scene rendering identically on the Vulkan and web backends

Controls:
    A / D       - Orbit camera
    T           - Swap the texture every surface samples
    Escape      - Quit

Usage:
    uv run python examples/features/3d/custom_shader_texture.py
    uv run python examples/features/3d/custom_shader_texture.py --test
"""

import math
import sys

import numpy as np

from simvx.core import Camera3D, DirectionalLight3D, Input, Key, Material, Mesh, MeshInstance3D, Node, on_input
from simvx.graphics import App, ShaderMaterial

# A material's own resources live in set 2: the uniform block at binding 0, then
# a SEPARATED texture and sampler, which is what both backends can bind (a
# combined `sampler2D` uniform has no WebGPU equivalent).
TEXTURED_VERT = """\
#version 450
layout(location = 0) in vec3 inPosition;
layout(location = 1) in vec3 inNormal;
layout(location = 2) in vec2 inUV;

layout(set = 0, binding = 0) uniform Camera {
    mat4 view;
    mat4 proj;
};
layout(std430, set = 1, binding = 0) readonly buffer Transforms {
    mat4 models[];
};

layout(location = 0) out vec2 fragUV;

void main() {
    mat4 model = models[gl_InstanceIndex];
    fragUV = inUV;
    gl_Position = proj * view * model * vec4(inPosition, 1.0);
}
"""

TEXTURED_FRAG = """\
#version 450
layout(location = 0) in vec2 fragUV;
layout(location = 0) out vec4 outColour;

layout(set = 2, binding = 0) uniform Params {
    float tint;
    float alpha;
    float uv_scale;
};
layout(set = 2, binding = 1) uniform texture2D albedo;
layout(set = 2, binding = 2) uniform sampler albedoSampler;

void main() {
    // uv_scale > 1 tiles the texture: the floor uses it, so the far half of the
    // surface is minified and reads from the texture's mip chain.
    vec4 texel = texture(sampler2D(albedo, albedoSampler), fragUV * uv_scale);
    outColour = vec4(texel.rgb * tint, texel.a * alpha);
}
"""


def checkerboard(size: int = 64, cells: int = 8) -> np.ndarray:
    """An RGBA checkerboard: orange and blue squares, no asset file needed."""
    pixels = np.zeros((size, size, 4), dtype=np.uint8)
    step = size // cells
    ys, xs = np.mgrid[0:size, 0:size]
    dark = ((xs // step) + (ys // step)) % 2 == 0
    pixels[dark] = (230, 120, 40, 255)
    pixels[~dark] = (40, 90, 220, 255)
    return pixels


def diagonals(size: int = 64, cells: int = 8) -> np.ndarray:
    """The swap target: green and violet diagonal bands, same size, no file."""
    pixels = np.zeros((size, size, 4), dtype=np.uint8)
    step = size // cells
    ys, xs = np.mgrid[0:size, 0:size]
    band = ((xs + ys) // step) % 2 == 0
    pixels[band] = (60, 200, 110, 255)
    pixels[~band] = (150, 60, 210, 255)
    return pixels


class TextureShaderScene(Node):
    """A textured cube behind a transparent textured pane, over a tiled floor."""

    input_actions = {
        "orbit_left": [Key.A],
        "orbit_right": [Key.D],
        "swap_texture": [Key.T],
        "quit": [Key.ESCAPE],
    }

    def on_ready(self):
        self.angle = 0.0
        # The two images T alternates between, and the materials it rebinds.
        self._images = (checkerboard(), diagonals())
        self._image = 0
        self._materials: list[ShaderMaterial] = []
        self.camera = Camera3D(name="Camera", fov=60, near=0.1, far=100.0, position=(0.0, 1.2, 7.0))
        self.camera.look_at((0.0, 0.0, 0.0))
        self.add_child(self.camera)
        self.add_child(DirectionalLight3D(name="Sun", intensity=1.0))

        pixels = checkerboard()

        opaque = ShaderMaterial(vertex_source=TEXTURED_VERT, fragment_source=TEXTURED_FRAG)
        opaque.set_uniform("tint", 1.0)
        opaque.set_uniform("alpha", 1.0)
        opaque.set_uniform("uv_scale", 1.0)
        opaque.set_texture("albedo", pixels)
        self._materials.append(opaque)
        cube = MeshInstance3D(
            name="TexturedCube",
            mesh=Mesh.cube(size=2.6),
            material=Material(colour=(1, 1, 1)),
            position=(0.0, 0.0, 0.0),
        )
        cube.shader_material = opaque
        self.add_child(cube)

        # The same shader, transparent: alpha comes out of the fragment shader
        # and the pipeline composites it over the cube behind.
        glass = ShaderMaterial(vertex_source=TEXTURED_VERT, fragment_source=TEXTURED_FRAG, transparent=True)
        glass.set_uniform("tint", 0.4)
        glass.set_uniform("alpha", 0.45)
        glass.set_uniform("uv_scale", 1.0)
        glass.set_texture("albedo", pixels)
        self._materials.append(glass)
        pane = MeshInstance3D(
            name="GlassPane",
            mesh=Mesh.cube(size=3.4),
            material=Material(colour=(1, 1, 1)),
            position=(0.0, 0.0, 2.4),
            scale=(1.0, 1.0, 0.02),
        )
        pane.shader_material = glass
        self.add_child(pane)

        # A floor tiling the same texture 24 times each way. Its far half is
        # minified far below one texel per pixel, which is the only part of a
        # scene that can tell whether a sampler reads the mip chain or clings to
        # level 0 -- so it is what keeps the two backends honest about sampling.
        floor_material = ShaderMaterial(vertex_source=TEXTURED_VERT, fragment_source=TEXTURED_FRAG)
        floor_material.set_uniform("tint", 0.85)
        floor_material.set_uniform("alpha", 1.0)
        floor_material.set_uniform("uv_scale", 24.0)
        floor_material.set_texture("albedo", pixels)
        self._materials.append(floor_material)
        floor = MeshInstance3D(
            name="TiledFloor",
            mesh=Mesh.cube(size=1.0),
            material=Material(colour=(1, 1, 1)),
            position=(0.0, -1.6, 0.0),
            scale=(60.0, 0.04, 60.0),
        )
        floor.shader_material = floor_material
        self.add_child(floor)

    @on_input(action="swap_texture")
    def _swap_texture(self, _event):
        """Rebind every surface's albedo to the other image, while it renders.

        set_texture() on a material already on screen is all a live swap takes.
        The texture lives in the material's own descriptor set -- the group the
        shader declares ``albedo`` in -- and that set is built to be updated after
        binding, so its texture descriptor may be rewritten while submitted frames
        are still reading it. Those frames may show either image; the ones after
        them sample the new one, with no pipeline rebuild and no reload.
        """
        self._image = 1 - self._image
        for material in self._materials:
            material.set_texture("albedo", self._images[self._image])
        return True

    def on_update(self, dt):
        if Input.is_action_pressed("quit"):
            self.app.quit()
        if Input.is_action_pressed("orbit_left"):
            self.angle -= dt
        if Input.is_action_pressed("orbit_right"):
            self.angle += dt
        radius = 7.0
        self.camera.position = (math.sin(self.angle) * radius, 1.2, math.cos(self.angle) * radius)
        self.camera.look_at((0.0, 0.0, 0.0))


def _selftest() -> bool:
    """Render headlessly and check the texture, the blend, and the live swap.

    The swap is pressed through the same action a player presses, and it is
    judged on captured pixels rather than on the material's own state: a rebind
    that never reached the descriptor set would leave the frame unchanged.
    """
    from simvx.core.testing import InputSimulator

    SWAP = 6
    FRAMES = 14

    app = App(width=320, height=240, title="Custom Shader Textures")
    scene = TextureShaderScene()
    sim = InputSimulator()

    def on_frame(idx: int, _t: float) -> bool:
        if idx == SWAP:
            sim.press_key(Key.T)
        elif idx == SWAP + 1:
            sim.release_key(Key.T)
        return True

    # The camera is still, so any difference between these two frames is the
    # texture and nothing else.
    before, after = app.run_headless(scene, frames=FRAMES, on_frame=on_frame, capture_frames=[SWAP - 1, FRAMES - 1])

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    lit = before[..., :3].astype(int)
    coloured = lit[lit.sum(axis=2) > 60]
    check(
        "the shader samples its texture and blends the pane over the cube",
        coloured.shape[0] > 500 and int(coloured.std(axis=0).max()) > 12,
        f"{coloured.shape[0]} lit pixels, colour spread {coloured.std(axis=0).max():.1f}",
    )

    # The checkerboard is orange/blue and the swap target is green/violet, so
    # the lit part of the frame moves toward green when the rebind lands.
    def greenness(frame: np.ndarray) -> float:
        rgb = frame[..., :3].astype(int)
        surface = rgb[rgb.sum(axis=2) > 60]
        return float(surface[:, 1].mean() - surface[:, 0].mean())

    moved = float(np.abs(after[..., :3].astype(int) - before[..., :3].astype(int)).mean())
    check(
        "T rebinds the live material and the next frames sample the new image",
        moved > 10.0 and greenness(after) > greenness(before) + 20.0,
        f"the frame moved {moved:.1f} per channel, green-over-red {greenness(before):.1f} -> {greenness(after):.1f}",
    )
    check(
        "and it is one image for all three surfaces",
        all(m.get_texture("albedo") is scene._images[1] for m in scene._materials),
        f"{len(scene._materials)} materials rebound to the same array",
    )

    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


def main():
    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(width=1024, height=640, title="Custom Shader Textures").run(TextureShaderScene())


if __name__ == "__main__":
    main()