docs: Architecture, QuickStart, ADRs; correct stale dual-path docs#3
Merged
Conversation
- Add Docs/DisplayXR/Architecture.md (class hierarchy, ownership,
per-frame data flow, module map)
- Add Docs/DisplayXR/QuickStart.md (install runtime → install plugin →
press Play in ~10 min)
- Add Docs/DisplayXR/adr/ with three ADRs:
* ADR-001 Direct OpenXR runtime loading (no UE OpenXR plugin)
* ADR-002 Zero-copy atlas handoff via single D3D12 device
* ADR-003 UE-native off-axis projection over Kooima projection_matrix
Correct stale docs that described a dual-path architecture that never
existed in code:
- CLAUDE.md: "Dual-Path OpenXR Integration" → unified session
- README.md (top-level): drop "two code paths at compile time"
- Docs/DisplayXR/README.md: drop Platform Architecture dual-path table
- Docs/DisplayXR/MacSetup.md: rewrite — no FDisplayXRDirectSession,
no FDisplayXRSceneViewExtension, no DISPLAYXR_USE_UNREAL_OPENXR;
explains Mac-specific quirks (active runtime manifest, no UE
OpenXR plugin on Mac) instead of inventing a separate architecture
- Docs/DisplayXR/TODO.md: drop DISPLAYXR_USE_UNREAL_OPENXR reference
from the macOS validation bullet
Verified DISPLAYXR_USE_UNREAL_OPENXR appears nowhere in source code
or Build.cs — it was a phantom flag only referenced in docs. Platform
selection is #if PLATFORM_WINDOWS / PLATFORM_MAC / PLATFORM_LINUX
inside FDisplayXRSession and FDisplayXRCompositor.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tackles the four doc items flagged in the "adequacy for devs/agents" review:
Corrected stale docs
Several docs described a dual-path architecture (`IOpenXRExtensionPlugin` on Win/Android vs `FDisplayXRDirectSession` on Mac, toggled by `DISPLAYXR_USE_UNREAL_OPENXR`) that never existed in code. The actual architecture is one unified `FDisplayXRSession` that loads the DisplayXR OpenXR runtime directly on every platform. Fixes:
Files
Added
Modified
Test plan
Verification note on the phantom flag
```
$ grep -rniI --exclude-dir=.git "DISPLAYXR_USE_UNREAL_OPENXR" .
Only matches are in docs (now corrected); zero matches in Source/
```
`FDisplayXRSession.h` comment explicitly states: "Replaces both FDisplayXRExtensionPlugin (Windows/Android OpenXR hook path) and FDisplayXRDirectSession (Mac direct path) with a single unified session." That comment is the ground truth; the stale docs missed the memo.