SubViewport Occlusion

an offscreen view that culls what its own camera cannot see.

📄 Docs only

Tags: 3d subviewport culling performance

Occlusion culling skips drawing objects hidden behind others. Set SubViewport(use_occlusion=True) and the view runs its own Hi-Z occlusion cull for its own camera, sized to its own target and independent of the main camera. Only the view opts in here: the main scene renders without occlusion culling.

Inside the SubViewport a brown wall stands close to the camera with a dense field of blue cubes packed behind it. The wall hides the field, so the cull skips it and it is never drawn into the texture. Orange cubes on either side of the wall stay in view, spinning, to show the visible part of the feed still renders.

The feed is shown twice: on an in-world monitor through Material(albedo_map=sub_viewport) and as a picture-in-picture Sprite2D(texture=sub_viewport) in the bottom-left corner. Both bindings are assigned once and follow the live texture. The label at the top left reads the view’s cull counts each frame from app.last_telemetry: view_occlusion_total is how many instances the view submitted and view_occlusion_drawn how many survived the cull.

Source

# /// simvx
# tags = ["3d", "subviewport", "culling", "performance"]
# screenshot_frame = 60
# web = { disabled = true, reason = "per-view occlusion culling is desktop-only until the WebGPU Hi-Z port" }
# ///
"""SubViewport Occlusion: an offscreen view that culls what its own camera cannot see.

Occlusion culling skips drawing objects hidden behind others. Set
`SubViewport(use_occlusion=True)` and the view runs its own Hi-Z occlusion cull
for its own camera, sized to its own target and independent of the main camera.
Only the view opts in here: the main scene renders without occlusion culling.

Inside the SubViewport a brown wall stands close to the camera with a dense
field of blue cubes packed behind it. The wall hides the field, so the cull
skips it and it is never drawn into the texture. Orange cubes on either side of
the wall stay in view, spinning, to show the visible part of the feed still
renders.

The feed is shown twice: on an in-world monitor through
`Material(albedo_map=sub_viewport)` and as a picture-in-picture
`Sprite2D(texture=sub_viewport)` in the bottom-left corner. Both bindings are
assigned once and follow the live texture. The label at the top left reads the
view's cull counts each frame from `app.last_telemetry`: `view_occlusion_total`
is how many instances the view submitted and `view_occlusion_drawn` how many
survived the cull.
"""

from itertools import product

from simvx.core import (
    Anchor,
    Camera3D,
    CanvasLayer,
    Control,
    DirectionalLight3D,
    Label,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    Sprite2D,
    SubViewport,
)
from simvx.graphics import App

FIELD_COLS, FIELD_ROWS, FIELD_LAYERS = 10, 6, 4
FIELD_SPACING = 0.85
PIP_SIZE = 240


class SubViewportOcclusionScene(Node):
    def on_ready(self):
        self.add_child(Camera3D(position=(0, 2, 6), look_at=(0, 1, 0)))
        self.add_child(DirectionalLight3D(intensity=2.0, direction=(-0.4, -1.0, -0.6)))

        # The offscreen view: its own camera, light, wall and cubes. Its cull runs for this camera alone.
        sub = self.add_child(SubViewport(size=(512, 512), use_occlusion=True))
        sub.add_child(Camera3D(position=(0, 1.5, 9), look_at=(0, 1.5, -8)))
        sub.add_child(DirectionalLight3D(intensity=2.5, direction=(-0.5, -0.8, -0.5)))

        # Wide enough to hide the whole field, narrow enough to leave the flank cubes in view.
        wall_mat = Material(colour=(0.55, 0.42, 0.30), roughness=0.8)
        sub.add_child(MeshInstance3D(mesh=Mesh.box((5, 5, 0.4)), material=wall_mat, position=(0, 2, 2)))

        field_mesh = Mesh.box(0.32)
        field_mat = Material(colour=(0.30, 0.55, 0.85), roughness=0.5)
        x0 = -(FIELD_COLS - 1) * FIELD_SPACING / 2
        for cx, cy, cz in product(range(FIELD_COLS), range(FIELD_ROWS), range(FIELD_LAYERS)):
            position = (x0 + cx * FIELD_SPACING, 0.2 + cy * FIELD_SPACING, -2 - cz * FIELD_SPACING)
            sub.add_child(MeshInstance3D(mesh=field_mesh, material=field_mat, position=position))

        flank_mesh = Mesh.box(0.6)
        flank_mat = Material(colour=(0.95, 0.55, 0.2), roughness=0.4, emissive_colour=(0.4, 0.2, 0.05))
        self.flanks = [
            sub.add_child(
                MeshInstance3D(mesh=flank_mesh, material=flank_mat, position=(side * (3.8 + k * 0.4), 1.5, -k * 0.5))
            )
            for side in (-1, 1)
            for k in range(3)
        ]

        # The live feed on a monitor in the main scene.
        monitor_mat = Material(colour=(1, 1, 1), roughness=1.0, albedo_map=sub)
        self.add_child(MeshInstance3D(mesh=Mesh.box((3.4, 3.4, 0.08)), material=monitor_mat, position=(0, 1.2, 0)))

        hud = self.add_child(CanvasLayer())
        self.status = hud.add_child(Label("View cull: waiting for the first frame", anchor=Anchor.TOP_LEFT, inset=12))
        hud.add_child(
            Label(
                f"use_occlusion = True: {FIELD_COLS * FIELD_ROWS * FIELD_LAYERS} cubes behind the view's wall",
                anchor=Anchor.BOTTOM_RIGHT,
                inset=12,
            )
        )
        # Picture-in-picture: the same feed as a sprite, centred in an anchored frame.
        pip = hud.add_child(Control(anchor=Anchor.BOTTOM_LEFT, size=(PIP_SIZE, PIP_SIZE), inset=12))
        pip.add_child(Sprite2D(texture=sub, position=(PIP_SIZE / 2, PIP_SIZE / 2), width=PIP_SIZE, height=PIP_SIZE))

    def on_update(self, dt):
        for i, flank in enumerate(self.flanks):
            flank.rotate_y((0.8 + 0.1 * i) * dt)
        telemetry = self.app.last_telemetry
        if total := telemetry.get("view_occlusion_total"):
            drawn = telemetry["view_occlusion_drawn"]
            self.status.text = f"View cull: drew {drawn} of {total} instances, culled {total - drawn}"


if __name__ == "__main__":
    App(title="SubViewport Occlusion", width=1280, height=720).run(SubViewportOcclusionScene())