@expofp/renderer 3.2.5 → 3.27.1

package/dist/controls/zoom-to.d.ts

@@ -0,0 +1,89 @@
+import { Box, type Point2Like } from '@expofp/geometry';
+import { type PerspectiveCamera } from 'three';
+import { type Space } from '../space/Space';
+/**
+ * The part of the canvas a target is framed inside, in **device** pixels, as the camera's own
+ * framing measures it.
+ *
+ * The offset is from the drawing buffer's centre rather than from its corner, because that is the
+ * only thing the fit does with it — a region centred on the canvas frames exactly as no region at
+ * all, and says so by being all zeroes.
+ */
+export interface FramingRegion {
+    /** How wide the region is. */
+    width: number;
+    /** How tall it is. */
+    height: number;
+    /** How far its centre sits to the right of the buffer's centre; negative for left. */
+    offsetX: number;
+    /** How far below; negative for above. */
+    offsetY: number;
+}
+/**
+ * What a camera's projection was offset by — three's own `camera.view`, which `VisibleRect` is what
+ * writes. Aliased rather than restated so the two can never drift.
+ */
+export type ViewOffset = PerspectiveCamera['view'];
+/** How {@link fitBox} should frame its target. */
+export interface FitOptions {
+    /** The target, in plan units. */
+    target: Box;
+    /** The scene's space, which takes the target into world units. */
+    space: Space;
+    /** How far the plan is turned, in radians — the camera's azimuth, negated. */
+    bearing: number;
+    /** The region to frame the target inside. */
+    region: FramingRegion;
+    /** Fraction of the region left as margin on each side; `0.25` spends half of it. */
+    padding?: number;
+    /** The closest the fit may bring the plan, as a zoom factor. */
+    maxZoom?: number;
+}
+/** Where the camera has to be for a target to fill its region. */
+export interface Fit {
+    /** Where the camera should look, in world units. */
+    center: Point2Like;
+    /** The zoom factor that frames the target. */
+    zoom: number;
+}
+/**
+ * Where the camera has to be for a box of the plan to fill a region of the canvas.
+ *
+ * Pure arithmetic, kept out of the hook so the part that can be wrong is the part that can be
+ * tested. It rests on the one invariant the viewbox fit exists to establish — at zoom factor `1` one
+ * world unit is one device pixel — which is what lets a world size and a pixel size be divided by
+ * each other below.
+ *
+ * The target is measured **in the camera's own frame**: its world box is turned about its centre by
+ * the bearing before its bounds are taken, so a plan the user has rolled frames the box they can see
+ * rather than its axis-aligned shadow. Turning about the centre is what leaves the centre alone,
+ * which is why only the size of that box is read.
+ *
+ * The pan target then picks up the region's offset from the buffer's centre, which is what lands the
+ * box in the middle of *that region* rather than in the middle of the canvas. The offset is divided
+ * by the zoom because it arrives as a distance in pixels and has to leave as one in world units, and
+ * turned by the bearing for the same reason the box was.
+ * @param options - The target, and how to frame it.
+ * @returns The framing, or `undefined` for a target with no area, which nothing can be fitted to.
+ */
+export declare function fitBox(options: FitOptions): Fit | undefined;
+/**
+ * The region a caller named, in the coordinates the fit works in.
+ *
+ * A `within` rect is given in css pixels of the **canvas**, which is where a host's own panels are.
+ * The fit works in the camera's framing instead — the canvas as it would be with no visible rect —
+ * so a rect has to come back through whatever `VisibleRect` put on the projection: a uniform scale
+ * about the rect's centre, and nothing else. With no view offset that reduces to a change of origin
+ * and a multiplication by the device pixel ratio.
+ *
+ * This is the one place in the renderer where a region of the canvas and the camera's framing meet,
+ * and it is the method whose whole job is relating the two. Everything else stays clear of it.
+ * @param within - The region, in css pixels from the canvas's top-left corner; omitted means all of it.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @param view - The camera's view offset, when one is in force.
+ * @returns The region in device pixels, offset from the buffer's centre.
+ */
+export declare function framingRegion(within: Box | undefined, width: number, height: number, dpr: number, view?: ViewOffset | null): FramingRegion;
+//# sourceMappingURL=zoom-to.d.ts.map

