MediaPool::aux (no render asks for it: renders ask for what their effects read) again gives every channel, the picture's too, so the pinned OpenEXR golden hashes stay as they were; 'all channels' without the picture applies to the effects' requests. docs/effects.md is generated: the note on static channel selection lives in docs/footage.md.
The cancellable footage view passed aux and aux_for straight to the source, so a viewer render called off during a channel decode kept decoding. They now go through the render's cancel flag like frame reads (a decode stops between batches; once called off none starts). A test checks a channel read runs under the flag and none starts after; it fails on the old code.
The parameters that pick which channels or Cryptomatte layer an effect reads (EXtractoR's Red/Green/Blue/Alpha, Cryptomatte's Layer and Layer Name, 3D Channel Extract's 3D Channel, ID Matte's Aux. Channel and Use Coverage, IDentifier's Channel Type) are static, as in After Effects where they have no stopwatch: no keyframes, no expression (prop.addKey, prop.toggleKey, prop.toggleAnimation and prop.setExpression refuse; prop.set changes the value). A document or an import that animated one keeps its first value and says so (a toast on open, a loss on .aep import). With that, what a frame reads is known from the values alone: the 'all channels' fallbacks for moving parameters and for effects that don't declare are gone (every channel effect declares; a test holds them to it), and a layer whose effects read no channels asks for none. Tests: the parameters refuse keys and expressions and the need is exactly the channel picked; a keyed channel selection opens static with its first value and is reported (both fail on the old code); the migration keeps the first key's value.
The plane store kept the R, G, B, A planes a picture was made of whenever the picture was read with channels for its effects (or with all of them), beside the converted picture in the media pool's frame cache: the same pixels twice. Once the picture is converted, its planes now leave the stored set (in place when nobody else holds it), but for a picture channel an effect names itself (EXtractoR reading R). 'All channels' means every channel but the picture's. A test reads a picture with one channel, with a named picture channel and with all channels, and checks exactly what stays and its bytes; it fails on the old code.
The plane store had a fixed 1 GB budget of its own, outside the preferences: with a Footage Frame Cache of 10000 MB it still held about 2.5 frames of a 69-channel 1080p file. The plane store and the media pool's frame cache now share the Footage Frame Cache (set_cache_budget sizes both and the memory accountant's footage group), with one least-recently-used order: each use takes a stamp from one shared counter, and over the footage budget the accountant drops the least recently used item, frame or plane set, whichever holder keeps it. Neither side has a share of its own. The common budget no longer adds a separate plane budget; the browser keeps its 512 MB cap on the planes. Tests: a footage budget of 10000 MB sizes the plane store (and resizes it at run time); filling the frame cache drops the oldest plane sets and filling the plane store drops the oldest frames (fails without the shared order: the frames went first); an accountant group shares its budget.
A drop guard takes the copy hook out and turns the localizer off at the end of the test that installs the hook, also when an assertion fails, so a later test doesn't inherit a hook that holds its copies.
The Disk page's localizer status was drawn only when something else redrew the page, so its queue and the file being copied stood still. While files are queued or copied it is drawn again every half second; idle, not at all. Network Footage Locations shows a hint (and tooltip) that it takes folders or drives separated by ;, translated in the eight catalogs that have the localizer's strings.
The panel worked a thumbnail's content key out again only when the project's revision or the time changed, so a Reload Footage or a watched file that changed (the revision stays) kept the old key and the old thumbnail. The footage reload count is now part of the panel's check. A panel test bumps the reload count alone; it fails on the old code.
PreviewMemory::trim_to counts the frames in RAM but took the next victim among all frames, GPU frames too: dropping one freed nothing it counts and lost a viewer frame. Victims are now taken among the frames an eligibility test accepts, in the same order (other scales first, then by the playhead): frames in RAM for the accountant, all frames for the cache's own budget. A test (with a GPU adapter) keeps the two oldest frames on the GPU; it fails on the old code.
With a viewer region of interest the renderer asked a PNG still for some rows, which the media pool reads whole anyway, and the layer was left out of the layer cache: its masks and effects ran again on every render. FootageSource::reads_rows tells whether a source reads only the rows asked for (the media pool: an OpenEXR frame whose channels no effect reads); otherwise the renderer asks for the whole frame and the layer stays cached. A test renders a still twice under a region; it fails on the old code (two row reads instead of one whole read).
The sweep after Reload Footage read up to 64 KiB of every entry to find its source files; plane entries are many (one per channel and frame) and each lists one small source file. A plane entry's head is now 4 KiB, with the full-file read kept for a longer list. A test counts the bytes read for a large plane entry; it fails on the old code (65536 bytes).
A read asking for a network file while the localizer copied it queued it again, and the file was copied over the network a second time. The file being copied is now remembered with the setting it is copied under; asked for again under the same setting it isn't queued, under a new one it is. A test holds a copy and asks again; it fails on the old code.
The decode thread's job held the flight until it ended, and the flight keeps the outcome for its waiters, so on a busy machine the planes just decoded still looked in use and the store dropped another file's instead (the eviction test failed on CI). The job now drops the flight before it sends the outcome. A test holds the decode thread after it sent; it fails with the old order. 300 runs of both eviction tests pass.
forget() bumped one generation for the whole pool, so forgetting any file
(every file-watcher change, every add_bytes) left every other file's
decodes in flight uncached and unjoinable, and requests decoded those files
again. The generation is now an epoch: forget() records it per path, and a
decode, flight or kept picture is stale only when its own path was
forgotten after it started. The per-path map is bounded (4096 paths; past
that, everything older counts as stale).
Refs #3269
The plane store's staleness is per file: a flight lives in its file's entry and forget drops only that file's entry. This test guards that a decode of one file in flight while another file is forgotten is still kept and joined; it fails when forget drops other files' in-flight entries.
The plane store keeps its flight in the file's entry, and forget drops the entry, so a request made after a forget never joins a decode of the old file. This test guards that: it fails when forget keeps an entry with a flight.
A request made after its file was forgotten (it changed on disk) while the
file's decode was in flight joined that decode, got the old pixels and kept
them in the frame cache as the new file's. Each flight now carries the
generation it started in; a request only joins a flight of its own
generation and otherwise decodes the file anew.
Refs #3269
Review fixes for the disk plane writes:
- A queued write holds copies of the planes it writes instead of the
plane store's whole set, so it counts exactly what it holds, the
memory accountant's trim frees what the queue reports, and it never
keeps the store from letting a set go.
- A set is queued in writes of at most 256 MB, and only a single plane
larger than the cache is left out, so a large set (a 4K file of many
channels) reaches the disk plane by plane instead of being refused
whole.
- Each plane entry counts as one encode again.
- A plane entry is shuffled straight from the samples' bits, without
the widened intermediate copies.
A queued plane write shares the plane store's set, which keeps the store
from letting go of it; trimming the disk queue now drops such writes
too, so the store can free the set in the same balance. The reader uses
saturating offsets, and the batch test fails a later batch by position.
- The reader reads the next batch of chunks while the one before
decompresses, reads chunks that follow each other in the file in one
request, starts with a small batch so decoding begins early, places
the planes in parallel, and converts half samples a slice at a time.
- A plane entry stores a half channel as half floats when every value
round-trips bit for bit (NaN planes and float data stay f32), with a
plain byte-plane shuffle; one entry per channel, read in parallel on a
hit. Old multi-plane entries (format 5) read as misses.
- The planes of one decode go to the disk writer as one job that shares
the plane store's set instead of a copy per channel; the queue counts
their bytes once the store lets go of them.
- The plane store loses its unused level, and one eviction loop serves
the budget and the memory accountant; dropping for bytes keeps
remembered failures.
* Preview: the sound plays on through stalls, the picture drops frames (#2473)
A preview whose rendering fell behind stopped its sound at the first frame
that wasn't cached and started it again once frames were cached, which
chopped it into bursts. Now the sound plays on: the picture shows the latest
frame rendered up to the sound, and the prefetch and the cache's eviction
order follow the sound's frame rather than the picture's.
The stall backoff from #3272 no longer has anything to do and is removed.
The start of a preview still waits for its first frames (#947).
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Preview: a picture behind its sound never shows past the sound's frame
`latest_cached_before` stopped only on the sound's exact frame, which a
picture off the plan's frame step steps over and a sound behind the picture
in a non-looping preview never reaches, so it could return a frame ahead of
the sound. The walk now stops at the first frame that isn't between the
picture and the sound in play order (across the loop's end once the sound
has wrapped). Also brings `Playback::starting`'s doc up to date.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- A region of interest reads rows only at the top level (no collapsed precomps, no nested
comps, no adjustment layers); input and footprint keys never keep a rows-only buffer; a rows
request takes the whole frame from the frame cache when it is there and keeps nothing itself.
- Sequence layers are keyed by their frame (without frame blending or fields), so times within
a frame share the entry.
- A decode taken over by a decode thread runs under the asker's cancel flag and hints.
- Disk planes: one entry per channel, read back whatever was asked for before; queued planes
are moved in (counted exactly), written by channel with checked math; the write refused when
a plane is of another size. Segmentations are compressed on the writer thread.
- Memory accountant: the plane budget is in the sum; the disk queue counts only bytes it alone
holds and never drops frame writes; one balance at a time, inserts balance at most every
100 ms, a refilling holder stays protected for 10 s.
- Reload Footage gives thumbnails new keys; thumbnail keys are worked out at most every 0.25 s.
- Localizer: network footage locations (Settings > Disk, e.g. P:\) besides UNC paths; copies
recorded beside them and adopted after a restart, stale temporaries deleted; the disk cache's
reserve kept free; by default beside the disk cache's folder, 20 GB; a copy gone meanwhile
reads the share; status shown translated, with the network locations.
- Tests: hooks hold the queued decode for the claim test; the disk test uses its own paths.
- A region of interest looks up the whole layer's cached buffer first; only a miss reads the
rows (and keeps nothing).
- The rows margin counts the region's rounding at the layer's own scale; the region test covers
shrunk and enlarged layers at reduced resolution.
- Layer and plane writes are bounded by the bytes they hold while queued (1 GB).
- The disk cache's drop generation is taken before the file is opened, so planes of a file
reloaded meanwhile are refused.
- A plane entry of another shape than the planes asked for is a miss before anything is
decompressed.
- The claim hand-off is one atomic phase (queued, running, claimed): no gap between the claim
and the queued job.
The RAM preview frames register with the memory accountant at the highest priority (what the
user looks at is freed last); GPU frames keep their own budget.
The renderer maps a top-level region of interest back through a 2D footage layer's transform
to the footage rows it shows, grown by the resampling (wider at a reduced scale) and the
effects' declared margins (effects::pixel_margin: 0 for the per-pixel 3D Channel effects). It
reads the whole frame for 3D layers, motion blur, frame blending, fields, layer styles, effects
that don't declare, and comps that read layers' pixels elsewhere (layer parameters,
expressions); a layer read in part isn't layer-cached. FootageSource::frame_rows hands the rows
to the media pool, which keys the frame by them and reads only those rows (1-line chunks:
exactly those lines), for footage whose channels no effect reads. Pixels in the region are
those of a whole-frame read.
Settings > Disk > Localize Network Footage (off by default), with a folder and a size limit:
OpenEXR files on network shares (UNC paths) are copied one at a time on a background thread,
never on the playback path, under a temporary name and renamed when complete. A copy is read
only while its source has the size and modification time it had when copied and the copy is
complete; entries made of it keep naming the share's file and identity. The least recently
used copies go beyond the limit; Settings > Disk shows what the localizer is doing.
* Preview: each stall doubles the frames the held sound waits for (#3260)
A preview that renders just below real time stopped its sound at the first
uncached frame, then started it again as soon as the silent preview kept up
with `ahead` frames cached. Those ran out within a few frames, so the sound
started and stopped over and over, which plays as distortion (#2473, #3260).
Each stall that stops the sound now doubles the cached frames ahead it waits
for before starting again, up to what fits in the RAM preview. A new preview
starts counting from zero.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* Preview: cap the held sound's wait at frames the prefetch can keep cached
Once the doubling reached the RAM preview's `fit`, the held sound waited for
offsets 0..fit, but the prefetch only requests offsets below fit - 1, and
while the silent preview moves on its last requests are still rendering. The
sound then stayed silent almost to the end of the preview even after
rendering recovered.
The backoff now stops at half of the frames the prefetch requests, and never
below the wait before any stall. A new test caches only the frames playback
itself requests, with a RAM preview of `ahead + 2` frames.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
render::memory::Accountant: one budget (the sum of the Memory & CPU budgets) over the holders
that register with it: the footage frames (priority 0), the disk write queue (0), the decoded
footage planes (1) and the layer cache (2). Over the budget it frees lowest priority first,
down to 90% of it; a holder that makes again what it just let go of (the layer cache tells its
refills) is protected while it thrashes. Holders are held weakly and balanced after their own
inserts, with their locks released.
A decode thread asking for planes whose decode is still queued on the decode threads claims it
(the queued job then does nothing), decodes it there and hands the outcome to the request that
queued it: no duplicate decode in the aux-first race, and still no decode thread waits for a
queued job. A decode that already began is copied as before.
A plane kind in the disk cache (planes/): named f32 planes, bit-exact, keyed by the source
file's path and identity, the channel set, the level and the rows; listing their source file,
so a changed file or Reload Footage drops them (the sweep covers planes). The plane store reads
them before decoding and queues what it decoded (encoded on the writer thread, refused when the
disk has no room or the file was dropped since the decode began). The footage source gets the
disk cache with set_disk_cache.
Queued writes carry their pixels (a layer buffer shared with the RAM cache, a frame moved in)
and the writer thread converts and compresses them; rendering threads go on at once. An entry
larger uncompressed than the cache may hold is refused before it is queued.
exr_index::get_opened keeps the file open when indexing opened it; the plane store's decode
reads from that handle (get_opened) instead of opening the file again. Served requests drop it.
Session::thumbnail_key: a comp's content key (as the disk cache keys frames), footage's item and
settings, the time, the size, the render switches and the footage reloads so far. The panel
renders a thumbnail again only when that key changes, not on every revision.
key_any keys an OpenEXR sequence layer (no proxy) by item and source time as it keys stills, so
a processed frame is kept in RAM and on disk; its entries list the frame file they read, so
Reload Footage and a changed file drop them as before.
- A covered batch is served before a remembered failure; failures are kept per request, so a
broken part or too many channels never hides the picture; a picture too large with its
effects' channels is read alone.
- Hostile headers: parts whose data window or uncompressed block is out of bounds are refused
before any decoder sees them (index, reader and the image crate's whole-file path, import).
- Seek and read errors are transient (Stopped), not remembered; the copy path notes its file.
- The index drops the headers' other attributes and previews, is bounded by bytes and checks
the file's identity before it is reused.
- A picture read alone isn't kept twice (plane store and frame cache).
- A waiter whose decodes keep being called off decodes a copy; rounds are bounded.
- The Cryptomatte probe asks with its own effect's need; animated parameters are found in
nested groups.
- Test hooks and caps are keyed by path; new tests: data window offsets, failures per request,
too large with channels, the file bound, hostile data windows, damaged files, rows and levels
on every compression and on tiles.