enum ImageStore

Bytes of decoded image the cache will hold before evicting. Generous by default: a screenful of covers is a few MB, and evicting sooner than necessary just means decoding again.

Bytes currently held, for tests and diagnostics.

Cache identity for bytes with no path: a hash of the content, so the same image registered twice is one texture and the caller invents no name.

Public for the same reason as key, and for one more: the compositor derives this key independently, from the bytes it received, and a client that spelled it differently would be talking about a different texture. One implementation, both sides.

FNV-1a with the length mixed in. A collision means two unrelated images share a texture, which is worth caring about — and takes roughly 2³² distinct images in one session to become likely, which is why 64 bits is enough here and would not be for an untrusted store.

Called by LavaApp.run once a frame has been emitted.

Evicting after emit rather than before is what makes "not drawn this frame" mean anything: at the start of a frame nothing has been drawn yet, so every entry would look idle and the cache would throw away the images it is about to paint. Running it here also means a cache that is over budget with nothing new arriving still drains — eviction on insert alone stops the moment loading does, and leaves the cache permanently over its limit.

Cached image, or nil while it loads.

Returns nil the first time and decodes on a worker; when the pixels arrive they are uploaded on the main thread and a redraw is requested, so the next frame gets the image. Callers draw a placeholder for the nil case — which they need anyway, because a real client is waiting on the network too.

maxPixelSize caps the longer edge at decode time (0 = native). Pass the size it will be drawn at. Two reasons, and the second is the one that bites: the pixels you don't decode cost nothing to hold, and ImageAtlas refuses anything wider than one cell, so an oversized decode silently costs a whole texture binding per image.

Whether a decode for this file is running right now.

The one thing imageIfLoaded's nil does not distinguish: still on its way, or asked for and come back empty. A caller that keeps the previous picture on screen while the next one decodes has to tell those apart, or a file that will never arrive leaves a stale frame up for ever. Ask before calling imageIfLoaded — that call starts a new decode, after which the answer is trivially yes.

Cache identity for a file decoded at a given cap and turn. 0 and .none add no segment, so existing callers keep their key and two callers that both want a picture the right way up share one texture.

Public because a GPUResourceHost outside this module has to stamp the same key into the UIImage it returns — this cache looks entries up by it, so a host that spelled it differently would register an image and then miss it on every subsequent frame.

Cached image, loaded synchronously. Kept for assets an app needs before its first frame — an icon, a brand mark — where a placeholder would be worse than a stall.

Resolve a file under assetsRoot (fonts/ / assets/ / root).

Load a resource from a SwiftPM / app Bundle (prefer the app's Bundle.module for brand art — not the engine or LavaUI bundles).

Hands every cached image back to the host and empties the cache.

Called on the way out of LavaApp.run, and that is not tidiness. A texture the renderer holds for a client is not freed when the client's process ends: under a compositor the registration counts a user, and there is nothing on the wire tying that user to the process that asked — ReleaseImage says so itself. So an app that exits with a full cache leaves every image it ever opened resident for as long as the desktop lives. A photograph viewer walking a library measured 2 GiB of that, with no viewer running.

It does not close the hole, only the common half of it: an exit through the frame loop reaches here, a crash or a kill does not. The other half belongs on the compositor's side of the wire, where a registration should be leased to the session that made it.

Marks an image as used. Called from the draw list on every emit, which is what makes "least recently used" mean "least recently drawn" rather than least recently asked for.