Model loading

import { Camera, Environment, MODEL_ASSET_TYPE, Model } from "ignifx";import { bootExample } from "../_kit/boot.ts";import { attachOrbit } from "../_kit/orbit.ts";import { bind, button, readout, select, toggle } from "../_kit/panel.ts";import { createGridGround, createLightRig, loadEnvironment } from "../_kit/stage.ts";import { fit, START_SUBJECT, SUBJECT_RADIUS, SUBJECTS, TARGET_HEIGHT } from "./subjects.ts";import type { AssetHandle, ModelAsset } from "ignifx";/** * Loading a glTF, watching it arrive, swapping it for another, and handing the memory back. * * The asset service is reference counted, and this example is the whole of what that means in * practice. `app.assets.load` answers with an `AssetHandle` **immediately** — still `"loading"`, * with a `progress` between 0 and 1 — so a game assigns it and carries on; the panel's Handle group * is that handle's own fields, read four times a second. Assigning a still-loading handle to * `Model.model` is allowed and is the normal thing to do: the model appears on the frame its * delivery lands in. * * The two rules worth taking away: * * 1. **Every `load` needs one `release`.** Two loads of one address answer with the same handle and *    a higher `refCount`, and the value is unloaded when the count reaches zero — after *    `assets.gcDelay` seconds, or at once when something calls `assets.gc()`. "Release the others" *    below does exactly that, and the Held readout is the bytes it gave back. * 2. **Await before `start()`, assign after it.** A load that finishes before the loop is running *    settles at once, so the opening subject is on screen in the first frame and a capture of it is *    reproducible. A load that finishes afterwards settles in `PreUpdate`, which is what makes the *    progress readout worth having. * * The measured bounds of the three models, and the arithmetic that stands each of them on the floor * at one height, are in `subjects.ts` beside this file. *//** How the panel writes a fraction: `progress` is `0…1`, bytes-weighted where sizes are known. */const PERCENT = 100;/** Bytes in a kibibyte, for the Held readout. */const BYTES_PER_KIB = 1024;/** * The clear colour, which is the site's dark `--bg` a shade deeper. * * @remarks * `studio.environment.json` loads its `.env` with the skybox off — the probe's cube map is a * mid-grey softbox room, which is right as light and wrong as a background — so what shows behind * the subject is this colour and nothing else. */const CLEAR_COLOR = { r: 0.043, g: 0.059, b: 0.094, a: 1 };/** The exposure the studio probe is graded at, chosen so the grid reads without flattening a metal. */const EXPOSURE = 1.15;bootExample({  title: "Model loading",  settings: {    rendering: {      clearColor: CLEAR_COLOR,      msaaSamples: 4,      // Read once, when `app.start()` registers the scene; asking afterwards is `IGX-0704`.      features: { shadows: true },    },    time: { fixedDeltaTime: 1 / 60 },  },  async setup({ app, panel }) {    const focus = { x: 0, y: TARGET_HEIGHT / 2, z: 0 };    const eye = app.world.createEntity("Main Camera");    eye.addComponent(Camera, { near: 0.05, far: 200, fov: 38 });    const orbit = attachOrbit(app, eye, {      yaw: 34,      // 24 degrees, not the 16 this started at: with a 38-degree vertical field of view the top of      // the frame is 19 degrees above centre, so any pitch under that leaves the ground plane's      // horizon — and a band of empty clear colour above it — in shot.      pitch: 24,      minDistance: 0.9,      maxDistance: 12,      idleDegreesPerSecond: 6,    });    orbit.frame({ center: focus, radius: SUBJECT_RADIUS }, 1.15);    createLightRig(app, { focus, keyIntensity: 2.2, rimIntensity: 0.9, shadowDarkness: 0.28 });    // Wide enough that its far edge is past the vanishing line at this camera pitch, so the frame    // reads as a floor rather than as a tile in the void. One grid cell is one metre at any size.    const ground = await createGridGround(app, { size: 60 });    // Both loads are awaited before the loop runs, so neither needs a frame pumped to settle. The    // `.env` also pulls the BRDF table Lite requires, from the `rendering.brdfLut` default address.    const first: AssetHandle<ModelAsset> = app.assets.load(SUBJECTS[START_SUBJECT]?.address ?? "", {      type: MODEL_ASSET_TYPE,    });    const environment = loadEnvironment(app, "studio");    await Promise.all([first.promise, environment.promise]);    const sky = app.world      .createEntity("Environment")      // `skybox` is decided when the `.env` loads, not here: `studio.environment.json` declares      // `skyboxEnabled: false`, so the component is told the same thing rather than left at its      // default and reported as `IGX-0711`. The background is the clear colour.      .addComponent(Environment, { environment, clearColor: CLEAR_COLOR, skybox: { enabled: false, size: 20 } });    sky.imageProcessing.toneMapping = "aces";    sky.imageProcessing.exposure = EXPOSURE;    const entity = app.world.createEntity("Subject");    const subject = entity.addComponent(Model, { castShadows: true, receiveShadows: true });    /** Every handle this example is holding, by the label that loaded it. One release each. */    const held = new Map<string, AssetHandle<ModelAsset>>([[START_SUBJECT, first]]);    let current = START_SUBJECT;    /**     * Shows one subject, loading it the first time it is asked for.     *     * @param label - A key of `SUBJECTS`.     */    const show = (label: string): void => {      const next = SUBJECTS[label];      if (next === undefined) {        return;      }      // Swapping a model is one assignment: `Model` compares the loaded asset with the one it      // instantiated and rebuilds its subtree on the next sync. A handle asked for the first time      // is still loading when it is assigned, so the model appears on the frame its delivery lands      // in — the asset lifetime, visible.      const handle = held.get(label) ?? app.assets.load<ModelAsset>(next.address, { type: MODEL_ASSET_TYPE });      held.set(label, handle);      current = label;      subject.model = handle;      const placement = fit(next, TARGET_HEIGHT);      entity.transform.localPosition.set(placement.offset.x, placement.offset.y, placement.offset.z);      entity.transform.localScale.set(placement.scale, placement.scale, placement.scale);    };    show(START_SUBJECT);    /** Drops every handle but the one on screen, and collects now rather than in `gcDelay` seconds. */    const releaseOthers = (): void => {      for (const [label, handle] of held) {        if (label === current) {          continue;        }        handle.release();        held.delete(label);      }      // Without this the values live for `assets.gcDelay` seconds (five by default) in case      // something asks for them again, which is the right default and the wrong demonstration.      app.assets.gc();      app.log.info("model-loading: holding", held.size, "model handles");    };    /**     * How many bytes the manifest says the held models weigh.     *     * @returns The sum over every held address, from `AssetManifestEntry.bytes`.     */    const heldBytes = (): number => {      let total = 0;      for (const handle of held.values()) {        const entry = app.assets.manifest.entries.find((candidate) => candidate.address === handle.address);        total += entry?.bytes ?? 0;      }      return total;    };    /**     * How many of the held handles have not arrived yet.     *     * @returns The count; zero except in the frames right after a swap to a model this page has     * not asked for before.     */    const loadingCount = (): number => {      let count = 0;      for (const handle of held.values()) {        if (handle.state === "loading") {          count += 1;        }      }      return count;    };    panel({      title: "Model loading",      groups: [        {          label: "Subject",          controls: [            select("Model", Object.keys(SUBJECTS), { value: START_SUBJECT, change: show }),            button("Release the others", releaseOthers),            // `active = false` hides an entity, `destroy()` removes it (`skills/ignifx/SKILL.md`            // gotcha 6). The grid is switched off to look at a silhouette, not rebuilt.            toggle("Grid", bind(ground.entity, "active")),          ],        },        {          label: "Handle",          controls: [            readout("Address", (): string => held.get(current)?.address ?? "—"),            readout("State", (): string => held.get(current)?.state ?? "released"),            readout("Progress", (): string => `${((held.get(current)?.progress ?? 0) * PERCENT).toFixed(0)}%`),            readout("Holders", (): string => String(held.get(current)?.refCount ?? 0)),            readout(              "Held",              (): string =>                `${String(held.size)} model${held.size === 1 ? "" : "s"} · ${(heldBytes() / BYTES_PER_KIB).toFixed(0)} KiB`,            ),          ],        },        {          label: "Frame",          collapsed: true,          controls: [            readout("Draw calls", (): string => String(app.renderer.drawCalls)),            readout("Still loading", (): string => String(loadingCount())),          ],        },      ],    });  },});