feat(effects): the recording's surface in the effect contract

[EtienneLescot]

Summary

An effect can now work on the recording's own surface, not only in output uv. Under the 3D camera, a wave computed in output uv draws circles on the picture while the recording is tilted under it. The context only gave the recording's bounding box, so no effect could follow the plane.

What the contract gains

• fx_to_footage(uv): the point of the recording's surface under a pixel, (0,0) at its top-left and (1,1) at its bottom-right, extended past its edges. Far outside 0..1 where no point of the surface lands.
• fx_from_footage(p): the way back, to sample frame().
• ctx.footage_aspect: the recording's width over height, for round distances on it.
• ctx.footage_corners and ctx.footage_warp, which the two functions read.

Same warp as the drawing. The functions are the WGSL mirror of quad_inverse / quad_forward in shaders.hlsl: bilinear under a fixed angle, the corners' homography under the real camera. The corners come from FrameGeometry::footage_quad, already shared by the backends.

Agnostic. The contract offers the two spaces and decides nothing. The resource, the tool description and the spec say what each space is; the effect picks. The ripple example of the MCP resource now uses the surface, as an example of use.

The fields are appended to FxContext (192 bytes), so contract 1 keeps its meaning.

For #1206 (macOS). Its FxFrameInputs needs the same two lines as Windows and Linux: footage: g.footage_quad(..) and footage_aspect: g.footage_aspect(..).

Related issue

None.

Type of change

• Feature
• Documentation

Release impact

• No release note needed: the shader effects have no UI yet

Desktop impact

• Windows
• Linux
• macOS: needs the two lines above in feat(compositor): the macOS shader effects pass (Metal) #1206

Screenshots / video

A water drop computed on the surface, under the orbit camera, exported through openscreen mcp. The video is in the session, not attached here.

Testing

• New Windows GPU test the_footage_plane_maps_back_to_what_the_compositor_drew: flat, fixed left angle (bilinear) and orbit (homography), at 1080p. It is checked against two mutants: one that breaks the bilinear inverse and one that forces bilinear under the camera. Both fail it.
• cargo test -p openscreen-compositor --lib -- shader_fx footage_plane: 21 passed.
• npx vitest --run electron/mcp/effects-contract.test.ts electron/ai-edition: 438 passed.
• npx tsc --noEmit, Biome on the touched files.
• The Linux side is a two-line change, not compiled here: CI builds it.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: f5ec70ee-5b47-4433-98b2-c3c1a6ee301f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[EtienneLescot]

Integrated into integration/shader-effects as 9d57ca1: the same change, cherry-picked on top of the Linux pass. It reaches main through #1210 (row 4).