refactor(gst): decide video input adapters in one place, and write down the block contract

[srperens]

Description

This PR puts the video input adapter decisions in one place and writes the block contract down as rules. It is Option D from #682, and it follows #948 and #949.

decide(): one place for the adapter rules

Three mechanisms each worked out on their own what a video input needs in front of it. They now all ask gst::video_adapt::decide(), and each keeps its own timing:

Call site	When it decides
video_input_bridge (WHEP Output)	on the first CAPS event
gl_link (the linker)	when a link is refused
gl_input_front (Vision Mixer GPU inputs)	on a query, with the splice done while the pad is idle

The rules, also given in the module doc:

Consumer	Producer caps	Adapters
GlUpload	raw video in CUDA memory only	CudaDownload, or MissingFactory when cudadownload is not installed
GlUpload	anything else	none
Accepts(consumer caps)	raw video in GL memory only, and the consumer takes system-memory raw video	GlDownload

WHEP Output is treated as a consumer whose caps are corrected, not as a rule of its own. whepserversink advertises video/x-raw(memory:GLMemory) but cannot encode it. The bridge therefore passes the caps the sink can actually take (system-memory raw video), and the download follows from the same rule the linker uses. The NV12 conversion stays a separate, WHEP-only step in the bridge. It saves converting once per viewer and is not a caps adaptation, so it is outside the table.

No behaviour change. The rules moved word for word, and every existing guard passes without edits. Two timing details differ, and neither changes the outcome:

• The linker now always queries the sink's caps after a refused link.
• The cudadownload registry lookup happens just before the lock instead of under it.

Compositor deprecated (text only)

The block's name is now "Video Compositor (deprecated)", and its description starts with "Deprecated: no longer maintained; use the Vision Mixer." Its id, properties and behaviour are unchanged. The Vision Mixer is the maintained mixer, so the compositor does not get the new input fronts.

Block guidelines

• New file docs/BLOCK_GUIDELINES.md, which holds the block rules:
  • Block Input Contract (new): a block emits what it naturally produces, and each consumer adapts its own input. This covers encoded vs raw, memory type, pixel format, resolution and framerate, and audio rate, format and channels. A consumer that cannot adapt fails the flow with an element error that says why. A guard test feeds the consumer something other than its preferred input.
  • GStreamer Memory Formats, with a new rule: avoid autovideoconvert and other auto-pluggers that choose by rank, and extend decide() instead. Behind gldownload on GStreamer 1.24.2, autovideoconvert failed 9 of 20 runs. See perf(whep): convert a video input once, not once per viewer #949.
  • Output Block Inputs, moved unchanged.
• CLAUDE.md imports the file (@docs/BLOCK_GUIDELINES.md), so agents read the same text as before.
• docs/CONTRIBUTING.md points human contributors to it.

Part of #682.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactor (no behaviour change)

Testing

Ran locally (macOS), rebased on main after #949 and #950:

• cargo test --lib: 693 passed, 4 ignored.
• Integration tests, all passing and unedited by this PR:
  • gl_memory_link_test (7)
  • vision_mixer_cuda_input_test (2)
  • vision_mixer_cuda_missing_test (1)
  • video_input_bridge_gl_test (1)
  • whip_whep_ice_transport_policy_test (9)
  • pipeline_lifecycle_test (3)
  • vision_mixer_fx_test (2)
  • vision_mixer_cpu_test (7)
• cargo clippy --all-targets -- -D warnings and cargo fmt are clean.

Revert checks (each temporary, then restored):

• Breaking the cudadownload availability rule, the Accepts consumer check, the CUDA-only rule and the GL-download rule in turn failed 7 tests each time. Among them were the new decide() tests and the bridge's real pipeline tests.
• Making the WHEP bridge pass the advertised GL caps instead of the corrected ones failed gl_nv12_is_only_downloaded, gl_rgba_is_downloaded_then_converted and video_input_bridge_gl_test.

Not run: the full cargo test --workspace.

Known, not changed (it would be a behaviour change, so it is left for a follow-up): the GL input front's CUDA-only check counts a video/x-raw(ANY) offer as CUDA-only, while the GL rule excludes ANY.

🤖 Generated with Claude Code