fix(highway_3d): fit backdrops to projected view

[saleemk]

What

Fix Highway 3D backdrops so they cover the complete projected camera view when projection zoom or view offsets are active.

The previous backdrop fit used the camera field of view and aspect ratio while keeping the backdrop centered. This could expose the finite edges of Venue and other full-screen backdrop planes when the projected view moved away from the default center.

This change:

• derives the visible backdrop bounds through PerspectiveCamera.getViewBounds()
• positions the backdrop at the projected view center
• keeps the backdrop parallel to the camera
• resizes when the projected width or height changes
• reapplies cover-cropping only when the projected aspect changes
• reuses scratch objects to avoid per-frame allocations

The shared correction covers Venue plates, crowd videos, custom images, and custom videos. Stock framing remains unchanged when projection zoom and view offsets are not used.

This complements #1043, which exposes projection controls through the Highway 3D camera bridge. This PR is based directly on main and can be reviewed independently.

feedpak surface

• This PR does not change how the app reads/writes feedpaks (manifest keys, pack files, folder layout)
• This PR changes the feedpak surface, with the specification change landing first through the FEP process

Testing

Automated:

• node --check plugins/highway_3d/screen.js
• node --test tests/js/venue_scene_3d.test.js
• node --test tests/js/*.test.js
• Focused Venue tests: 24 passed
• Full JavaScript suite: 1,134 passed

Manual:

• tested with the camera bridge from feat(highway_3d): extend the camera bridge for touch controls #1043
• phone portrait and landscape
• tablet portrait and landscape
• Venue backdrop during pinch zoom and two-finger pan
• reset view and orientation transitions
• stock Highway 3D behavior

Checklist

• CHANGELOG.md [Unreleased] updated
• Tests added/updated for new behaviour
• Commits are DCO signed off (git commit -s)

Summary by CodeRabbit

• Bug Fixes

  • Improved 3D highway backdrop fitting to better match the camera’s visible perspective.
  • Enhanced texture cover-cropping across different screen shapes and viewing angles.
  • Improved backdrop centering and orientation during camera changes and video texture swaps.

• Tests

  • Added coverage to verify projection-based backdrop sizing, cropping, positioning, and orientation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ff8daa37-b310-4cf0-a605-af7692ceb02b

📥 Commits

Reviewing files that changed from the base of the PR and between eef58c8 and 13bdda2.

📒 Files selected for processing (2)

• plugins/highway_3d/screen.js
• tests/js/venue_scene_3d.test.js

---

📝 Walkthrough

Walkthrough

Changes

Backdrop fitting

Layer / File(s)	Summary
Projected view fitting plugins/highway_3d/screen.js	Backdrop sizing now uses cam.getViewBounds(...), caches visible dimensions/aspect, applies visible-aspect cropping, and aligns the plane using camera-local transforms.
Cover-crop state propagation plugins/highway_3d/screen.js	Backdrop states accept visible-aspect inputs, track visible dimensions, provide aspect fallbacks, and reset aspect state during video swaps.
Projected fitting regression coverage tests/js/venue_scene_3d.test.js	Adds source-level assertions for view-bounds sizing, camera alignment, cover-cropping, and removal of FOV/lookAt-based logic.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Camera
  participant BackdropFit
  participant BackdropState
  Camera->>BackdropFit: getViewBounds(distance)
  BackdropFit->>BackdropState: cache visible dimensions and aspect
  BackdropFit->>BackdropState: applyCoverCrop(visibleAspect)
  Camera->>BackdropFit: localToWorld and getWorldQuaternion
  BackdropFit->>BackdropState: update plane position and orientation

Loading

Possibly related PRs

• got-feedBack/feedBack#905: Modifies the same highway 3D backdrop fitting and cover-cropping machinery.

Suggested reviewers: byrongamatos, chrisbewithyou

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: fitting Highway 3D backdrops to the projected camera view.
Description check	✅ Passed	The description covers What, feedpak surface, testing, and checklist items, with only the changelog box left unchecked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}