@expofp/renderer 3.44.8 → 3.45.0

package/dist/objects/images/image-container.js

@@ -10,6 +10,12 @@ import { DIM_SCHEMA } from '../materials/effects/color-dim';
  * `uv * zw + xy` maps the quad's unit uv onto the region.
  */
 export const UV_OFFSET_UNIFORM = 'uvOffset';
+/**
+ * The per-instance uniform each atlas mesh reads its opacity from. The container owns the name and
+ * hands it to the mesh's `TextureMaterial` as the `opacityUniform` prop, so the material patches its shader
+ * without knowing the name itself.
+ */
+export const OPACITY_UNIFORM = 'instanceOpacity';
 /**
  * One atlas's mesh bookkeeping.
  *
@@ -51,6 +57,15 @@ export class ImageContainer extends SlotContainer {
     get facesCamera() {
         return isBatchedSprites(this.mesh);
     }
+    /**
+     * Writes a def's opacity into its slot, clamped, treating an absent value as fully opaque.
+     * @param slot - The instance's slot.
+     * @param opacity - The def's opacity, or `undefined` for the default.
+     */
+    setOpacityAt(slot, opacity) {
+        const value = opacity === undefined ? 1 : Math.min(Math.max(opacity, 0), 1);
+        this.mesh.setUniformAt(slot, OPACITY_UNIFORM, value);
+    }
     addInstance(packed) {
         // `addInstances` grows the buffers itself if the atlas ever overflows its sized capacity, so
         // there is nothing to pre-scan; the id is captured from the creation callback.
@@ -70,14 +85,15 @@ export class ImageContainer extends SlotContainer {
     }
 }
 /**
- * The schema the mesh declares (via `addUniforms`) so it can hold a {@link UV_OFFSET_UNIFORM} and a
- * dim per slot.
+ * The schema the mesh declares (via `addUniforms`) so it can hold a {@link UV_OFFSET_UNIFORM}, a
+ * {@link OPACITY_UNIFORM} and a dim per slot. The opacity float keeps the schema at two texels: a flat
+ * mesh is `vec4` + `float` + `float` = 6 floats, and a sprite mesh's own `anchor` brings it to 8.
  *
- * Both in one call although the two come from different places: `InstanceUniforms.add` merges and
+ * All in one call although they come from different places: `InstanceUniforms.add` merges and
  * rebuilds the backing texture, so declaring them separately would build it twice per bind.
  */
 const IMAGE_SCHEMA = {
-    vertex: { [UV_OFFSET_UNIFORM]: 'vec4', ...DIM_SCHEMA.vertex },
+    vertex: { [UV_OFFSET_UNIFORM]: 'vec4', [OPACITY_UNIFORM]: 'float', ...DIM_SCHEMA.vertex },
 };
 // Scratch for the one uv-region upload a claim performs, filled and read within a single synchronous
 // statement.

package/dist/objects/materials/TextureMaterial.d.ts

@@ -7,22 +7,25 @@ export interface TextureMaterialProps {
      */
     map: Texture;
     /**
-     * The name of a per-instance `vec4` uniform to source the texture region from — for a texture
-     * atlas on an instanced/batched mesh that declares and writes it. The mesh owns the name; the
-     * material only patches its shader to sample `map` through it. Omit it for a plain textured
-     * material: the shader is left unpatched, so the material draws its whole `map` and works in any
-     * context, not only an instanced one.
+     * The name of a per-instance `vec4` uniform to source the texture region from, for an atlas on an
+     * instanced/batched mesh that declares and writes it. The mesh owns the name; the material only
+     * patches its shader to sample `map` through it. Omit it to draw the whole `map` unpatched, in any
+     * context.
      */
     uvOffset?: string;
+    /**
+     * The name of a per-instance `float` uniform holding the instance's opacity, for a mesh that
+     * declares and writes one. Omit it to leave the fragment shader unpatched.
+     */
+    opacityUniform?: string;
 }
 /**
  * The material used to render a texture, optionally through a per-instance uv-offset uniform so an
  * instanced/batched mesh can pack many regions into one atlas.
  *
  * When {@link TextureMaterialProps.uvOffset} is set, the patch overwrites `vMapUv` after
- * `<uv_vertex>` has run, so the instance's atlas region replaces whatever the stock chunk computed.
- * Instanced meshes wrap this `onBeforeCompile` rather than replacing it, and inject their uniform
- * fetch at the top of `main()`, so the uniform is in scope by the time this line runs.
+ * `<uv_vertex>`, replacing the stock chunk's value. Instanced meshes wrap this `onBeforeCompile`
+ * and inject their uniform fetch at the top of `main()`, so the uniform is in scope here.
  * @param props - The material's texture and optional uv-offset uniform name.
  * @returns The material element.
  */

