@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/view/particles/effect/ParticleEmitterInspectorView.js

@@ -0,0 +1,606 @@
+import {
+    EMITTER_BLEND,
+    EMITTER_PROJECTION,
+} from "../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import {
+    EMITTER_RENDER_CHANNEL_COMPONENTS,
+    EMITTER_RENDER_CHANNELS,
+} from "../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js";
+import LabelView from "../../../../src/view/common/LabelView.js";
+import EmptyView from "../../../../src/view/elements/EmptyView.js";
+import View from "../../../../src/view/View.js";
+
+/**
+ * Everything about an effect that is not its simulation: how fast it emits, how its particles are
+ * blended and oriented, which per-particle attribute drives which render channel, its bounds sphere,
+ * and the attribute schema those channels can name.
+ *
+ * It belongs to neither editing layer, and both need it — a program that writes `position` does
+ * nothing visible until something says that `position` is what the renderer should place the quad
+ * at — so it is a third panel over the same document rather than a section of either.
+ *
+ * ## Why the attribute schema is here
+ *
+ * The layout is the contract between the simulation and the renderer: the VM addresses attributes by
+ * the word offsets it assigns, and the emitter record stores those same offsets for the render
+ * channels. Editing it is editing that contract, which is why adding one is guarded by
+ * {@link ParticleEffectDocument#addAttribute} rather than done by hand, and why removing one unbinds
+ * the channels that named it.
+ */
+
+/**
+ * Emitter fields that are a plain number, and the range a control should hold them to.
+ * @type {Array<{key: string, label: string, min: number, step: number, help: string}>}
+ */
+const NUMERIC_FIELDS = [
+    {
+        key: "spawn_rate",
+        label: "spawn rate",
+        min: 0,
+        step: 1,
+        help: "Particles per second. Integrated on the GPU — the CPU never counts particles.",
+    },
+    {
+        key: "bounds_radius",
+        label: "bounds radius",
+        min: 0,
+        step: 0.1,
+        help: "Radius of the emitter's bounding sphere. Under AVBOIT it marks the depth slices the "
+            + "effect may occlude in, so an effect that outruns it occludes at the wrong depth.",
+    },
+];
+
+/**
+ * Feature flags, as toggles.
+ * @type {Array<{key: string, label: string, help: string}>}
+ */
+const FLAG_FIELDS = [
+    { key: "lighting", label: "lighting", help: "Forward-shade the billboards with scene lighting." },
+    { key: "soft_depth", label: "soft depth", help: "Fade against scene depth instead of cutting into it." },
+    { key: "sort", label: "sort", help: "Depth-sort this emitter's particles." },
+    { key: "cull", label: "cull", help: "Sleep the simulation when the emitter is out of view." },
+];
+
+export class ParticleEmitterInspectorView extends View {
+    /**
+     * Handlers that push the document's value back into a control, run on every refresh.
+     * @type {Array<function():void>}
+     */
+    #readers = [];
+
+    /**
+     * @type {EmptyView}
+     */
+    #attributes;
+
+    /**
+     * @type {EmptyView}
+     */
+    #channels;
+
+    /**
+     * The rows listing the attributes. Separate from the section around it so the "add" row below
+     * survives a rebuild with whatever is typed into it.
+     * @type {EmptyView}
+     */
+    #attribute_rows;
+
+    /**
+     * The row each render channel picker sits in, by channel name. Held so a mis-sized binding can
+     * be marked on the row rather than on the control inside it.
+     * @type {Map<string, View>}
+     */
+    #channel_rows = new Map();
+
+    /**
+     * The render channel pickers, by channel name. Held so their value can be re-read without
+     * rebuilding them: a rebuilt <select> closes under the pointer and loses whatever was focused.
+     * @type {Map<string, HTMLSelectElement>}
+     */
+    #channel_selects = new Map();
+
+    /**
+     * The attribute schema the option lists were last built from.
+     *
+     * Only the attributes decide the *shape* of the channel pickers and the attribute list, and a
+     * change to the effect is far more often something else - a spawn rate, a node parameter. So
+     * they are rebuilt when this changes and left alone otherwise, which is also what keeps a
+     * half-typed attribute name from being swept away by an unrelated edit.
+     *
+     * @type {string}
+     */
+    #attributes_signature = "";
+
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     */
+    constructor({ effect }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-emitter-inspector');
+
+        /**
+         * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+         */
+        this.effect = effect;
+
+        this.addChild(this.#buildIdentity());
+        this.addChild(this.#buildEmission());
+        this.addChild(this.#buildAppearance());
+
+        this.#channels = new EmptyView({ classList: ['section', 'channels'] });
+        this.#channels.addChild(new LabelView("render channels", { classList: ['heading'] }));
+        this.addChild(this.#channels);
+
+        this.#buildChannelRows();
+
+        this.#attributes = new EmptyView({ classList: ['section', 'attributes'] });
+        this.#attributes.addChild(new LabelView("attributes", { classList: ['heading'] }));
+        this.addChild(this.#attributes);
+
+        this.#attribute_rows = new EmptyView({ classList: ['attribute-rows'] });
+
+        this.#attributes.addChild(this.#attribute_rows);
+        this.#attributes.addChild(this.#buildAttributeAdder());
+
+        this.bindSignal(effect.on.changed, this.refresh, this);
+        this.on.linked.add(this.refresh, this);
+
+        this.refresh();
+    }
+
+    /**
+     * Re-read everything from the document.
+     *
+     * Values are pushed into every control; the option lists and the attribute rows are rebuilt only
+     * when the attributes themselves changed, because that is the only thing their shape follows and
+     * rebuilding them on every edit would sweep away whatever an author was in the middle of.
+     */
+    refresh() {
+        for (const reader of this.#readers) {
+            reader();
+        }
+
+        const signature = this.effect.attributes
+            .map(attribute => `${attribute.name}:${attribute.components}`)
+            .join(",");
+
+        if (signature !== this.#attributes_signature) {
+            this.#attributes_signature = signature;
+
+            this.#writeChannelOptions();
+            this.#buildAttributes();
+        }
+
+        this.#writeChannelValues();
+    }
+
+    /**
+     * @returns {View}
+     */
+    #buildIdentity() {
+        const section = section_view("effect");
+
+        const field = text_input(this.effect.name);
+
+        field.addEventListener('change', () => {
+            this.effect.name = field.value;
+            this.effect.touch();
+        });
+
+        this.#readers.push(() => {
+            if (document.activeElement !== field) {
+                field.value = this.effect.name;
+            }
+        });
+
+        section.addChild(row("name", field));
+
+        return section;
+    }
+
+    /**
+     * @returns {View}
+     */
+    #buildEmission() {
+        const section = section_view("emission");
+
+        for (const field of NUMERIC_FIELDS) {
+            section.addChild(this.#numericRow(field));
+        }
+
+        section.addChild(this.#vectorRow("bounds centre", "bounds_center", 3));
+
+        return section;
+    }
+
+    /**
+     * @returns {View}
+     */
+    #buildAppearance() {
+        const section = section_view("appearance");
+
+        section.addChild(this.#enumRow("blend", "blend", EMITTER_BLEND));
+        section.addChild(this.#enumRow("projection", "projection", EMITTER_PROJECTION));
+
+        for (const flag of FLAG_FIELDS) {
+            section.addChild(this.#flagRow(flag));
+        }
+
+        section.addChild(this.#vectorRow("flipbook (cols, rows)", "flipbook", 2));
+        section.addChild(this.#vectorRow("atlas (u, v, w, h)", "atlas_region", 4));
+
+        return section;
+    }
+
+    /**
+     * One picker per render channel. The channels are fixed, so the rows are built once; only their
+     * options and their value follow the document.
+     */
+    #buildChannelRows() {
+        for (const channel of EMITTER_RENDER_CHANNELS) {
+            const select = document.createElement('select');
+
+            select.addEventListener('change', () => {
+                if (select.value === "") {
+                    delete this.effect.emitter.render[channel];
+                } else {
+                    this.effect.emitter.render[channel] = select.value;
+                }
+
+                this.effect.touch();
+            });
+
+            this.#channel_selects.set(channel, select);
+
+            const channel_row = row(channel, select);
+
+            this.#channel_rows.set(channel, channel_row);
+            this.#channels.addChild(channel_row);
+        }
+    }
+
+    /**
+     * Re-read the options every picker offers from the effect's attributes.
+     */
+    #writeChannelOptions() {
+        for (const select of this.#channel_selects.values()) {
+            const none = document.createElement('option');
+
+            none.value = "";
+            none.textContent = "— not bound —";
+
+            const options = [none];
+
+            for (const attribute of this.effect.attributes) {
+                const option = document.createElement('option');
+
+                option.value = attribute.name;
+                option.textContent = `${attribute.name} (${attribute.components})`;
+
+                options.push(option);
+            }
+
+            select.replaceChildren(...options);
+        }
+    }
+
+    /**
+     * Point every picker at what the emitter binds now. A binding naming an attribute that is gone
+     * reads as unbound, which is what the record would carry.
+     */
+    #writeChannelValues() {
+        for (const [channel, select] of this.#channel_selects) {
+            const bound = this.effect.emitter.render[channel];
+            const attribute = this.effect.attributes.find(candidate => candidate.name === bound);
+
+            select.value = attribute === undefined ? "" : bound;
+
+            this.#markChannelWidth(channel, attribute);
+        }
+    }
+
+    /**
+     * Mark a channel whose attribute is narrower than the render pass reads.
+     *
+     * The read is a fixed width — see {@link EMITTER_RENDER_CHANNEL_COMPONENTS} — so a narrow
+     * attribute is not a smaller read, it is a read into whatever the layout packed next. Nothing
+     * downstream objects to it, which is exactly why it is worth saying here.
+     *
+     * @param {string} channel
+     * @param {{name: string, components: number}|undefined} attribute
+     */
+    #markChannelWidth(channel, attribute) {
+        const channel_row = this.#channel_rows.get(channel);
+        const wanted = EMITTER_RENDER_CHANNEL_COMPONENTS[channel];
+
+        const mismatched = attribute !== undefined && attribute.components < wanted;
+
+        channel_row.setClass('mismatched', mismatched);
+
+        if (mismatched) {
+            channel_row.el.setAttribute(
+                'title',
+                `The render pass reads ${wanted} words for '${channel}', and '${attribute.name}' is `
+                + `${attribute.components}. The rest comes from whatever the layout packed after it.`
+            );
+        } else {
+            channel_row.el.removeAttribute('title');
+        }
+    }
+
+    /**
+     * The per-particle attribute schema, with the word each occupies — which is what the VM
+     * addresses and what the emitter record stores for a render channel.
+     */
+    #buildAttributes() {
+        this.#attribute_rows.removeAllChildren();
+
+        let layout = null;
+
+        try {
+            layout = this.effect.buildLayout();
+        } catch (e) {
+            this.#attribute_rows.addChild(new LabelView(e.message, { classList: ['problem', 'error'] }));
+        }
+
+        for (const attribute of this.effect.attributes) {
+            const entry = new EmptyView({ classList: ['attribute'] });
+
+            const offset = layout === null || !layout.has(attribute.name)
+                ? "?"
+                : String(layout.offsetOf(attribute.name));
+
+            entry.addChild(new LabelView(attribute.name, { classList: ['name'] }));
+            entry.addChild(new LabelView(`w${offset} · ${attribute.components}c`, { classList: ['where'] }));
+
+            const remove = new EmptyView({ classList: ['remove'] });
+
+            remove.addChild(new LabelView("✕"));
+            remove.el.setAttribute('title', `Remove '${attribute.name}'`);
+            remove.el.addEventListener('click', () => this.effect.removeAttribute(attribute.name));
+
+            entry.addChild(remove);
+
+            this.#attribute_rows.addChild(entry);
+        }
+    }
+
+    /**
+     * @returns {View}
+     */
+    #buildAttributeAdder() {
+        const adder = new EmptyView({ classList: ['add-attribute'] });
+
+        const name = text_input("");
+
+        name.setAttribute('placeholder', 'new attribute');
+
+        const components = document.createElement('select');
+
+        for (const count of [1, 2, 3, 4]) {
+            const option = document.createElement('option');
+
+            option.value = String(count);
+            option.textContent = `${count}c`;
+
+            components.appendChild(option);
+        }
+
+        components.value = "1";
+
+        const problem = new LabelView("", { classList: ['problem', 'error'] });
+
+        const add = new EmptyView({ classList: ['toolbar-button'] });
+
+        add.addChild(new LabelView("add"));
+
+        add.el.addEventListener('click', () => {
+            problem.el.textContent = "";
+
+            const candidate = name.value.trim();
+
+            if (candidate === "") {
+                return;
+            }
+
+            try {
+                this.effect.addAttribute(candidate, Number.parseInt(components.value, 10));
+
+                name.value = "";
+            } catch (e) {
+                problem.el.textContent = e.message;
+            }
+        });
+
+        adder.addChild(new EmptyView({ el: name }));
+        adder.addChild(new EmptyView({ el: components }));
+        adder.addChild(add);
+        adder.addChild(problem);
+
+        return adder;
+    }
+
+    /**
+     * @param {{key: string, label: string, min: number, step: number, help: string}} field
+     * @returns {View}
+     */
+    #numericRow(field) {
+        const input = document.createElement('input');
+
+        input.setAttribute('type', 'number');
+        input.setAttribute('min', String(field.min));
+        input.setAttribute('step', String(field.step));
+
+        input.addEventListener('change', () => {
+            const parsed = Number.parseFloat(input.value);
+
+            if (!Number.isFinite(parsed) || parsed < field.min) {
+                input.value = String(this.effect.emitter[field.key]);
+                return;
+            }
+
+            this.effect.emitter[field.key] = parsed;
+            this.effect.touch();
+        });
+
+        this.#readers.push(() => {
+            if (document.activeElement !== input) {
+                input.value = String(this.effect.emitter[field.key]);
+            }
+        });
+
+        return row(field.label, input, field.help);
+    }
+
+    /**
+     * @param {string} label
+     * @param {string} key emitter field holding an array
+     * @param {number} components how many of its entries to show
+     * @returns {View}
+     */
+    #vectorRow(label, key, components) {
+        const container = new EmptyView({ classList: ['vector'] });
+
+        /** @type {HTMLInputElement[]} */
+        const fields = [];
+
+        for (let lane = 0; lane < components; lane++) {
+            const input = document.createElement('input');
+
+            input.setAttribute('type', 'number');
+            input.setAttribute('step', 'any');
+            input.classList.add('lane');
+
+            input.addEventListener('change', () => {
+                const parsed = Number.parseFloat(input.value);
+                const next = this.effect.emitter[key].slice();
+
+                next[lane] = Number.isFinite(parsed) ? parsed : 0;
+
+                this.effect.emitter[key] = next;
+                this.effect.touch();
+            });
+
+            fields.push(input);
+
+            container.el.appendChild(input);
+        }
+
+        this.#readers.push(() => {
+            const value = this.effect.emitter[key];
+
+            fields.forEach((input, lane) => {
+                if (document.activeElement !== input) {
+                    input.value = String(value[lane] ?? 0);
+                }
+            });
+        });
+
+        return row(label, container);
+    }
+
+    /**
+     * @param {string} label
+     * @param {string} key emitter field
+     * @param {Object<string, number>} options
+     * @returns {View}
+     */
+    #enumRow(label, key, options) {
+        const select = document.createElement('select');
+
+        for (const [name, value] of Object.entries(options)) {
+            const option = document.createElement('option');
+
+            option.value = String(value);
+            option.textContent = name.toLowerCase().replace(/_/g, " ");
+
+            select.appendChild(option);
+        }
+
+        select.addEventListener('change', () => {
+            this.effect.emitter[key] = Number.parseInt(select.value, 10);
+            this.effect.touch();
+        });
+
+        this.#readers.push(() => {
+            select.value = String(this.effect.emitter[key]);
+        });
+
+        return row(label, select);
+    }
+
+    /**
+     * @param {{key: string, label: string, help: string}} flag
+     * @returns {View}
+     */
+    #flagRow(flag) {
+        const input = document.createElement('input');
+
+        input.setAttribute('type', 'checkbox');
+
+        input.addEventListener('change', () => {
+            this.effect.emitter[flag.key] = input.checked;
+            this.effect.touch();
+        });
+
+        this.#readers.push(() => {
+            input.checked = this.effect.emitter[flag.key] === true;
+        });
+
+        return row(flag.label, input, flag.help);
+    }
+}
+
+/**
+ * @param {string} heading
+ * @returns {EmptyView}
+ */
+function section_view(heading) {
+    const section = new EmptyView({ classList: ['section'] });
+
+    section.addChild(new LabelView(heading, { classList: ['heading'] }));
+
+    return section;
+}
+
+/**
+ * @param {string} label
+ * @param {HTMLElement|View} control
+ * @param {string} [help] shown as the row's tooltip
+ * @returns {View}
+ */
+function row(label, control, help) {
+    const view = new EmptyView({ classList: ['field-row'] });
+
+    view.addChild(new LabelView(label, { classList: ['name'] }));
+
+    if (control instanceof View) {
+        view.addChild(control);
+    } else {
+        view.el.appendChild(control);
+    }
+
+    if (typeof help === "string") {
+        view.el.setAttribute('title', help);
+    }
+
+    return view;
+}
+
+/**
+ * @param {string} value
+ * @returns {HTMLInputElement}
+ */
+function text_input(value) {
+    const input = document.createElement('input');
+
+    input.setAttribute('type', 'text');
+    input.setAttribute('spellcheck', 'false');
+    input.value = value;
+
+    return input;
+}