Instancing

import {  Camera,  createMaterialAsset,  Environment,  InstancedMeshRenderer,  MeshAsset,  pbrMaterialDefinition,} from "ignifx";import { bootExample } from "../_kit/boot.ts";import { thousands, wholeMetres } from "../_kit/format.ts";import { attachOrbit } from "../_kit/orbit.ts";import { readout, slider, toggle } from "../_kit/panel.ts";import { createLightRig } from "../_kit/stage.ts";import { CAPACITY, CLEAR_COLOR, layOutBelt, LOD, MESH, SHOT } from "./belt.ts";import type { AssetHandle, MaterialAsset, MeshAsset as MeshAssetType } from "ignifx";/** * Twenty thousand asteroids, one draw call. * * ## The slab is yours * * An `InstancedMeshRenderer` draws one mesh many times, each copy placed by its own matrix. The * matrices live in a `Float32Array` this file owns: sixteen floats per rock, column-major, the * layout `Transform.worldMatrix` already uses. `setMatrices` hands the renderer the array itself, * not a copy, so the array has to stay alive and stay at least `count * 16` floats long. Moving a * rock is a write into the array followed by `markDirty()`; drawing fewer is `setCount`, which * uploads nothing. * * ## Three settings fixed when the renderer is built * * `capacity`, `gpuCulling` and which mesh is the LOD partner are baked in when the renderer is first * drawn. Changing one later is refused with `IGX-0717`, and the field goes back to the value being * drawn. So the GPU-culling and LOD toggles below build a **new** renderer — which is what a * graphics-settings screen has to do too. The LOD `distance` and `band` are not in that set, so the * distance slider is an ordinary assignment. * * The two toggles are not independent. Lite picks each rock's mesh in the culling compute pass, so * a LOD partner on a renderer with `gpuCulling: false` is accepted and never used: every rock draws * the full-detail mesh. The panel keeps them honest — culling off takes the partner with it, and * the partner on brings culling back. * * `belt.ts` beside this file lays the ring out and writes the matrices. */bootExample({  title: "Instancing",  settings: {    rendering: { clearColor: CLEAR_COLOR, features: { shadows: false } },  },  setup({ app, panel, random, flags }) {    const eye = app.world.createEntity("Main Camera");    eye.addComponent(Camera, { near: 0.5, far: 600, fov: SHOT.fov });    attachOrbit(app, eye, {      yaw: SHOT.yaw,      pitch: SHOT.pitch,      distance: SHOT.distance,      target: SHOT.target,      minDistance: 6,      maxDistance: 320,    });    // One sun and a cool bounce: the rocks are lit, not shadowed. Shadows are off in `settings`    // because a 20,000-instance caster pass is a different lesson, and a directional shadow map    // fitted around a 110-metre belt would be a blur at any resolution worth paying for.    createLightRig(app, {      focus: SHOT.target,      keyPosition: { x: -60, y: 34, z: -40 },      keyIntensity: 5.2,      fillIntensity: 0.7,      fillColor: { r: 0.42, g: 0.55, b: 0.9, a: 1 },      rimIntensity: 1.6,      rimPosition: { x: 52, y: 12, z: 46 },      shadows: false,    });    app.world.createEntity("Environment").addComponent(Environment).imageProcessing.toneMapping = "aces";    const rock: AssetHandle<MaterialAsset> = createMaterialAsset(      app,      pbrMaterialDefinition({        name: "instancing/rock",        baseColor: { r: 0.55, g: 0.51, b: 0.46, a: 1 },        metallic: 0,        roughness: 0.95,      }),      [],    );    // This file holds the three handles for the page's life; each renderer only borrows them.    const near: AssetHandle<MeshAssetType> = MeshAsset.sphere(app, {      diameter: MESH.diameter,      segments: MESH.segments,    });    const far: AssetHandle<MeshAssetType> = MeshAsset.sphere(app, {      diameter: MESH.diameter,      segments: MESH.lodSegments,    });    // Allocated once, filled once, and handed to Lite by reference for the life of the page.    const slab = new Float32Array(CAPACITY * 16);    layOutBelt(slab, CAPACITY, random);    const belt = app.world.createEntity("Asteroid belt");    // The frame-time probe needs 420 rendered frames, which SwiftShader cannot rasterise at 20,000    // instances in its time limit. The engine's per-frame cost is the same for any count once the    // slab is static, so a benchmark draws a tenth of the belt.    let drawn = flags.isBench ? CAPACITY / 10 : CAPACITY;    let gpuCulling = true;    let useLod = true;    let lodDistance: number = LOD.distance;    let renderer = build(null);    /**     * Creates the renderer the current settings describe, replacing the one before it.     *     * @param previous - The renderer being replaced, or `null` for the first.     * @returns The live component.     */    function build(previous: InstancedMeshRenderer | null): InstancedMeshRenderer {      // `destroy` lands at the end of the frame, so the old belt draws nothing until then. Not      // `enabled = false`: that hides the entity's node, which the new renderer shares.      if (previous !== null) {        previous.setCount(0);        previous.destroy();      }      const created = belt.addComponent(InstancedMeshRenderer, {        mesh: near,        materials: [rock],        capacity: CAPACITY,        gpuCulling,        castShadows: false,        receiveShadows: false,        lod: useLod ? { mesh: far, distance: lodDistance, band: LOD.band } : null,      });      created.setMatrices(slab, drawn);      return created;    }    panel({      title: "Instancing",      groups: [        {          label: "Belt",          controls: [            slider(              "Drawn",              { min: 0, max: CAPACITY, step: 100, format: thousands },              {                value: drawn,                change: (value: number): void => {                  // No re-upload: the slab is unchanged and only the active range moves.                  drawn = Math.round(value);                  renderer.setCount(drawn);                },              },            ),            readout("Instances", (): string => thousands(renderer.count)),          ],        },        {          label: "Culling and detail",          controls: [            // Each toggle reads the other's variable back, so switching one moves the other with it.            toggle("GPU culling", {              value: gpuCulling,              change: (on: boolean): void => {                gpuCulling = on;                useLod = useLod && on;                renderer = build(renderer);              },              read: (): boolean => gpuCulling,            }),            toggle("LOD partner", {              value: useLod,              change: (on: boolean): void => {                useLod = on;                gpuCulling = gpuCulling || on;                renderer = build(renderer);              },              read: (): boolean => useLod,            }),            // Live on the renderer that is drawing, and remembered for the next one a toggle builds;            // it does nothing while the LOD partner is off.            slider(              "LOD distance",              { min: 8, max: 160, step: 2, format: wholeMetres },              {                value: lodDistance,                change: (value: number): void => {                  lodDistance = value;                  const lod = renderer.lod;                  if (lod !== null) {                    lod.distance = value;                  }                },                read: (): number => lodDistance,              },            ),          ],        },        {          label: "Frame",          collapsed: true,          controls: [readout("Draw calls", (): string => String(app.renderer.drawCalls))],        },      ],    });  },});