Skip to content

README.md

Latest commit

 

History

History
239 lines (195 loc) · 23.9 KB

README.md

File metadata and controls

239 lines (195 loc) · 23.9 KB
Raw

DisplayXR Documentation

New to the project? Read ORIENTATION.md first — a top-down, plain-language tour of what DisplayXR is, why it's built this way, and where every doc lives. This page below is the role-based jump table.

Who are you?

App developer OXR contributor DXR core contributor Vendor contributor
Building apps that target DisplayXR Working on the OpenXR state tracker / extensions Working on compositors, IPC, shell contracts, build Integrating a 3D-display vendor (driver + DP)
→ getting-started/ → architecture/ → architecture/ → guides/vendor-plugin-onboarding.md
→ specs/extensions/ → specs/extensions/ → specs/runtime/ → specs/vendor/
→ reference/ → guides/implementing-extension.md → adr/, roadmap/ → vendors/ (your vendor's subfolder)
→ adr/ → adr/ (003, 007, 015)

For App Developers

Build apps for 3D displays using the OpenXR standard.

  • Getting Started — what is DisplayXR, architecture, sim_display
  • Building — build instructions for Windows, macOS, and Linux
  • Android Build Guide — Lume Pad-class hardware: vendor SDK setup, Gradle, install
  • Android Bring-Up Checklist — A→B→C→D step-by-step test plan for first hardware install
  • App Classes — handle, texture, hosted, IPC — which one to use
  • Your First Handle App — tutorial walkthrough
  • Ship a Manifest — make your app discoverable on every workspace controller, OEM shell, and showcase in the ecosystem with a 30-second JSON file + optional 3D logo
  • Troubleshooting — symptom → cause → fix for the field-confirmed pitfalls (app hangs at startup / VPN Winsock LSP, "Failed to initialize OpenXR", Vulkan crashes, eye-tracking/camera, wrong runtime loads); start with displayxr-cli selftest
  • FAQ — conceptual questions: what DisplayXR is, supported displays/OSes/graphics APIs, do I need hardware to develop, multiview vs stereo, engines, license, relation to Monado

Extension Specs

For OXR / DXR Core Contributors

Contribute to the DisplayXR runtime — compositors, state tracker, auxiliary code.

Internal Specs (specs/runtime/)

For Display Vendors

Integrate your 3D display hardware into DisplayXR.

Integrated vendors (vendors/)

Architecture Decision Records

Index below is generated by scripts/gen_adr_index.py (CI-checked). Add an ADR file, re-run the script. Full standalone index: adr/README.md.

  • ADR-001 — Native Compositors Per Graphics API
  • ADR-002 — IPC Layer Preserved for Multi-App
  • ADR-003 — Vendor Abstraction via Display Processor Vtable
  • ADR-004 — D3D11 Native Over Vulkan Multi-Compositor
  • ADR-005 — Multiview Atlas Layout
  • ADR-006 — Legacy App Compromise View Scale
  • ADR-007 — Compositor Never Weaves
  • ADR-008 — Display as Spatial Entity
  • ADR-009 — Upstream Cherry-Pick Strategy
  • ADR-010 — Shared App IOSurface Worst-Case Sized
  • ADR-011 — D3D11 Swapchain Textures Must Use TYPELESS Format
  • ADR-012 — Window-Relative Kooima Projection
  • ADR-013 — Universal App Launch Model (Hidden HWND Proxy)
  • ADR-014 — Shell Owns Rendering Mode Control
  • ADR-015 — DisplayXR Owns Multi-Display Vendor Routing
  • ADR-016 — Workspace Controllers Own Their Tray Surface and Lifecycle
  • ADR-017 — Tiered strategy for Win32 modal dialogs under the workspace shell
  • ADR-018 — Workspace Hit-Test Is Plumbing; Drag/Resize/Cursor Policy Is the Controller's
  • ADR-019 — Aux Library Boundary for Vendor Plug-in DLLs
  • ADR-020 — Plug-in ABI Compatibility Policy (versioning, struct_size negotiation, drift guards)
  • ADR-021 — Color Management & the Encoding-State Invariant
  • ADR-022 — Per-Mode Capability Flags + Frozen Enumerated App Structs
  • ADR-023 — Unified Atlas Capture (XR_DXR_atlas_capture)
  • ADR-024 — Raw vs Render-Ready Views (XR_DXR_view_rig)
  • ADR-025 — Android Vendor Display Processors Run Out-of-Process
  • ADR-026 — Orientation-Independent Rendering Modes, Config-Derived View Scale, Rotation-Aware Worst-Case Atlas
  • ADR-027 — Display Zones — decoupled mixed 2D/3D layout, per-zone rig, wish mask
  • ADR-028 — The rendering mode is the content recipe; the hardware state is an orthogonal override
  • ADR-029 — The IPC client owns the transparent present; the DP reconstructs alpha, never bakes a background
  • ADR-030 — Compositor Crops to Content; Zero-Copy Only When the Swapchain Equals the Mode Atlas
  • ADR-031 — Remove the 2D-surround / output-rect mechanism — display-zones is the sole region paradigm
  • ADR-032 — Array (Layered) Swapchains Are First-Class Alongside the Tiled Atlas
  • ADR-033 — The Party That Owns Placement Reports Geometry; the Weaver Owns Everything Phase
  • ADR-034 — Input Providers Are a Second Plug-in Type, Not a Display-Processor Extension
  • ADR-035 — The Service Owns Arbitration, Runs One Compositor Pipeline, and Isolates Its Satellites
  • ADR-036 — Android: per-window compositor instances; the workspace overlay is an optional mode
  • ADR-037 — Adapter placement policy on hybrid-GPU devices
  • ADR-038 — On Android the Vendor Plug-in Ships Inside the Runtime APK
  • ADR-039 — One fill engine for every tier (same-adapter split)
  • ADR-040 — Rear depth budget — the runtime owns the policy, the plug-in owns pixels, the app owns geometry
  • ADR-041 — Fixed view count with per-frame activity — inactive views alias, they do not disappear
  • ADR-042 — A vendor 2D→3D conversion module supersedes the open default — the runtime exposes it, weaving stays the DP's
  • ADR-043 — A display's stereo camera is a plug-in-provided source, owned by the service and privacy-gated by the runtime
  • ADR-044 — The colour contract, per backend and swapchain format
  • ADR-045 — Plug-ins are always loadable and report their platform state
  • ADR-046 — Depth-aware cursor — opt-in only; the app knows the depth, the runtime places the cursor
  • ADR-047 — Multi-screen — segments and per-screen views

Roadmap

Design docs, status trackers, and plans — some shipped, some in progress. After the 2026-05-13 cleanup, this folder holds only living docs (PRDs, in-progress plans, current contracts) — historical agent prompts and shipped-phase status snapshots are recoverable from git history.

Shipped

Planned / In Progress

Reference

Cross-cutting references that don't belong to a single audience.

  • Conventions — code style and naming conventions
  • Understanding Targets — build target structure
  • Windows Build — Windows build instructions
  • Qwerty Device — keyboard/mouse simulated controller
  • Window Drag Rendering — rendering during window drag
  • Debug Logging — log level conventions
  • View-Configuration Model — PRIMARY_STEREO vs PRIMARY_MULTIVIEW_DXR: which view configuration an app begins, what each reports at xrEnumerateViewConfigurationViews / xrLocateViews / xrEndFrame, the under-submit contract, CTS status and the DXR_VIEW_CONFIG_LEGACY kill switch (#1486 / #80)
  • CTS interactive procedure — operator runbook for the three human-evaluated CTS categories ([composition] / [scenario] / [actions] × [interactive]): which display processor a submission should use and why, the qwerty key map that stands in for controllers, a per-test judgement table, and stated verdict rules for the 3D-display ambiguities (#1523 § 4)
  • Motion-to-Photon Levers — every latency knob (late weave, repaint, queue tiers, deferred present, late latching) with its default, and the defaults per GPU topology (dGPU / iGPU / hybrid)
  • Weave Cadence vs. Eye Prediction — how late weave / repaint / slot partition / adapter split relate to vendor-side late latching and the eye predictor, which of them exist on Android, and the CNSDK prediction measurement plan
  • Adapter Selection — DXR_D3D_FORCE_GPU / DXR_VK_FORCE_GPU supported contract (hybrid iGPU/dGPU machines, in-process getenv caveat)
  • DPI Awareness — the DLL rule: Win32 geometry read inside the runtime answers in the HOST app's DPI space, so publish-worthy rects must pin a per-monitor-v2 thread context
  • Control Panel performance settings — census of all 71 DXR_* levers (read site, mechanism, default, tier) + the design for a persisted settings store the runtime reads inside the app process (design only)
  • Workspace Stability — the wedge family (lock starvation, fence jams, blocking presents, vendor-DP and MCP write wedges), the no-unbounded-work principle (#925), and the diagnostic toolkit ([RENDER] tell, PDBs, wedge captures, close gauntlet)

Vendor-specific reference docs now live in vendors/<vendor>/.

Archive

Resolved or superseded documents — kept for historical reference.

Legacy Monado

Inherited Monado documentation — kept for reference, not actively maintained.