package/dist/controls/zoom-to.js

@@ -0,0 +1,91 @@
+import { Box, Point, rectBounds } from '@expofp/geometry';
+/**
+ * Where the camera has to be for a box of the plan to fill a region of the canvas.
+ *
+ * Pure arithmetic, kept out of the hook so the part that can be wrong is the part that can be
+ * tested. It rests on the one invariant the viewbox fit exists to establish — at zoom factor `1` one
+ * world unit is one device pixel — which is what lets a world size and a pixel size be divided by
+ * each other below.
+ *
+ * The target is measured **in the camera's own frame**: its world box is turned about its centre by
+ * the bearing before its bounds are taken, so a plan the user has rolled frames the box they can see
+ * rather than its axis-aligned shadow. Turning about the centre is what leaves the centre alone,
+ * which is why only the size of that box is read.
+ *
+ * The pan target then picks up the region's offset from the buffer's centre, which is what lands the
+ * box in the middle of *that region* rather than in the middle of the canvas. The offset is divided
+ * by the zoom because it arrives as a distance in pixels and has to leave as one in world units, and
+ * turned by the bearing for the same reason the box was.
+ * @param options - The target, and how to frame it.
+ * @returns The framing, or `undefined` for a target with no area, which nothing can be fitted to.
+ */
+export function fitBox(options) {
+    const { target, space, bearing, region, padding = 0, maxZoom } = options;
+    // The bounds of the target once the plan is turned — geometry's own rect maths, given the world
+    // box as a rect with a rotation. Turning is about the centre, so the centre below is still the
+    // target's and only the extent has changed.
+    const world = worldBounds(target, space);
+    const source = rectBounds({ center: world.center, size: world.size, rotation: bearing });
+    const { width: sourceWidth, height: sourceHeight } = source.size;
+    if (sourceWidth <= 0 || sourceHeight <= 0)
+        return undefined;
+    if (region.width <= 0 || region.height <= 0)
+        return undefined;
+    const margin = 1 - 2 * padding;
+    const fitted = Math.min((region.width * margin) / sourceWidth, (region.height * margin) / sourceHeight);
+    const zoom = maxZoom === undefined ? fitted : Math.min(fitted, maxZoom);
+    if (!(zoom > 0))
+        return undefined;
+    const pan = new Point(-region.offsetX / zoom, -region.offsetY / zoom).rotate(bearing, ORIGIN);
+    return { center: { x: source.center.x + pan.x, y: source.center.y + pan.y }, zoom };
+}
+/**
+ * The region a caller named, in the coordinates the fit works in.
+ *
+ * A `within` rect is given in css pixels of the **canvas**, which is where a host's own panels are.
+ * The fit works in the camera's framing instead — the canvas as it would be with no visible rect —
+ * so a rect has to come back through whatever `VisibleRect` put on the projection: a uniform scale
+ * about the rect's centre, and nothing else. With no view offset that reduces to a change of origin
+ * and a multiplication by the device pixel ratio.
+ *
+ * This is the one place in the renderer where a region of the canvas and the camera's framing meet,
+ * and it is the method whose whole job is relating the two. Everything else stays clear of it.
+ * @param within - The region, in css pixels from the canvas's top-left corner; omitted means all of it.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @param view - The camera's view offset, when one is in force.
+ * @returns The region in device pixels, offset from the buffer's centre.
+ */
+export function framingRegion(within, width, height, dpr, view) {
+    if (!within) {
+        return { width: width * dpr, height: height * dpr, offsetX: 0, offsetY: 0 };
+    }
+    // What the framing was scaled by, and where its centre landed — read straight back off the
+    // parameters `VisibleRect` handed `setViewOffset`.
+    const scale = view?.enabled ? view.fullWidth / view.width : 1;
+    const landingX = view?.enabled ? view.fullWidth / 2 - view.offsetX : width / 2;
+    const landingY = view?.enabled ? view.fullHeight / 2 - view.offsetY : height / 2;
+    return {
+        width: (within.size.width / scale) * dpr,
+        height: (within.size.height / scale) * dpr,
+        offsetX: ((within.center.x - landingX) / scale) * dpr,
+        offsetY: ((within.center.y - landingY) / scale) * dpr,
+    };
+}
+/**
+ * The target's bounds in world space.
+ *
+ * Two corners are the whole box: the plan-to-world mapping scales and translates, so opposite
+ * corners stay opposite. `fromMinMax` normalizes them, so a transform that mirrors an axis and
+ * hands them over the other way round still comes out right.
+ * @param target - The target, in plan units.
+ * @param space - The scene's space.
+ * @returns The bounds, in world units.
+ */
+function worldBounds(target, space) {
+    const min = space.planToWorld({ ...target.min, z: 0 });
+    const max = space.planToWorld({ ...target.max, z: 0 });
+    return Box.fromMinMax(min, max);
+}
+const ORIGIN = { x: 0, y: 0 };

