@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/Renderer.js

@@ -1,4 +1,5 @@
 import { assert } from "../../core/assert.js";
+import { frame_jitter_applies } from "./frame_jitter_applies.js";
 import Signal from "../../core/events/signal/Signal.js";
 import Vector2 from "../../core/geom/Vector2.js";
 import { clamp } from "../../core/math/clamp.js";
@@ -84,9 +85,11 @@ import { View } from "./view/View.js";
 import { ViewManager } from "./view/ViewManager.js";
 
 /**
+ * @typedef {import("../device/timing/profile/GPUFrameRecorder.js").GPUFrameRecorder} GPUFrameRecorder
  * @typedef {import("../device/timing/profile/GPUProfileSession.js").GPUProfileSession} GPUProfileSession
  * @typedef {import("./camera/PerspectiveCamera.js").PerspectiveCamera} PerspectiveCamera
  * @typedef {import("./extension/RenderExtension.js").RenderExtension} RenderExtension
+ * @typedef {import("./rasterize/native/avboit/AVBOITSideChannel.js").AVBOITSideChannel} AVBOITSideChannel
  * @typedef {import("./scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
  * @typedef {import("./scene/Scene.js").Scene} Scene
  */
@@ -470,6 +473,17 @@ export class Renderer {
      */
     onDeviceFailure = new Signal();
 
+    /**
+     * Sent at the end of every frame {@link render} or {@link render_to_target} completes, with the
+     * number of frames completed so far. A frame that throws is not one of them: whatever it had
+     * recorded may still have been submitted, but it sends nothing and is not counted.
+     *
+     * **Submitted, not finished.** The frame's commands have been handed to the queue and the GPU
+     * may not have started them; a listener that needs the GPU to be done with the frame waits on
+     * {@link GPUQueue#onSubmittedWorkDone} instead.
+     *
+     * @type {Signal<number>}
+     */
     onFrameFinished = new Signal();
 
     /**
@@ -702,6 +716,79 @@ export class Renderer {
         return this.#extensions.count(phase);
     }
 
+    /**
+     * Transparent sources an outside caller has put into the transparency pipeline, in the order
+     * they were added — which means nothing: the volume and the accumulators they draw into are sums.
+     *
+     * @type {AVBOITSideChannel[]}
+     */
+    #transparency_channels = [];
+
+    /**
+     * Put a transparent source that is not a meshlet bucket into the transparency pipeline: an
+     * `AVBOITSideChannel`, whose fragments are then composited order-independently against the
+     * transparent meshes, the particles and every other channel.
+     *
+     * **This is what an extension cannot do.** Work at `AfterTransparency` composites over the
+     * resolved transparency and cannot interleave with it. A channel is asked instead for its
+     * occupancy, its splat and its draw at the three points where the meshlet buckets contribute
+     * theirs, every frame; one that says it has nothing to add (`avboit_is_empty`) is left out of
+     * that frame, so registering one does not by itself make the pipeline run. There is no order to
+     * declare — order among channels changes no pixel.
+     *
+     * **AVBOIT only.** Under {@link ShadeTransparencyMode.MBOIT}, or with transparency off, a channel
+     * is asked for nothing and what it holds is not drawn — as for the particles.
+     *
+     * @param {AVBOITSideChannel} channel
+     * @returns {AVBOITSideChannel} `channel`, for handing back to {@link remove_transparency_channel}
+     */
+    add_transparency_channel(channel) {
+        assert.defined(channel, 'channel');
+        assert.isFunction(channel.avboit_occupancy, 'channel.avboit_occupancy');
+        assert.isFunction(channel.avboit_splat, 'channel.avboit_splat');
+        assert.isFunction(channel.avboit_draw, 'channel.avboit_draw');
+
+        if (channel.avboit_is_empty !== undefined) {
+            // optional, but asked every frame when present — a flag where a method belongs would
+            // throw in the middle of a frame rather than here
+            assert.isFunction(channel.avboit_is_empty, 'channel.avboit_is_empty');
+        }
+
+        // Once, whatever the caller does. In the list twice it would be drawn twice — every
+        // extinction and every colour it adds, doubled — and that has to hold in a build whose
+        // asserts are stripped, so a repeat is a no-op rather than a failed assertion.
+        if (!this.#transparency_channels.includes(channel)) {
+            this.#transparency_channels.push(channel);
+        }
+
+        return channel;
+    }
+
+    /**
+     * Take a channel back out of the transparency pipeline.
+     *
+     * @param {AVBOITSideChannel} channel
+     * @returns {boolean} whether it was registered
+     */
+    remove_transparency_channel(channel) {
+        const index = this.#transparency_channels.indexOf(channel);
+
+        if (index === -1) {
+            return false;
+        }
+
+        this.#transparency_channels.splice(index, 1);
+
+        return true;
+    }
+
+    /**
+     * @returns {number} how many transparency channels are registered
+     */
+    transparency_channel_count() {
+        return this.#transparency_channels.length;
+    }
+
 
     /**
      *
@@ -1060,10 +1147,12 @@ export class Renderer {
     #particle_systems = new Map();
 
     /**
-     * The side-channel list handed to the transparency orchestrator, reused frame to frame.
-     * @type {GPUParticleSystem[]}
+     * The side-channel list handed to the transparency orchestrator, rebuilt every frame and reused
+     * frame to frame: the particles when they are on, then every registered transparency channel
+     * that has something to add.
+     * @type {AVBOITSideChannel[]}
      */
-    #particle_side_channels = [];
+    #side_channels = [];
 
     /**
      * The particle system of a scene — created on first use, so a scene without emitters costs
@@ -1446,9 +1535,37 @@ export class Renderer {
     }
 
     /**
-     * Cleanup
+     * Whether {@link destroy} has been called. Rendering afterwards would encode against resources
+     * that are gone, so it refuses the same way a lost device does.
+     *
+     * @type {boolean}
+     */
+    #destroyed = false;
+
+    /**
+     * Release everything {@link initialize} built, in reverse.
+     *
+     * This used to be the media-query listener and the particle systems, and nothing else: not the
+     * graphics context, not the depth ping-pong or TAA history textures, not the visibility
+     * target, not the scene, view or camera contexts — each of which owns GPU buffers — and none
+     * of the post-process subsystems. GraphicsEngine.stop() calls it and its own doc calls
+     * stop/start symmetric and repeatable, so a tool that swaps renderers per document exhausted
+     * device memory in a handful of cycles, leaking a whole G-buffer, depth and history set at
+     * output resolution plus the scene database, the meshlet pool, the light collection, every
+     * shadow view's camera buffer and the entire texture cache, every time.
+     *
+     * Two things stay out of it: {@link #postprocess} and {@link #path_tracer} own no GPU
+     * resources of their own and expose no teardown, and the device itself is not destroyed here
+     * because the renderer may not own it.
+     *
+     * @returns {void}
      */
     destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
 
         window.matchMedia("(dynamic-range: high)").removeEventListener("change", this.#update_hdr_support);
 
@@ -1456,6 +1573,54 @@ export class Renderer {
             system.destroy();
         }
         this.#particle_systems.clear();
+
+        for (const baker of this.#probe_bakers.values()) {
+            baker.destroy();
+        }
+        this.#probe_bakers.clear();
+
+        for (const sdf of this.#scene_sdfs.values()) {
+            sdf.destroy();
+        }
+        this.#scene_sdfs.clear();
+
+        this.#autoexposure?.destroy();
+        this.#depth_of_field?.destroy();
+        this.#depth_of_field_unreal?.destroy();
+        this.#restir_di?.destroy();
+        this.#nss?.destroy();
+
+        this.#views?.destroy();
+        this.#scenes?.destroy();
+        this.#cameras?.destroy();
+
+        this.#destroy_render_targets();
+
+        this.#graphics?.destroy();
+    }
+
+    /**
+     * The textures {@link init_render_targets} and {@link #resize_render_targets} allocate outside
+     * the frame graph. They come from `textures.contextFromDescriptor`, which does not put them in
+     * the manager's cache, so nothing else will ever release them.
+     *
+     * @returns {void}
+     */
+    #destroy_render_targets() {
+        const targets = [
+            ...this.#textures_depth,
+            ...this.#textures_taa_history,
+            ...(this.#vis_render_target?.color_attachments ?? []),
+        ];
+
+        for (const target of targets) {
+            target?.destroy();
+        }
+
+        this.#textures_depth.fill(undefined);
+        this.#textures_taa_history.fill(undefined);
+
+        this.#vis_render_target = undefined;
     }
 
 
@@ -1745,15 +1910,18 @@ export class Renderer {
      * simulation, the animation tick and exposure adaptation all step by it. Zero by default, which
      * draws the current state and moves nothing; a fixed fraction of a second here instead would run
      * the simulation at that rate no matter what the caller's clock was doing.
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     * @returns {boolean} whether a frame was encoded and submitted. False only when there is nothing
+     * to draw with — the device was lost, or the renderer destroyed. Frames the GPU has not finished
+     * yet neither hold this one back nor make it return false.
      */
     render(
         camera,
         scene,
         time_delta_seconds = 0
     ) {
-        if (this.#device_lost) {
-            // device is lost, can't render — and asking the context for a texture would throw
+        if (this.#device_lost || this.#destroyed) {
+            // device is lost or the renderer was torn down, so there is nothing to encode against —
+            // and asking the context for a texture would throw
             return false;
         }
 
@@ -1783,19 +1951,106 @@ export class Renderer {
      * @param {Scene} scene
      * @param {number} time_delta_seconds
      * @param {GPUTextureContext} target must match {@link output_resolution}
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     * @returns {boolean} whether a frame was encoded and submitted. False only when there is nothing
+     * to draw with — the device was lost, or the renderer destroyed. Frames the GPU has not finished
+     * yet neither hold this one back nor make it return false.
      */
     render_to_target(
         camera,
         scene,
         time_delta_seconds,
         target
+    ) {
+        try {
+            return this.#draw_to_target(camera, scene, time_delta_seconds, target);
+        } catch (error) {
+            this.#finish_stranded_frame();
+
+            throw error;
+        }
+    }
+
+    /**
+     * The frame's command context from the moment it is created until the frame's teardown takes
+     * it, and null otherwise — so a frame that throws before its teardown leaves it here for
+     * {@link render_to_target} to finish.
+     *
+     * @type {ShadeGPUCommandContext|null}
+     */
+    #frame_command_ctx = null;
+
+    /**
+     * The profiler's recorder for the frame {@link #frame_command_ctx} belongs to, and the session
+     * that handed it out — null when that frame is not profiled — so a frame that throws before its
+     * teardown still closes its profile frame. Otherwise a capture leaves out exactly the frames
+     * that failed.
+     *
+     * @type {GPUFrameRecorder|null}
+     */
+    #frame_profile_recorder = null;
+
+    /**
+     * @type {GPUProfileSession|null}
+     */
+    #frame_profile_session = null;
+
+    /**
+     * Finish the context a frame left behind when it threw before its teardown: the scene tick, the
+     * shadow draw and every extension phase run between the context's creation and the teardown,
+     * and a throw from any of them used to leave it open for good, holding its upload block, its
+     * transient buffers and its profiler's buffers — every frame it happened.
+     *
+     * What comes back is what it holds. What it recorded is submitted if the encoder can still be
+     * finished: a throw once the `Shade` debug group is open leaves that group unclosed, the
+     * command buffer is invalid, and the submission is refused with nothing of the frame run — as it
+     * is for a pass that throws, whose teardown shares the same unclosed group.
+     */
+    #finish_stranded_frame() {
+        const stranded = this.#frame_command_ctx;
+        const recorder = this.#frame_profile_recorder;
+        const session = this.#frame_profile_session;
+
+        this.#frame_command_ctx = null;
+        this.#frame_profile_recorder = null;
+        this.#frame_profile_session = null;
+
+        if (stranded === null) {
+            return;
+        }
+
+        try {
+            stranded.finish();
+        } catch (teardown_error) {
+            // already unwinding: the frame's own error is the one the caller needs to see
+        }
+
+        if (recorder !== null) {
+            stranded.profiling_absorbed.then(() => {
+                session.end_frame(recorder, performance.now());
+            });
+        }
+    }
+
+    /**
+     * The whole of {@link render_to_target}, which only adds the finishing of a frame that throws.
+     *
+     * @param {PerspectiveCamera} camera
+     * @param {Scene} scene
+     * @param {number} time_delta_seconds
+     * @param {GPUTextureContext} target
+     * @returns {boolean}
+     */
+    #draw_to_target(
+        camera,
+        scene,
+        time_delta_seconds,
+        target
     ) {
         assert.defined(target, 'target');
         assert.equal(target.isGPUTextureContext, true, 'target.isGPUTextureContext !== true');
 
-        if (this.#device_lost) {
-            // device is lost, can't render
+        if (this.#device_lost || this.#destroyed) {
+            // device is lost or the renderer was torn down, so there is nothing to encode against
             return false;
         }
 
@@ -1839,8 +2094,11 @@ export class Renderer {
 
         const resolution_internal = this.#internal_resolution;
         {
-            const jitter_x = jitter_source.Jitter[0];
-            const jitter_y = jitter_source.Jitter[1];
+            // no jitter when nothing is going to resolve it — see frame_jitter_applies
+            const jitter_applies = frame_jitter_applies(this.#feature_taa_enabled, this.upscale_type);
+
+            const jitter_x = jitter_applies ? jitter_source.Jitter[0] : 0;
+            const jitter_y = jitter_applies ? jitter_source.Jitter[1] : 0;
 
             view_ctx.setJitter(jitter_x, jitter_y);
             view_ctx.setViewportSize(resolution_internal.x, resolution_internal.y);
@@ -1863,6 +2121,8 @@ export class Renderer {
             "Renderer/main-0"
         );
 
+        this.#frame_command_ctx = command_ctx;
+
         /**
          * The frame recorder for this frame, or null when nothing is profiling.
          * @type {GPUFrameRecorder|null}
@@ -1876,6 +2136,9 @@ export class Renderer {
 
             if (profile_recorder !== null) {
                 command_ctx.enable_profiling(profile_recorder, 0);
+
+                this.#frame_profile_recorder = profile_recorder;
+                this.#frame_profile_session = this.profile_session;
             }
         }
 
@@ -2326,8 +2589,8 @@ export class Renderer {
 
         // Particles move here, after the scene's nodes have their world matrices for the frame, and
         // draw below as a side channel of the transparency pipeline.
-        const particle_side_channels = this.#particle_side_channels;
-        particle_side_channels.length = 0;
+        const side_channels = this.#side_channels;
+        side_channels.length = 0;
 
         if (this.feature_particles_enabled) {
             const particles = this.particles(scene_ctx);
@@ -2345,7 +2608,26 @@ export class Renderer {
                 dt: time_delta_seconds,
             });
 
-            particle_side_channels.push(particles);
+            side_channels.push(particles);
+        }
+
+        // Every channel registered from outside, unless it says it has nothing to add: the
+        // orchestrator runs whenever it has a channel, and one that is always registered would
+        // otherwise make every frame pay for the whole pipeline. Only when something will ask them
+        // — with transparency off, or under MBOIT, which takes no side channels, a channel is not
+        // consulted at all.
+        if (this.#feature_enabled_transparencies && this.transparency_mode === ShadeTransparencyMode.AVBOIT) {
+            const transparency_channels = this.#transparency_channels;
+
+            for (let i = 0; i < transparency_channels.length; i++) {
+                const channel = transparency_channels[i];
+
+                if (channel.avboit_is_empty !== undefined && channel.avboit_is_empty()) {
+                    continue;
+                }
+
+                side_channels.push(channel);
+            }
         }
 
         if (this.#feature_enabled_transparencies) {
@@ -2379,7 +2661,7 @@ export class Renderer {
 
                 indirect_lighting_mode: this.indirect_lighting_mode,
                 avboit: this.avboit,
-                side_channels: particle_side_channels,
+                side_channels,
             });
 
             graph.pop_scope();
@@ -2484,6 +2766,9 @@ export class Renderer {
                 velocity: gr_velocity,
                 depth: gr_texture_depth_current,
                 resolution: this.#output_resolution.asArray(),
+                // both are built against the internal resolution, which is not the output grid
+                // whenever anything is being upscaled
+                velocity_resolution: this.#internal_resolution.asArray(),
             });
         }
 
@@ -2505,27 +2790,45 @@ export class Renderer {
 
         let exposure = -1;
 
-        if (this.feature_bloom_enabled || this.feature_automatic_exposure_enabled) {
+        /*
+         The scene as it stands before bloom composites over it: what the metering reads, and what
+         bloom reads too.
+
+         The metering used to read `bloom.downsampled` — mip 0 of the bloom chain — because it was
+         already half-res and already there. It is produced by `downsample_karis`, which weights
+         each tap by 1/(1+luma) for the express purpose of DESTROYING bright outliers so they do not
+         bloom, and the histogram is read over the 70th to 95th percentile window: exactly the
+         bright tail that weighting suppresses. Three dark texels and one bright one in a quad
+         average 6x darker through it than through a box filter, so a scene with small bright
+         highlights — sun glints, emissive signage, a lit window in a dark room — metered low and
+         was therefore rendered over-exposed by the same amount. The coupling was invisible from
+         here: the two subsystems shared a texture for a reason that had nothing to do with
+         metering, and the filter that made it wrong lives in the bloom folder.
+
+         Full-res, so the tail it meters is the tail that is on screen. That is four times the
+         histogram invocations of the old half-res mip, on a shader that is a load, a luminance and
+         an atomic add.
+        */
+        const metered_color = current_color_out;
+
+        if (this.feature_bloom_enabled) {
             const bloom = graph_postprocess_bloom({
                 graph,
                 input: current_color_out,
                 resolution: this.#output_resolution.asArray(),
             });
 
-            if (this.feature_bloom_enabled) {
-                current_color_out = bloom.composited;
-            }
-
-            if (this.feature_automatic_exposure_enabled) {
-                // TODO force time_delta_second to a very high value on view transition
+            current_color_out = bloom.composited;
+        }
 
-                exposure = this.#autoexposure.update({
-                    graph,
-                    input_color: bloom.downsampled,
-                    time_delta_seconds,
-                });
-            }
+        if (this.feature_automatic_exposure_enabled) {
+            // TODO force time_delta_second to a very high value on view transition
 
+            exposure = this.#autoexposure.update({
+                graph,
+                input_color: metered_color,
+                time_delta_seconds,
+            });
         }
 
 
@@ -2625,6 +2928,11 @@ export class Renderer {
          destroyed, and the session's frame accounting silently short a frame. A render loop that
          catches and carries on repeats that every failing frame until the device complains.
         */
+        // the teardown has it from here, whatever the finish does
+        this.#frame_command_ctx = null;
+        this.#frame_profile_recorder = null;
+        this.#frame_profile_session = null;
+
         try {
             command_ctx.finish();
         } catch (teardown_error) {

package/src/shade/renderer/animation/ANIMATION_CLIP_STATE_STRUCT.d.ts

@@ -7,13 +7,10 @@
  * the curves' clock) and feeds the result to each bound track's curve
  * evaluator.
  *
- * Membership is represented as a singly-linked list of bound-track group
- * nodes whose head index is {@link bound_track_group_head}. Group nodes
- * each inline up to {@link TRACKS_PER_GROUP_NODE} bindings and chain
- * forward via their own `next` pointer; clips with zero bindings store
- * `0xFFFFFFFF`. The chain replaces the previous `animation_clip_bindings`
- * relationship table, so adding bindings to a clip no longer touches a
- * separate table.
+ * Membership is a run of rows of `animation_bindings`, named by
+ * {@link bindings_first} and {@link bindings_count} — a range the database
+ * knows about, so removing the clip's row takes its bindings with it. A
+ * clip with no bindings yet holds the empty range `(0xFFFFFFFF, 0)`.
  *
  * Tracks within a clip don't have to share the clip's `[time_start,
  * time_end]` window — their curves are clamped to their own

package/src/shade/renderer/animation/ANIMATION_CLIP_STATE_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ANIMATION_CLIP_STATE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_CLIP_STATE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uDA2EyB;6BApGI,gCAAgC"}
+{"version":3,"file":"ANIMATION_CLIP_STATE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_CLIP_STATE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uDAiFyB;6BAvGI,gCAAgC"}

package/src/shade/renderer/animation/ANIMATION_CLIP_STATE_STRUCT.js

@@ -10,13 +10,10 @@ import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
  * the curves' clock) and feeds the result to each bound track's curve
  * evaluator.
  *
- * Membership is represented as a singly-linked list of bound-track group
- * nodes whose head index is {@link bound_track_group_head}. Group nodes
- * each inline up to {@link TRACKS_PER_GROUP_NODE} bindings and chain
- * forward via their own `next` pointer; clips with zero bindings store
- * `0xFFFFFFFF`. The chain replaces the previous `animation_clip_bindings`
- * relationship table, so adding bindings to a clip no longer touches a
- * separate table.
+ * Membership is a run of rows of `animation_bindings`, named by
+ * {@link bindings_first} and {@link bindings_count} — a range the database
+ * knows about, so removing the clip's row takes its bindings with it. A
+ * clip with no bindings yet holds the empty range `(0xFFFFFFFF, 0)`.
  *
  * Tracks within a clip don't have to share the clip's `[time_start,
  * time_end]` window — their curves are clamped to their own
@@ -55,11 +52,15 @@ export const ANIMATION_CLIP_STATE_STRUCT = WebGPUStruct.from({
     time_end: f32,
 
     /**
-     * Index of the head node of the bound-track group chain in the
-     * `animation_bound_track_groups` table, or `0xFFFFFFFF` if the clip
-     * has no bindings.
+     * First row of the clip's bindings in the `animation_bindings` table,
+     * or `0xFFFFFFFF` if the clip has none.
      */
-    bound_track_group_head: u32,
+    bindings_first: u32,
+
+    /**
+     * How many bindings the run holds; 0 if the clip has none.
+     */
+    bindings_count: u32,
 
     /**
      * Per-frame `time` advance is `dt * playback_rate`. `1.0` is
@@ -71,11 +72,13 @@ export const ANIMATION_CLIP_STATE_STRUCT = WebGPUStruct.from({
 
     /**
      * Bitfield of {@link AnimationClipFlags} — `Playing`, `Loop`, etc.
-     * The tick shader reads this every frame; the host writes it via
-     * {@link GPUAnimationManager#set_flags} (full overwrite) or has it
-     * partially toggled by {@link GPUAnimationManager#start} /
-     * {@link GPUAnimationManager#stop} (Playing bit only). Defaults to
-     * `0` at clip creation: not playing, not looping.
+     * The tick shader reads this every frame and never writes it; the
+     * host sets and clears bits of it via
+     * {@link GPUAnimationManager#set_flags} /
+     * {@link GPUAnimationManager#clear_flags}, or the Playing bit alone
+     * via {@link GPUAnimationManager#start} /
+     * {@link GPUAnimationManager#stop}. Defaults to `0` at clip
+     * creation: not playing, not looping.
      */
     flags: u32,
 

package/src/shade/renderer/animation/ANIMATION_CURVE_HEADER_STRUCT.js

@@ -7,21 +7,21 @@ export const ANIMATION_CURVE_HEADER_STRUCT = WebGPUStruct.from({
      */
     kind: u32,
     /**
-     * Index of the head keyframe block in the `animation_keyframe_blocks`
-     * table. The block at this index inlines up to
-     * {@link KEYFRAMES_PER_BLOCK} keyframes and points at the next block
-     * via its own `next` field; the chain ends when a block's `next` is
-     * `0xFFFFFFFF`. Replaces the previous "contiguous run of keyframes"
-     * layout, so curves can grow independently without forcing
-     * keyframe-table compaction.
+     * First row of the curve's keyframes in the `animation_keyframes` table: a run of
+     * {@link keyframe_count} rows, one keyframe each, in ascending time order. The two words are a
+     * range the database knows about, so removing the curve's row would take its keyframes with it.
      */
-    keyframe_block_head: u32,
+    keyframes_first: u32,
     /**
-     * Total number of keyframes summed across the chain. The evaluator
-     * uses this only for the single-keyframe fast path; ordinary
-     * evaluation walks blocks until it hits the chain terminator.
+     * How many keyframes the run holds — at least one for any curve.
      */
     keyframe_count: u32,
+    /**
+     * Time of the first keyframe.
+     */
     time_min: f32,
+    /**
+     * Time of the last keyframe.
+     */
     time_max: f32,
 })