I guess in this instance you are referring to "local space" since its relative to its parent (the pass). You should probably add a docstring for Entity::SetTransformation too.

Added a docstring to [Set|Get]Transformation.

All Entity and layer transforms are recorded as global -- this offsetting behavior is kind of a hack to get things aligned due to coverage optimizations (conceptually, all layers cover the entire screen; if we weren't using coverage to compute minimal subpass texture sizes, we wouldn't need to perform this offsetting at render time). And so at render time the Entity transform isn't relative to the user-controlled parent layer transform as "local space" implies, we just slide it over a bit just-in-time to align with coverage rectangle we computed for the current pass on the fly.

One potentially cool way we could slide this offset in without performing this confusing "slide the Entity around on the screen just before rendering" would be to adjust the viewport, but that's an exploration for another day. :p

One potentially cool way we could slide this offset in without performing this confusing "slide the Entity around on the screen just before rendering" would be to adjust the viewport, but that's an exploration for another day. :p

Yea, that is sort of tripping me up. Instead of mutating an entities transform I'd prefer a way to crawl up and down the layers and build the necessary transform. For rendering to the subpass's texture we'd use the local transform, for doing coverage tests we'd calculate the global transform, etc. There's no need to mutate.

Yea, that is sort of tripping me up. Instead of mutating an entities transform I'd prefer a way to crawl up and down the layers and build the necessary transform.

Conceptually, this Entity transform mutation we're doing isn't moving the Entity to the correct scene position -- the Entity already has the correct global transform in the scene as defined by the user. What we're actually doing is aligning the orthographic camera based on where the minimal layer texture is going to be drawn.

If we wanted to avoid mutating the Entity transform, we could for example add a camera concept, or pass the offset as an extra param to Entity::Render() and let the Contents choose how to handle it during Command construction. But FWIW, I actually think what we're doing today is... pretty OK, barring better documentation.

If we wanted to avoid mutating the Entity transform, we could for example add a camera concept,

Yea, I like that idea. It's a more clear concept, involves less mutating, easier math, has more opportunities to bake since the geometry will be static.