package/dist/core/InstanceUniforms.d.ts

@@ -0,0 +1,93 @@
+import { type WebGLProgramParametersWithUniforms } from 'three';
+import { SquareDataTexture, type UniformType, type UniformValue, type UniformValueObj } from './SquareDataTexture';
+/** The GLSL types a per-instance uniform may take, keyed by the name it gets in the shader. */
+export type UniformSchema = Record<string, UniformType>;
+/** Per-instance uniforms to declare, split by the shader stage that reads them. */
+export interface UniformSchemaShader {
+    /** Uniforms read in the vertex shader. */
+    vertex?: UniformSchema;
+    /** Uniforms read in the fragment shader. */
+    fragment?: UniformSchema;
+}
+/**
+ * The per-instance uniform store shared by all core classes: a {@link SquareDataTexture} plus the schema
+ * describing how uniforms pack into it.
+ *
+ * Ported from the identical uniform code both three.ez packages carry (`Uniforms.ts` in each), with
+ * one change: uniforms are **added**, not declared once. {@link add} merges into whatever is already
+ * there and rebuilds the texture, carrying existing values across — so a material and its container
+ * can each declare what they need without coordinating, and a declaration after instances are
+ * written keeps them. Removal is deliberately unsupported; rebuild the mesh if it is ever needed.
+ *
+ * The shader wiring lives here as well ({@link patchShader}), because every mesh does the same two
+ * things with it: bind the texture, and open `main` with the prologue that fetches from it. What
+ * differs between them — where the per-instance index comes from, and what each adds around the
+ * prologue — is what they pass in.
+ */
+export declare class InstanceUniforms {
+    /** The backing texture, or `null` until {@link add} declares the first uniform. */
+    texture: SquareDataTexture | null;
+    /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
+    private declared;
+    /**
+     * Declares uniforms, merging with any already declared and rebuilding the texture.
+     *
+     * The layout packs every uniform into as few texels as it can, so adding one generally moves the
+     * others — hence the rebuild-and-copy rather than an in-place append. Redeclaring a name with a
+     * different type replaces it.
+     * @param schema - The uniforms to add.
+     * @param capacity - Instances the texture must hold.
+     */
+    add(schema: UniformSchemaShader, capacity: number): void;
+    /**
+     * Reads one instance's uniform.
+     * @param id - The instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    get(id: number, name: string, target?: UniformValueObj): UniformValue;
+    /**
+     * Writes one instance's uniform and marks its row for upload.
+     * @param id - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    set(id: number, name: string, value: UniformValue): void;
+    /**
+     * Grows the texture to a new instance capacity, keeping what is written.
+     * @param capacity - The new capacity.
+     */
+    resize(capacity: number): void;
+    /**
+     * Points a compiling shader at these uniforms: binds the texture, and opens `main` in both stages
+     * with the prologue that fetches this instance's values and brings them into scope under the
+     * names they were declared with.
+     *
+     * Does nothing and answers `false` while no uniform is declared — there is no texture to bind and
+     * nothing to name, so a caller whose own GLSL reads those names has to skip it too.
+     * @param shader - The program parameters to edit.
+     * @param indexName - The per-instance index the fetch addresses by, in shader scope where the
+     *   prologue lands (a float; see {@link SquareDataTexture}). A caller computing it inside `main`
+     *   supplies it with a later {@link openMain}, which lands ahead of this fetch.
+     * @param body - GLSL to run straight after the fetch, in both stages. Where code reading the
+     *   uniforms goes, since nothing ahead of the prologue can see them.
+     * @returns Whether the shader was patched.
+     * @throws {Error} If either stage has no `main` to inject into.
+     */
+    patchShader(shader: WebGLProgramParametersWithUniforms, indexName: string, body?: string): boolean;
+    /**
+     * Adopts another store's schema and an independent copy of its values, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source: InstanceUniforms): void;
+    /** Frees the texture. */
+    dispose(): void;
+    /**
+     * The texture, or a readable failure when nothing declared a uniform.
+     * @returns The texture.
+     * @throws {Error} If {@link add} has not been called.
+     */
+    private require;
+}
+//# sourceMappingURL=InstanceUniforms.d.ts.map

