Build a cache over one host-owned loader.
ReadonlyresolveA binding-private texture over the primed source, for buildMaterial.
A bound field rather than a method so it can be handed straight to
buildModel as the resolver itself. An asset that was never primed
throws instead of returning undefined: undefined is the host's honest
"this project ships no such map", and answering it for an asset the
material DOES declare would render a floor with no tile and call that
success.
ReadonlyresolveA material wrapper shared by every equal binding, for buildModel and buildMaterial when one shot builds several models or rebuilds one.
Two object bindings that carry the same fields (asset, coordinate set
and source, colour space, UV transform and sampler) make
resolveAutoMovieMaterialTexture write the same state onto their
wrapper, so they can share it; each distinct binding still receives its
own wrapper, issued once by resolve. A legacy string binding takes
its colour space from the slot it fills, which the binding does not
name, so it always receives a fresh wrapper. Environment scenes need a
wrapper of their own and must keep using resolve.
Read host-decoded upload facts for preflight before the first GPU draw. The source object supplies its dimensions, component width and inherited sampling; material bindings still select their separate resident variants. The texture token names the cache's original object. For environment derivative ownership, call readAutoMovieTextureSource on the actual resolved environment clone instead of substituting this original object. Before any clone is issued the host may prepare its decoded original. After issue, this observation checks every owned wrapper's actual tuple/version; clone-created shared Source.version increments do not invalidate it.
Attempt every distinct issued clone and decoded source exactly once.
In-flight decodes are awaited before release, so a host that tears a shot down mid-load frees what it started rather than leaking whatever landed after the teardown. The loader must settle independently of this release; awaiting cache disposal from inside its own decode would await itself. Concurrent and repeated callers receive the same completion promise. Every public retirement is attempted even when another listener throws. A single failure preserves its original identity; multiple failures retain their original values in attempt order. A failed attempt is not physical release. Detached Source history also rejects completion after every attempt: native disposal looks up the current Source and cannot certify the old footprint. Retain that context's unknown residency until its physical release; neither an empty cache nor a new cache in the same context proves it was retired.
Decode every distinct asset the given bindings name, at most once each.
An asset id that names one of images, the images the binding's model
carries, is decoded from those bytes by decodeAutoMovieImage;
every other id goes to the host loader. One id names one image for the
whole shot: priming it again from different carried bytes, or once carried
and once from the loader, rejects before anything is decoded, because
resolve sees only the id.
Awaiting this is what makes resolve synchronous, which is what lets buildMaterial stay a pure function of a material. A binding whose asset fails to decode rejects here, naming every asset that failed, rather than surfacing later as a silently untextured surface.
One shot's decoded texture assets: loaded once, handed out per binding, and released once.
An original comes from the host's loader, or, for an image a model carries, from that image's own bytes; either way this cache owns it.
Two facts pull in opposite directions and this class is where they meet. buildMaterial writes a binding's color space, UV transform and sampler ONTO the texture object it is given, so two slots that name the same image must not receive the same object: a floor repeating its tile 40 times and a table top repeating the same tile twice would otherwise fight over one
repeat, last writer winning. Decoding that image once instead lets every binding reuse its loaded pixel source without repeating the host's load and decode work for each model.So the asset is decoded once and each binding gets
clone()of it. Athree.jsclone shares its source'sSourceobject while keeping binding state private. Within one WebGL renderer, that source can share a GPU texture when the renderer's texture-state keys match. UV repeat and offset alone do not change that key; different sampler, format, flip or color-space state can allocate and upload separate textures for the same pixels. GPU resources also belong to their renderer, so sharing a decoded source does not promise one upload across bindings, updates or renderers.The cache is per shot rather than per model because a shot is the lifetime a host can actually end: dispose attempts every distinct Texture it owns once and preserves failed retirement, however many times it is called. A cache that has been disposed refuses further work rather than quietly decoding into a bucket nobody will empty. The first issuance fixes the original's inputs before native copy starts and verifies its successful or failed completion. Later observed original or uncontrolled issued-wrapper changes make its facts uncertified, even after properties are restored. Unobserved round trips between checks are not detected. Normal material and exclusive environment owners acknowledge their own supported transitions.
A different live cache cannot acquire this cache's original or issued wrapper; distinct wrappers may still share decoded pixels. A detached Source can leave an earlier native upload alive after public disposal and therefore makes completion indeterminate. An issued binding wrapper cannot return through the loader as a decoder original, including an alias inside this same cache.