frame_shape

The shape of the frame the viewport draws, for a suite whose fixture or whose reading depends on it.

The frame is the rect the engine draws the scene into: the headless framebuffer a native engine was started at, the browser window on the web, and whatever the editor's panels leave of either. So a case that works out what to read, or how big to make what it reads, from the frame as it was drawn holds at every shape, and one that wrote either down for one shape reads a different part of the scene at another.

frameHalfExtent sizes a fixture to fill the frame at a distance. frameMatchesSceneRect answers whether the frame was drawn at the scene rect's current shape yet, which is the point to take a reading from after a resize. widenTheSceneRect draws the scene rect at a wide short shape for as long as a case needs it, finding the surface height that gives that shape under whatever editor layout is up, and hands back what puts the surface back.

local FrameShape = require("@builtin::tests.fixtures.frame_shape")

Test.it("the claim holds in a wide short frame", function(t)
    local putBack = FrameShape.widenTheSceneRect()
    Test.waitUntil(function() return FrameShape.frameMatchesSceneRect() end, 240)
    -- … the same claim the case at the engine's own shape makes …
    putBack()
end)

To read a place in the frame rather than fill it, pair this with the frame probe: tests.fixtures.fx_probe turns a world point into the tile of its grid the point is drawn in, from the view the frame was drawn under.