package/dist/objects/materials/TextureMaterial.js

@@ -8,34 +8,41 @@ import { overlayParams, sharedParams } from './shared';
  * instanced/batched mesh can pack many regions into one atlas.
  *
  * When {@link TextureMaterialProps.uvOffset} is set, the patch overwrites `vMapUv` after
- * `<uv_vertex>` has run, so the instance's atlas region replaces whatever the stock chunk computed.
- * Instanced meshes wrap this `onBeforeCompile` rather than replacing it, and inject their uniform
- * fetch at the top of `main()`, so the uniform is in scope by the time this line runs.
+ * `<uv_vertex>`, replacing the stock chunk's value. Instanced meshes wrap this `onBeforeCompile`
+ * and inject their uniform fetch at the top of `main()`, so the uniform is in scope here.
  * @param props - The material's texture and optional uv-offset uniform name.
  * @returns The material element.
  */
 export function TextureMaterial(props) {
-    const { map, uvOffset } = props;
+    const { map, uvOffset, opacityUniform } = props;
     const applyDim = useDimPatch();
     const overlay = useLayerOverlay();
     function onBeforeCompile(parameters) {
         applyDim(parameters);
-        if (!uvOffset)
-            return;
-        parameters.vertexShader = parameters.vertexShader.replace('#include <uv_vertex>', 
-        /*glsl*/ `
+        if (uvOffset) {
+            parameters.vertexShader = parameters.vertexShader.replace('#include <uv_vertex>', 
+            /*glsl*/ `
         #include <uv_vertex>
         vMapUv = uv * ${uvOffset}.zw + ${uvOffset}.xy;
       `.trim());
+        }
+        if (opacityUniform) {
+            // All four channels: the blend is premultiplied, so rgb already carries the texel's alpha and
+            // must carry the opacity too. Scaling `a` alone leaves a bright halo instead of a faded pin.
+            //
+            // After `colorspace_fragment`, so rgb is already sRGB-encoded and blends with the same weight
+            // as alpha. Before the encode, `0.5` would read about 73% opaque. Dim patches an earlier chunk
+            // (`tonemapping_fragment`), so the two never share an anchor.
+            parameters.fragmentShader = parameters.fragmentShader.replace('#include <colorspace_fragment>', 
+            /*glsl*/ `
+        #include <colorspace_fragment>
+        gl_FragColor *= ${opacityUniform};
+      `.trim());
+        }
     }
-    // An atlas texture is premultiplied (see `makeAtlasTexture`'s `premultiplyAlpha` comment), so
-    // this material needs the premultiplied blend, not `sharedParams`'s straight-alpha one.
-    // `blendSrc: OneFactor` is the only change: the source term becomes `1 * (c * a)`, which already
-    // equals the straight blend's own `c * a` source term, so the composited color comes out the
-    // same either way. `blendDst` stays `OneMinusSrcAlphaFactor` from `sharedParams`, since that half
-    // does not depend on how the source is stored.
-    //
-    // The override lives here, not in `sharedParams`, because `ColorMaterial` and `LineMaterial`
-    // share that object and their colors are never premultiplied.
+    // An atlas texture is premultiplied (see `makeAtlasTexture`), so this needs `blendSrc: OneFactor`
+    // rather than `sharedParams`'s straight-alpha source term; `blendDst` is unaffected. The override
+    // lives here because `ColorMaterial` and `LineMaterial` share `sharedParams` and are never
+    // premultiplied.
     return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/text/text-container.d.ts

@@ -48,6 +48,20 @@ export declare class TextContainer extends SlotContainer<number, BatchedTextImpl
      *   the lifetime of a canvas, so capturing it here is safe.
      */
     constructor(invalidate: () => void);
+    /**
+     * Binds the batch, and asks for a frame each time it finishes a sync.
+     *
+     * {@link scheduleSync}'s callback closes the loop only for a sync it starts. A write made inside a
+     * frame callback — a layout rule's, or a placement report's drained before the render — flags the
+     * batch before that frame renders, so the batch's own render hook starts the sync, with no
+     * callback, and the coalesced one that follows finds nothing left to do. Its glyphs then land
+     * after the last frame anyone asked for, and the old text stays on screen until something else
+     * happens to draw. A repack that runs inside the render hook is a frame late for the same reason:
+     * three has uploaded the batch's attributes by then. The batch's own completion is the one signal
+     * both paths share.
+     * @param mesh - The mounted batch, or the ref-cleanup `null`.
+     */
+    bind(mesh: BatchedTextImpl | null): void;
     /**
      * The members backing one def.
      * @param slot - The def's group.
@@ -61,7 +75,8 @@ export declare class TextContainer extends SlotContainer<number, BatchedTextImpl
      * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
      * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
      * what closes that loop; without it new text appears only when something else happens to
-     * invalidate.
+     * invalidate. A sync this did not start is covered by the batch's own completion, which
+     * {@link bind} listens for.
      */
     scheduleSync(): void;
     claim(def: RenderableDef, lineCount: number): number;

package/dist/objects/text/text-container.js

@@ -45,6 +45,27 @@ export class TextContainer extends SlotContainer {
         super();
         this.invalidate = invalidate;
     }
+    /**
+     * Binds the batch, and asks for a frame each time it finishes a sync.
+     *
+     * {@link scheduleSync}'s callback closes the loop only for a sync it starts. A write made inside a
+     * frame callback — a layout rule's, or a placement report's drained before the render — flags the
+     * batch before that frame renders, so the batch's own render hook starts the sync, with no
+     * callback, and the coalesced one that follows finds nothing left to do. Its glyphs then land
+     * after the last frame anyone asked for, and the old text stays on screen until something else
+     * happens to draw. A repack that runs inside the render hook is a frame late for the same reason:
+     * three has uploaded the batch's attributes by then. The batch's own completion is the one signal
+     * both paths share.
+     * @param mesh - The mounted batch, or the ref-cleanup `null`.
+     */
+    bind(mesh) {
+        // `mesh` reads the bound batch, which is undefined until the first bind; the base ignores a
+        // re-bind, so the listener is added once too.
+        const first = mesh !== null && this.mesh === undefined;
+        super.bind(mesh);
+        if (first)
+            mesh.addEventListener('synccomplete', () => this.invalidate());
+    }
     /**
      * The members backing one def.
      * @param slot - The def's group.
@@ -60,7 +81,8 @@ export class TextContainer extends SlotContainer {
      * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
      * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
      * what closes that loop; without it new text appears only when something else happens to
-     * invalidate.
+     * invalidate. A sync this did not start is covered by the batch's own completion, which
+     * {@link bind} listens for.
      */
     scheduleSync() {
         if (this.syncScheduled)

package/dist/space/layout-measure.d.ts

@@ -2,7 +2,7 @@ import { type Camera } from 'three';
 import { type CameraControlsImpl } from '../controls';
 import { type Space } from './Space';
 /**
- * How much of the plan one device pixel spans, in plan units — what everything sized in pixels is
+ * How much of the plan one CSS pixel spans, in plan units — what everything sized in pixels is
  * authored against, and what the imperative renderer published as `ptScale`.
  *
  * **One number for a view that has many.** Perspective foreshortens a pitched plan, so no single
@@ -21,16 +21,18 @@ import { type Space } from './Space';
  * Neither path knows a `visibleRect` exists: its framing rides in `projectionMatrix`, which one
  * reads `m00` out of and the other projects through.
  *
- * **Device pixels, not css pixels** — a plan at dpr 2 reports half the pixel size of the same plan
- * at dpr 1, as the imperative renderer did measuring `canvas.height`.
+ * **CSS pixels, not device pixels** — a plan reports the same pixel size at every device ratio. The
+ * renderer's public surface is CSS pixels, because a caller authors in CSS pixels and the ratio of
+ * the drawing buffer is the renderer's own business; the caller hands over the canvas's width in
+ * CSS pixels and the ratio never enters here.
  * @param camera - The camera in use.
  * @param space - The scene's space.
- * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param cssWidth - The canvas's width in CSS pixels.
  * @param controls - The camera controls, when mounted; they own the distance to the target.
- * @returns Plan units per device pixel, or `undefined` while the camera misses the plan or the
- *   buffer has no width.
+ * @returns Plan units per CSS pixel, or `undefined` while the camera misses the plan or the canvas
+ *   has no width.
  */
-export declare function measurePixelSize(camera: Camera, space: Space, bufferWidth: number, controls?: CameraControlsImpl): number | undefined;
+export declare function measurePixelSize(camera: Camera, space: Space, cssWidth: number, controls?: CameraControlsImpl): number | undefined;
 /**
  * Which way the plan is turned, in radians clockwise from north — {@link measurePixelSize}'s
  * counterpart on the roll axis, split the same way.
@@ -46,12 +48,12 @@ export declare function measurePixelSize(camera: Camera, space: Space, bufferWid
  * imperative renderer used, and with it the question of how far apart to place it.
  * @param camera - The camera in use.
  * @param space - The scene's space.
- * @param bufferWidth - The drawing buffer's width in device pixels.
- * @param bufferHeight - Its height, which weights the two NDC axes back into pixels.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param cssHeight - Its height in CSS pixels, which weights the two NDC axes back into pixels.
  * @param controls - The camera controls, when mounted; they hold the angle outright.
  * @returns The roll in `[0, 2π)`, or `undefined` while the camera misses the plan.
  */
-export declare function measureRoll(camera: Camera, space: Space, bufferWidth: number, bufferHeight: number, controls?: CameraControlsImpl): number | undefined;
+export declare function measureRoll(camera: Camera, space: Space, cssWidth: number, cssHeight: number, controls?: CameraControlsImpl): number | undefined;
 /**
  * Whether a new pixel size differs enough from the last one to re-lay out on.
  *

package/dist/space/layout-measure.js

@@ -4,7 +4,7 @@ import { bearing } from '../controls';
 import { euclideanModulo } from '../utils/math';
 import { isOrthographic, isPerspective } from './camera-kind';
 /**
- * How much of the plan one device pixel spans, in plan units — what everything sized in pixels is
+ * How much of the plan one CSS pixel spans, in plan units — what everything sized in pixels is
  * authored against, and what the imperative renderer published as `ptScale`.
  *
  * **One number for a view that has many.** Perspective foreshortens a pitched plan, so no single
@@ -23,24 +23,26 @@ import { isOrthographic, isPerspective } from './camera-kind';
  * Neither path knows a `visibleRect` exists: its framing rides in `projectionMatrix`, which one
  * reads `m00` out of and the other projects through.
  *
- * **Device pixels, not css pixels** — a plan at dpr 2 reports half the pixel size of the same plan
- * at dpr 1, as the imperative renderer did measuring `canvas.height`.
+ * **CSS pixels, not device pixels** — a plan reports the same pixel size at every device ratio. The
+ * renderer's public surface is CSS pixels, because a caller authors in CSS pixels and the ratio of
+ * the drawing buffer is the renderer's own business; the caller hands over the canvas's width in
+ * CSS pixels and the ratio never enters here.
  * @param camera - The camera in use.
  * @param space - The scene's space.
- * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param cssWidth - The canvas's width in CSS pixels.
  * @param controls - The camera controls, when mounted; they own the distance to the target.
- * @returns Plan units per device pixel, or `undefined` while the camera misses the plan or the
- *   buffer has no width.
+ * @returns Plan units per CSS pixel, or `undefined` while the camera misses the plan or the canvas
+ *   has no width.
  */
-export function measurePixelSize(camera, space, bufferWidth, controls) {
-    if (!(bufferWidth > 0) || !(space.scale > 0))
+export function measurePixelSize(camera, space, cssWidth, controls) {
+    if (!(cssWidth > 0) || !(space.scale > 0))
         return undefined;
     if (controls) {
         const worldWidth = visibleWorldWidth(camera, controls.distance);
         if (!(worldWidth > 0))
             return undefined;
         // The camera measures the world, and only the fit says how much plan that world is.
-        return worldWidth / bufferWidth / space.scale;
+        return worldWidth / cssWidth / space.scale;
     }
     const aim = aimedAt(camera, space);
     if (!aim)
@@ -56,7 +58,7 @@ export function measurePixelSize(camera, space, bufferWidth, controls) {
     const planLength = Math.hypot(right.x - left.x, right.y - left.y);
     if (!(planLength > 0))
         return undefined;
-    return planLength / bufferWidth;
+    return planLength / cssWidth;
 }
 /**
  * Which way the plan is turned, in radians clockwise from north — {@link measurePixelSize}'s
@@ -73,12 +75,12 @@ export function measurePixelSize(camera, space, bufferWidth, controls) {
  * imperative renderer used, and with it the question of how far apart to place it.
  * @param camera - The camera in use.
  * @param space - The scene's space.
- * @param bufferWidth - The drawing buffer's width in device pixels.
- * @param bufferHeight - Its height, which weights the two NDC axes back into pixels.
+ * @param cssWidth - The canvas's width in CSS pixels.
+ * @param cssHeight - Its height in CSS pixels, which weights the two NDC axes back into pixels.
  * @param controls - The camera controls, when mounted; they hold the angle outright.
  * @returns The roll in `[0, 2π)`, or `undefined` while the camera misses the plan.
  */
-export function measureRoll(camera, space, bufferWidth, bufferHeight, controls) {
+export function measureRoll(camera, space, cssWidth, cssHeight, controls) {
     if (controls)
         return bearing(controls);
     const aim = aimedAt(camera, space);
@@ -93,8 +95,8 @@ export function measureRoll(camera, space, bufferWidth, bufferHeight, controls)
     // d(ndc)/dx by the quotient rule, less its `1/w²` — positive, so it moves no direction. NDC is
     // aspect-distorted, so each axis is weighted back into pixels; canvas y grows downward where NDC
     // y grows up.
-    const dx = (column[0] * clip.w - clip.x * column[3]) * bufferWidth;
-    const dy = -(column[1] * clip.w - clip.y * column[3]) * bufferHeight;
+    const dx = (column[0] * clip.w - clip.x * column[3]) * cssWidth;
+    const dy = -(column[1] * clip.w - clip.y * column[3]) * cssHeight;
     if (dx === 0 && dy === 0)
         return undefined;
     // The plan turned clockwise by θ shows its east axis at screen angle -θ.
@@ -137,7 +139,7 @@ function aimedAt(camera, space) {
  * installs, which leaves `fov` untouched.
  *
  * Width where the imperative renderer took height, so both of {@link measurePixelSize}'s paths
- * divide by the one buffer dimension they are given; for a projection whose aspect is the buffer's
+ * divide by the one canvas dimension they are given; for a projection whose aspect is the buffer's
  * the two agree exactly.
  * @param camera - The camera in use.
  * @param distance - Distance from the camera to the point it is aimed at, in world units.