Model loading

import { Camera, Environment, MODEL_ASSET_TYPE, Model } from "ignifx";import { bootExample } from "../_kit/boot.ts";import { percent } from "../_kit/format.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 model is asking for a handle and assigning it. `app.assets.load` answers at once with a * handle that is still loading; a `Model` given one shows nothing until it arrives, then shows it on * that frame. The panel reads the handle's state and progress while that happens. * * Every load is paired with a release. An asset nobody holds is collected `gcDelay` seconds later, * or at once with `gc()`, which is what "Release the others" does. The opening model is awaited * before `app.start()`, so the first frame already has it; a model asked for later arrives at the * start of a frame, in `PreUpdate`. *//** Bytes in a kibibyte, for the Held readout. */const BYTES_PER_KIB = 1024;/** 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: {      // The site's dark `--bg` a shade deeper. The studio probe loads with its skybox off, so this      // colour is all that shows behind the subject.      clearColor: { r: 0.043, g: 0.059, b: 0.094, a: 1 },      // Read once, when `app.start()` registers the scene; asking afterwards is `IGX-0704`.      features: { shadows: true },    },  },  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,      // Steeper than half the 38-degree field of view, so the floor fills the frame behind the subject.      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 });    // 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")      // `studio.environment.json` loads with its skybox off, so the component says the same rather      // than being reported as `IGX-0711`.      .addComponent(Environment, { environment, skybox: { enabled: false, size: 20 } });    sky.imageProcessing.toneMapping = "aces";    sky.imageProcessing.exposure = EXPOSURE;    // After the `Environment`, so the fade reuses it rather than making a second one.    const ground = await createGridGround(app, { fade: true });    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 => percent(held.get(current)?.progress ?? 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())),          ],        },      ],    });  },});