The problem
Several UI systems needed many frames stored in one texture: status indicators, hand poses, animated icons, and other image sequences.
Without a shared concept, every consumer calculates row and column offsets, creates one texture resource per tile, tracks the current frame, wraps at the ends, updates the element, and gets the direction cases slightly wrong.
That arithmetic is not difficult. Repeating its rules in every consumer is how small bugs become a family tradition.
The reduction
The useful domain question is:
Which frame is next, where is it in the atlas, and how do I display it?
H3's ImageAtlas gives that question a vocabulary: getCoordinates, getNextFrame, spawn, cycleFrame, and getElement. The ImageAtlas reference describes the runtime and allocation contract.
The H4ND implementation became the first real consumer immediately after the abstraction was introduced. bf230995 added ImageAtlas to H3, and 224d20c shows the first H4ND consumer. The H3 ImageAtlas reference documents the durable API.
Give repeated rules a home
The atlas owns the rules that belong to an atlas:
- frames are one-based;
- coordinates advance across rows;
- forward and backward movement wrap;
- construction creates the tile resources;
- cycling changes an existing element rather than rebuilding the UI.
The consumer owns the meaning of the frame: health, fatigue, compass direction, hand pose, or something else. That division is why the object is useful without becoming a UI framework.
Reality corrects the edges
The first abstraction was not perfect. Later history repaired the contract where actual use found gaps:
494ebdc4fixed the false/backward case.
Later commits 51cfc16c and 8fa3d40a added the dedicated next-frame operation and fixed the current-tile update. The current source preserves that resulting behavior in getNextFrame and cycleFrame.
This is not evidence that the abstraction was a mistake. It is evidence that a useful boundary gives bugs one place to be fixed.
What to steal
When a representation has recurring rules, give the representation a domain vocabulary. Do not scatter frame arithmetic through every caller.
But do not turn every four-line calculation into a class. The repeated domain concept, shared ownership, and real consumer pressure are what justify ImageAtlas.
See H3UI for the higher-level UI layer and Allocation and GC for the difference between constructing an atlas once and rebuilding it in a frame loop.
When not to use this
If one caller performs four lines of frame arithmetic once, it does not have a reusable atlas boundary yet. Use an ordinary texture and local code until repeated frames, wrapping rules, or shared ownership justify the domain object.