cinema

The cinema slice of FIRE FOR EFFECT: light, lens, timeline and sound. It is one of the four modules ffe.film drives, and it owns the four entities the scene build places for it — Sun, Sky, FilmCamera and FilmListener — which it finds by name and never respawns.

Everything it does is a pure function of the film time the director hands in. Nothing reads wall time, os.clock or engine time, which is the whole of the determinism argument: run the film twice, get the same film.

Exports

• M.build(root) — re-entrant. Establishes the light rig, the atmosphere, the grade chain and the sound emitters, all parented under root.
• M.tick(t, dt) — one rendered frame at FILM time t. Places the camera and the listener, then drives look, grade and sound.
• M.reset() — called when the film rewinds.
• M.report(t) — everything the slice is doing at film second t, as data: the eye, the aim, the lens, the light, the grade and the sound.
• M.audit(step?) — walk the film without running it and report the camera, the shot and the listener's offset from the eye at every step.

What it is made of

Usage

local Film = require("ffe.film")
local Cinema = require("ffe.cinema")

Film.seek(58)          -- park frame-exact on shot 10
Film.drive()           -- one frame at that time
Cinema.report(58)      -- what the camera, the light and the mix are doing

require("ffe.cinema.check").all()   -- the whole slice's proof, as PASS/FAIL lines

Notes

• The lens is authored once. A set-up states a vertical fov; the focal length the depth of field is built from comes out of it against a 24 mm sensor (Shots.focalLength). Nothing states millimetres.
• Shot 16 IS shot 1 — the same table, shared by reference. Check.arc() asserts it with rawequal as well as by evaluating both stations, because a copy would drift the first time somebody nudged one of them.
• The ear rides the lens, position and facing both. A listener carried to the right point with the wrong facing puts a gun that is on the left of the frame on the right of the mix.
• Nothing here goes through the lighting toolbox. Its setSun / setAmbient fault on a scene holding a DirectionalLight component (#10510), and they spawn scene-durable light entities outside FilmRoot. Every light in this film is a component this slice writes directly, on an entity it owns.
• The clock is shared. Four agents drive the one ffe.film clock in this world, so a Film.seek you made can be moved by somebody else between two calls. Read Film.time() back before trusting a capture.