feat(stereo-camera): vendor-neutral UVC side-by-side stereo source (Windows MF; V4L2 stub)

[dfattal]

What

ADR-043 Amendment 4: a vendor-neutral, service-owned stereo camera source for plain UVC side-by-side stereo webcams. Today every stereo camera comes from a display plug-in. With this, any display plus any SBS UVC stereo webcam works through XR_DXR_stereo_camera, with no vendor plug-in, the same consent and privacy model, and the same rectified output.

• auxiliary/util/u_stereo_uvc.{h,c} (pure, tested on every OS):
  • Opt-in config. Nothing is claimed without the per-user stereo-cameras.json (%LOCALAPPDATA%\DisplayXR\, $XDG_CONFIG_HOME/displayxr/). DXR_STEREO_CAMERA_UVC_CONFIG overrides the path and DXR_STEREO_CAMERA_UVC=0 turns the source off.
  • Each entry matches by VID:PID and/or a friendly-name substring, and sets the layout (sbs-full | sbs-half), eye order, mode, eye size, nominal baseline and HFOV, plus an optional OpenCV calibration file (YAML or JSON).
  • Device assignment: one device per entry, and a name-only entry that matches several devices claims none.
  • A device that a plug-in reports as its platform_device_hint is never claimed. The Leia plug-in reports its tracker as "vvvv:pppp", and this form is covered by a test.
  • The SBS split resamples each half to a square-pixel eye (integer box reduction, then bilinear; NV12 or YUY2 in, NV12 out). Half-SBS uses an exact 2-row average. The default eye size is capped at 1280 px wide.
  • The nominal pinhole model, the calibration-file parser, and a fake backend.
  • Built-in allowlist: none. I could not cite a public SBS spec for any device.
• auxiliary/os/os_uvc_capture*: the Media Foundation backend.
  • MFEnumDeviceSources only lists devices; nothing is activated.
  • The mode list creates the device source but never starts it.
  • Capture uses an async IMFSourceReader with advanced video processing, so the system MJPEG decoder MFT does the decoding. The newest sample wins.
  • V4L2 is a stub with the plan written down. The backend is its own library (aux_os_uvc) and is linked only into the service and displayxr-cli, never the runtime DLL.
• Camera manager:
  • Each camera carries a source tag, and a single src_* dispatch picks the source. Consent, CAMERA_CONSUMER rules, the foreground rule, the in-use indicator, linger, rings, the rectifier and the refinement are one code path for both sources.
  • Plug-in cameras are enumerated first.
  • An uncalibrated UVC pair is reported without CALIBRATED, and its RAW calibration is refused. RECTIFIED is a pass-through (no remap, no zoom, nominal numbers) until the online vertical refinement applies a correction. After that it uses the normal corrected LUT path and the calibration generation moves.
  • A calibration file makes the camera CALIBRATED, and the R2 rectifier runs as usual.
  • Adds a create_ex() test seam.
  • Fixes a latent bug: cam->index now always equals the camera's slot. Before, it was the plug-in index, which went wrong after a skipped malformed camera.
• CLI:
  • camera list shows (source: plugin|uvc), and "source" in --json. The JSON now escapes backslashes in the hint.
  • New camera uvc-devices [--modes] runs locally with no service. It shows the config and the devices present, and which entry claims which device (or that an entry is ambiguous). --modes lists modes for claimed devices only.
• Wire: xrt_stereo_camera_properties.reserved becomes source (same size). The OpenXR struct and the spec version are unchanged.

Docs

• ADR-043 Amendment 4.
• Spec: new §9a, plus the rule changes in §2–§5, §8, §11 and §13. RECTIFIED now requires a camera the service can rectify, not CALIBRATED | NATIVELY_RECTIFIED.
• Roadmap: row U1.
• Env-var census: two new vars.
• index.json summary updated; gen_extensions_index.py --check passes.

Tests (Windows, local)

• tests_stereo_uvc: 12 cases, 402 assertions. Covers config parsing and errors, VID:PID parsing, matching, the assignment and ambiguity rules, plug-in exclusion, eye-size math, the nominal model, calibration files, the split (lr/rl, full/half, NV12/YUY2), and the fake source end to end (disparity 25.60 px, dy +2.40 px recovered). Closed loop: dy +2.398 → +0.004 px.
• tests_stereo_camera_manager: the real manager, driven through its IPC handlers on the fake backend with an in-memory consent store. No MF, no device, no service, so it runs on CI. Checks enumerate and calibration semantics, and a RECTIFIED stream through consent and the read-only ring with refinement APPLIED, generation 0 → 1, delivered dy +2.40 → +0.004 px. A RAW stream stays RAW.
• Full ctest: 91/91. build_windows.bat build is warning-clean apart from the known C4090 in oxr_session.c.
• MinGW cross-compile was not run because it isn't installed on this box. macOS and Linux compile coverage comes from PR CI.

Not done / follow-ups

• Hardware test with a real SBS webcam (owner run; recipe in the session report).
• V4L2 backend.
• MJPEG decode at 4K60 in software is heavy. A D3D11 device manager for hardware MJPEG decode, or choosing a smaller mode, is the next lever.
• GPU rectifier (already a TODO in R2).

🤖 Generated with Claude Code

[dfattal]

Hardware check (SR laptop + SpatialLabs Eyes 0733:011a, 2026-10-08): no config → claims nothing, tracker 04f2:b70c 'never touched'. With config (sbs-half, lr, 3840x2160@60): CLAIMED, camera list shows it as source: uvc 1280x720/eye; probe delivers a real stereo pair (2560x720, eye order correct: +35 px disparity at ~1.5 m). Findings: (1) 11.3 Hz delivered, ~93 ms latency — software MJPEG decode of 4K60 is the bottleneck; needs the D3D11/DXVA hardware decoder path before this is usable for calls (the camera only offers 3840x2160). (2) --rectified gate FAIL by a margin (+1.18 px vs 0.5) after 8 s at 11 Hz; refinement converging (+1.77 → +0.09 px window). Functional, but HW decode should land before merge.