/** * Two-tier frame cache. * * The preview tier holds many downscaled frames: a long, coarse history that * answers a scrub instantly while the crisp frame decodes. The exact tier holds * a few full-resolution frames, bounded by a RAM budget rather than a fixed * count so the slot count tracks frame size. * * A lookup prefers exact, then preview, tagging the hit with the tier that * served it. Only an exact hit is full-resolution; a preview hit still owes the * caller a crisp decode. * * The exact tier is keyed by the timeline's identity for the frame, so two * source frames can never share a slot at any frame rate. The preview tier is * keyed by rounded millisecond, which merges frames spaced under a millisecond; * it is the tier whose answer is already declared approximate, and it never * claims to be the frame at the target. * * Both tiers store OffscreenCanvas blits, never VideoFrames: a raw-frame cache * pins decoder output, stalling the decoder and growing VRAM without bound. A * frame fed as a live VideoSample is drawn into the blit and never retained, so * the no-retention rule holds on the zero-copy path too. */ import type { FrameId } from "./frame-timeline"; import type { VideoSampleLike } from "./scrub-cursor"; /** * What the cache can blit into a tier: an already-decoded canvas/image, or a * live VideoSample it draws once and never retains. The sample's draw scales to * the tier size just like drawImage does, so the stored blit is identical either * way. */ export type CacheBlitSource = CanvasImageSource | VideoSampleLike; export declare enum FrameTier { Exact = "exact", Preview = "preview" } export interface CachedFrame { readonly canvas: OffscreenCanvas; readonly timestampMs: number; readonly tier: FrameTier; } export interface FrameCacheStats { readonly exactHits: number; readonly previewHits: number; readonly misses: number; readonly exactSize: number; readonly previewSize: number; readonly exactCapacity: number; readonly previewCapacity: number; /** True timestamps (ms) currently resident in each tier, for the diagnostics * timeline. Bounded by capacity, so a small array per poll. */ readonly exactTimestampsMs: number[]; readonly previewTimestampsMs: number[]; /** Configured source frame interval: the visual width of each cached mark on * the timeline. Nothing is keyed by it, so this is a display width and not * the grid entries land on. */ readonly bucketMs: number; /** Frames dropped to LRU pressure per tier, and puts that overwrote a live * key: a frame decoded again on the exact tier, and on the preview tier * either that or two frames sharing one rounded millisecond. */ readonly exactEvictions: number; readonly previewEvictions: number; readonly bucketCollapses: number; /** Per-tier frame dimensions and the crisp tier's RAM ceiling, so a consumer * can derive resident bytes (size x w x h x 4) and the budget fill. */ readonly exactFrameWidth: number; readonly exactFrameHeight: number; readonly previewFrameWidth: number; readonly previewFrameHeight: number; readonly exactBudgetBytes: number; } export interface FrameCacheOptions { /** Crisp-tier frame size, the cursor's decode resolution. */ readonly exactWidth: number; readonly exactHeight: number; /** Coarse-tier width; height derives from the exact aspect ratio. */ readonly previewWidth: number; /** Limit the configured coarse width to the current decode width. */ readonly fitPreviewToOutput?: boolean; /** Crisp scrub-tier RAM ceiling in bytes; slot count derives from frame size. */ readonly exactBudgetBytes: number; /** Coarse-tier slot count. */ readonly previewCapacity: number; /** Coarse-tier byte ceiling, additionally limiting its slot count. */ readonly previewBudgetBytes?: number; /** Source frame interval in ms, reported to diagnostics as the timeline mark * width. It keys nothing. */ readonly bucketMs: number; /** Floor on exact-tier slots, applied even when the byte budget would yield * fewer. Lets a caller that owns the prefetch-window width guarantee a full * window fits regardless of frame size. The cache stays ignorant of the * window; it only honors the number it is handed. */ readonly minExactSlots?: number; } export declare class FrameCache { private readonly options; private readonly exact; private readonly preview; private exactHits; private previewHits; private misses; private readonly bucketMs; private readonly exactBudgetBytes; constructor(options: FrameCacheOptions); resized(width: number, height: number): FrameCache; /** * Store a crisp full-resolution frame for the exact (scrub) tier under * `frame`, the timeline's name for it. `timestampMs` is the decoded * timestamp, which is what lookups match on and what a hit reports back. */ putExact(frame: FrameId, timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void; /** Store a downscaled frame for the coarse preview tier. */ putPreview(timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void; /** * Best cached answer for a named source frame. The exact tier is looked up * only by `frame` identity; time is used solely for the approximate preview * fallback. This keeps a long variable-rate frame from borrowing a crisp * neighbour merely because both timestamps fit a millisecond tolerance. */ getForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null; /** Non-accounting form of {@link getForFrame}. */ peekForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null; /** Preview-only lookup without hit accounting or LRU promotion. */ peekPreview(timestampMs: number, toleranceMs: number): CachedFrame | null; /** * Best cached frame for `timestampMs`, consulting the exact tier then the * preview tier: a crisp hit within `exactTolMs`, else a coarse hit within * `previewTolMs`, else null. The two tolerances differ because the exact tier * is keyed per source frame while the preview tier may only hold sparse * keyframes. * * `exactTolMs` is an upper bound, not the reach: a crisp hit is also held to * the frame span the exact tier has observed, since a tolerance wider than * one frame (50ms is, at every rate from 24 to 60fps) would let a neighbour * answer as the exact frame. */ get(timestampMs: number, exactTolMs: number, previewTolMs: number): CachedFrame | null; /** * Same lookup as get() but without touching the hit/miss accounting. The * synchronous render-loop peek and the authoritative seek both hit the cache * for one user gesture; counting both double-books every scrub. The peek * uses this so only the seek's get() is tallied, keeping the hit-rate a * per-lookup rate rather than two-per-gesture. */ peek(timestampMs: number, exactTolMs: number, previewTolMs: number): CachedFrame | null; /** * Marks the exact entry nearest `timestampMs` as most-recently-used without * counting a hit. Lets the scheduler protect the just-shown center frame * from being the LRU victim of its own neighbor sweep. No-op on a miss. */ bumpExact(timestampMs: number): void; /** Promotes one exact frame by identity. */ bumpExactFrame(frame: FrameId): void; /** Protects a resident preview during a sweep that fills other targets. */ bumpPreview(timestampMs: number): void; clear(): void; get stats(): FrameCacheStats; } interface TierHit { readonly canvas: OffscreenCanvas; readonly timestampMs: number; } /** * One cache tier: a fixed-capacity, MRU-ordered set of OffscreenCanvas copies * under keys its owner assigns. A put onto a live key overwrites that slot in * place, so an owner that lets two frames share a key loses one of them * silently; overflow past capacity evicts the least-recently-used entry * instead. Lookups match on the stored frame's true timestamp and never on the * key, so a cache-served frame carries the same timestamp a fresh decode would. */ export declare class TierStore { readonly capacity: number; readonly width: number; readonly height: number; /** Width of the grid the owner's keys round onto, or 0 when a key names a * frame outright. Two entries closer together than this are one frame * whose two decodes rounded onto either side of a key boundary. */ private readonly keyGridMs; /** MRU-ordered keys. Index 0 is the LRU, the last index is the MRU. */ private readonly keys; private readonly entries; /** Canvases released by eviction, held for the next put to fill. */ private readonly spare; private evictionCount; private bucketCollapseCount; /** Smallest gap between two stored frames, which is the source frame interval * once neighbours are resident. Learned from the timestamps the tier is * handed, so it is what the source really did rather than a declared rate. * Null until two frames have landed. */ private observedIntervalMs; constructor(capacity: number, width: number, height: number, /** Width of the grid the owner's keys round onto, or 0 when a key names a * frame outright. Two entries closer together than this are one frame * whose two decodes rounded onto either side of a key boundary. */ keyGridMs: number); /** Frames dropped to the LRU policy; a cache-pressure signal for diagnostics. */ get evictions(): number; /** Puts that landed on a key already live, collapsing both onto one slot. */ get bucketCollapses(): number; put(key: number, timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void; /** * Nearest resident frame to `timestampMs` within `tolMs`, or null. * * `atOrBefore` restricts it to frames at or before the target, which is the * contract a decode answers a seek with. Without it the tier can answer with * the frame AFTER the target, one no decode would ever return, so the same * pointer position paints a different frame depending on whether the cache or * the decoder served it, and the picture steps forward and back as the two * alternate. */ get(timestampMs: number, tolMs: number, atOrBefore?: boolean): TierHit | null; peek(timestampMs: number, tolMs: number): TierHit | null; /** Retrieves exactly one owner-assigned key and promotes it to MRU. */ getByKey(key: number): TierHit | null; /** Promotes the entry nearest `timestampMs` to most-recently-used. Scans * rather than keys off the timestamp: callers pass a gesture position, which * is not a frame timestamp, so a keyed lookup would miss the very frame on * screen. No accounting; it is not a lookup. */ touch(timestampMs: number): void; /** Promotes an owner-assigned key without a timestamp scan. */ touchKey(key: number): void; clear(): void; get size(): number; /** True timestamps (ms) of resident frames, for diagnostics. Bounded by capacity. */ timestampsSnapshot(): number[]; private bump; /** * Best candidate for `timestampMs`, or null when nothing qualifies. * * Under `atOrBefore` a stored frame stands for the span from its own * timestamp up to the next source frame; a target past that span belongs to * the next frame, which is what a decode for it returns. Answering it from * this tier would paint a frame no decode for that time ever produces, so a * candidate outside its own frame's span is not eligible however generous the * caller's tolerance is. Until the tier has learned a frame gap it has no * spacing to bound with and the caller's tolerance stands alone. */ private nearest; /** Narrows the learned frame interval to the smallest gap seen so far. A gap * at or below the key grid is one frame that rounded onto two keys rather * than two frames, so it is no interval at all; what survives is a gap * between two frames, and never zero. It only ever tightens, so a tier that * has watched an unrepresentative stretch of a variable-rate source bounds * lookups too tightly (a decode) rather than too loosely (the wrong frame). */ private observeSpacing; } export {};