[tychedelia]

There were some weirdness with how lights previously worked:

• We were spawning retained lights into the world without any boundaries around which graphics they applied to or when.
• We had no way to do immediate mode lighting (see p5 spotLight and friends for example).
• We had no ways to despawn lights or have a light handle.

The solution is to add the immediate mode methods as well as a light draw method that uses the light for a given frame. We keep track of these "frame lights" and create them as needed for a given flush. This is important because we need to be aware of when the transform changes, or when there are multiple flushes in a single frame. In other words, the light the user creates is more like a light descriptor and they can create as many light instances they want by calling light, weaving transform changes in between if they so choose.

Also cleans up some life cycles. We now have DrawTransient and FlushTransient which exist at different boundaries. So geometries get cleaned up inside a flush boundary but lights stick around for the entire draw frame.

Most of the changes in this diff are in the examples and can be ignored.

[github-actions]

Visual regression: 2 changed of 43 cases

case	status	detail
py_flocking_gpu	❌ changed	5.79% of pixels differ
py_gltf_load	❌ changed	10.75% of pixels differ

If these changes are intentional, add the deliberate-rendering-change label.

_{baseline 3497b83eff · adapter llvmpipe (LLVM 20.1.2, 256 bits) (Vulkan, Mesa 25.2.8-0ubuntu0.24.04.4 (LLVM 20.1.2))}

Open the visual report · workflow run