package/dist/core/InstanceUniforms.js

@@ -0,0 +1,266 @@
+import { Matrix3, Matrix4, Vector2, Vector3, Vector4, } from 'three';
+import { declareBeforeMain, openMain } from './shader-source';
+import { SquareDataTexture, } from './SquareDataTexture';
+/**
+ * The per-instance uniform store shared by all core classes: a {@link SquareDataTexture} plus the schema
+ * describing how uniforms pack into it.
+ *
+ * Ported from the identical uniform code both three.ez packages carry (`Uniforms.ts` in each), with
+ * one change: uniforms are **added**, not declared once. {@link add} merges into whatever is already
+ * there and rebuilds the texture, carrying existing values across — so a material and its container
+ * can each declare what they need without coordinating, and a declaration after instances are
+ * written keeps them. Removal is deliberately unsupported; rebuild the mesh if it is ever needed.
+ *
+ * The shader wiring lives here as well ({@link patchShader}), because every mesh does the same two
+ * things with it: bind the texture, and open `main` with the prologue that fetches from it. What
+ * differs between them — where the per-instance index comes from, and what each adds around the
+ * prologue — is what they pass in.
+ */
+export class InstanceUniforms {
+    /** The backing texture, or `null` until {@link add} declares the first uniform. */
+    texture = null;
+    /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
+    declared = {};
+    /**
+     * Declares uniforms, merging with any already declared and rebuilding the texture.
+     *
+     * The layout packs every uniform into as few texels as it can, so adding one generally moves the
+     * others — hence the rebuild-and-copy rather than an in-place append. Redeclaring a name with a
+     * different type replaces it.
+     * @param schema - The uniforms to add.
+     * @param capacity - Instances the texture must hold.
+     */
+    add(schema, capacity) {
+        const vertex = { ...this.declared.vertex, ...schema.vertex };
+        const fragment = { ...this.declared.fragment, ...schema.fragment };
+        const layout = buildUniformLayout({ vertex, fragment });
+        const texture = new SquareDataTexture(Float32Array, layout.channels, layout.pixelsPerInstance, capacity, layout.uniformMap, layout.fetchInFragmentShader);
+        const previous = this.texture;
+        if (previous) {
+            copyUniforms(previous, texture, declaredTypes(this.declared), capacity);
+            previous.dispose();
+        }
+        this.texture = texture;
+        this.declared = { vertex, fragment };
+    }
+    /**
+     * Reads one instance's uniform.
+     * @param id - The instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    get(id, name, target) {
+        return this.require().getUniformAt(id, name, target);
+    }
+    /**
+     * Writes one instance's uniform and marks its row for upload.
+     * @param id - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    set(id, name, value) {
+        const texture = this.require();
+        texture.setUniformAt(id, name, value);
+        texture.enqueueUpdate(id);
+    }
+    /**
+     * Grows the texture to a new instance capacity, keeping what is written.
+     * @param capacity - The new capacity.
+     */
+    resize(capacity) {
+        this.texture?.resize(capacity);
+    }
+    /**
+     * Points a compiling shader at these uniforms: binds the texture, and opens `main` in both stages
+     * with the prologue that fetches this instance's values and brings them into scope under the
+     * names they were declared with.
+     *
+     * Does nothing and answers `false` while no uniform is declared — there is no texture to bind and
+     * nothing to name, so a caller whose own GLSL reads those names has to skip it too.
+     * @param shader - The program parameters to edit.
+     * @param indexName - The per-instance index the fetch addresses by, in shader scope where the
+     *   prologue lands (a float; see {@link SquareDataTexture}). A caller computing it inside `main`
+     *   supplies it with a later {@link openMain}, which lands ahead of this fetch.
+     * @param body - GLSL to run straight after the fetch, in both stages. Where code reading the
+     *   uniforms goes, since nothing ahead of the prologue can see them.
+     * @returns Whether the shader was patched.
+     * @throws {Error} If either stage has no `main` to inject into.
+     */
+    patchShader(shader, indexName, body = '') {
+        const texture = this.texture;
+        if (!texture)
+            return false;
+        const glsl = texture.getUniformsGLSL(UNIFORMS_TEXTURE, indexName);
+        shader.uniforms[UNIFORMS_TEXTURE] = { value: texture };
+        shader.vertexShader = openMain(declareBeforeMain(shader.vertexShader, glsl.vertex.declarations), `${glsl.vertex.body}\n${body}`);
+        shader.fragmentShader = openMain(declareBeforeMain(shader.fragmentShader, glsl.fragment.declarations), `${glsl.fragment.body}\n${body}`);
+        return true;
+    }
+    /**
+     * Adopts another store's schema and an independent copy of its values, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source) {
+        this.declared = {
+            vertex: { ...source.declared.vertex },
+            fragment: { ...source.declared.fragment },
+        };
+        this.texture = source.texture ? source.texture.clone() : null;
+    }
+    /** Frees the texture. */
+    dispose() {
+        this.texture?.dispose();
+    }
+    /**
+     * The texture, or a readable failure when nothing declared a uniform.
+     * @returns The texture.
+     * @throws {Error} If {@link add} has not been called.
+     */
+    require() {
+        if (!this.texture) {
+            throw new Error('InstanceUniforms: declare uniforms with "addUniforms" before reading or writing them.');
+        }
+        return this.texture;
+    }
+}
+/**
+ * Packs a schema into texels, largest uniform first so small ones fill the gaps.
+ * @param schema - Every uniform to lay out.
+ * @returns The layout.
+ */
+function buildUniformLayout(schema) {
+    const vertexSchema = schema.vertex ?? {};
+    const fragmentSchema = schema.fragment ?? {};
+    const uniforms = [];
+    let totalSize = 0;
+    // Only when nothing is read in the vertex shader can the fetch move to the fragment shader.
+    let fetchInFragmentShader = true;
+    for (const name in vertexSchema) {
+        const type = vertexSchema[name];
+        const size = uniformSize(type);
+        totalSize += size;
+        uniforms.push({ name, type, size });
+        fetchInFragmentShader = false;
+    }
+    for (const name in fragmentSchema) {
+        if (vertexSchema[name])
+            continue;
+        const type = fragmentSchema[name];
+        const size = uniformSize(type);
+        totalSize += size;
+        uniforms.push({ name, type, size });
+    }
+    uniforms.sort((a, b) => b.size - a.size);
+    const uniformMap = new Map();
+    const filled = [];
+    for (const { name, size, type } of uniforms) {
+        uniformMap.set(name, { offset: uniformOffset(size, filled), size, type });
+    }
+    return {
+        channels: Math.min(totalSize, 4),
+        pixelsPerInstance: Math.ceil(totalSize / 4),
+        uniformMap,
+        fetchInFragmentShader,
+    };
+}
+/**
+ * Places one uniform, reusing a partly filled texel when it fits.
+ * @param size - Elements the uniform spans.
+ * @param filled - Elements used so far in each texel; extended as texels are opened.
+ * @returns The uniform's element offset within an instance's record.
+ */
+function uniformOffset(size, filled) {
+    if (size < 4) {
+        for (let i = 0; i < filled.length; i++) {
+            if (filled[i] + size <= 4) {
+                const offset = i * 4 + filled[i];
+                filled[i] += size;
+                return offset;
+            }
+        }
+    }
+    const offset = filled.length * 4;
+    for (let remaining = size; remaining > 0; remaining -= 4) {
+        filled.push(remaining);
+    }
+    return offset;
+}
+/**
+ * Elements a uniform type occupies.
+ * @param type - The GLSL type.
+ * @returns Its element count.
+ * @throws {Error} If the type is not one this texture can store.
+ */
+function uniformSize(type) {
+    switch (type) {
+        case 'float':
+            return 1;
+        case 'vec2':
+            return 2;
+        case 'vec3':
+            return 3;
+        case 'vec4':
+            return 4;
+        case 'mat3':
+            return 9;
+        case 'mat4':
+            return 16;
+        default:
+            throw new Error(`InstanceUniforms: invalid uniform type "${String(type)}".`);
+    }
+}
+/**
+ * Flattens a schema into the name-to-type pairs a rebuild has to carry across.
+ * @param schema - The declared uniforms.
+ * @returns Every uniform, whichever stage reads it.
+ */
+function declaredTypes(schema) {
+    return { ...schema.vertex, ...schema.fragment };
+}
+/**
+ * Carries per-instance values from one layout to the next, so declaring a uniform does not discard
+ * what is already written. Goes through the public accessors, which is what makes it indifferent to
+ * the offsets moving underneath.
+ * @param previous - The texture being replaced.
+ * @param next - The texture replacing it.
+ * @param types - The uniforms to carry, by name.
+ * @param count - Instances to copy.
+ */
+function copyUniforms(previous, next, types, count) {
+    for (const name in types) {
+        // Allocated once per uniform, not per instance, so a rebuild costs a handful of objects however
+        // many instances it carries across.
+        const target = uniformScratch(types[name]);
+        for (let id = 0; id < count; id++) {
+            next.setUniformAt(id, name, previous.getUniformAt(id, name, target));
+        }
+    }
+}
+/**
+ * A target for reading a uniform of the given type.
+ * @param type - The GLSL type.
+ * @returns The scratch object, or `undefined` for a `float`, which is read by value.
+ */
+function uniformScratch(type) {
+    switch (type) {
+        case 'vec2':
+            return new Vector2();
+        case 'vec3':
+            return new Vector3();
+        case 'vec4':
+            return new Vector4();
+        case 'mat3':
+            return new Matrix3();
+        case 'mat4':
+            return new Matrix4();
+        default:
+            return undefined;
+    }
+}
+/**
+ * The sampler name the uniforms texture binds to. Private because both sides of the agreement it
+ * enforces — the generated GLSL and the `shader.uniforms[…]` entry — are set by
+ * {@link InstanceUniforms.patchShader}.
+ */
+const UNIFORMS_TEXTURE = 'uniformsTexture';