SpectraXR

Keep your eyes in the cockpit. Bring your copilot into VR.

SpectraXR is a fail-safe OpenXR API Layer and out-of-process Host for Windows VR. It renders floating HTML/CSS, image, and live desktop-window HUD panels inside Star Citizen VR (Vulkan), Spectra / Unreal Engine 5.8 (D3D12), and any D3D11, D3D12, or Vulkan OpenXR game—driven live by BHC-Voice and NaveCore without ever hooking game memory.

  • Vulkan, D3D12 & D3D11
  • Zero game memory hooks
  • 3-strike circuit breaker
  • 100% local IPC
Active OpenXR HUD Composition Layers Interactive VR simulator
    Visible in VR: 4. Hidden: 2. Frame overhead: 0.04 ms.

    Version 1.0 Complete

    All 10 engineering phases of SpectraXR (`SpectraXR_Layer.dll` + `SpectraXR.exe` + Python, C++17 & Unreal Engine 5.8 SDKs) are built and verified with 9/9 automated CTest suites passing on hardware Vulkan, Direct3D 12, and Direct3D 11. The complete static-CRT portable release is just 494 KB with zero third-party runtime DLLs.

    Lifting your headset mid-quantum jump breaks everything VR is for.

    When you fly in VR—whether hauling cargo in Star Citizen on Vulkan via Virtual Desktop (VDXR) or testing a cockpit in Unreal Engine 5.8 on Direct3D 12—you constantly need external information: commodity trade tables, quantum jump distances, voice-assistant answers from BHC-Voice, or ship telemetry from NaveCore.

    Traditional overlays try to inject themselves by hooking IDXGISwapChain::Present or patching game functions in memory. That approach is fragile, breaks across graphics APIs, and triggers anti-cheat protections like Easy Anti-Cheat.

    SpectraXR takes the clean-room path designed by Khronos itself: an official OpenXR Implicit API Layer (`SpectraXR_Layer.dll`) paired with an out-of-process Host (`SpectraXR.exe`). The game renders its world; SpectraXR simply hands additional `XrCompositionLayerQuad` and `XrCompositionLayerCylinderKHR` surfaces to the VR runtime at the end of `xrEndFrame`.

    Engineered so the game always comes first

    Six non-negotiable rules govern every line of C++ in `SpectraXR_Layer.dll` and `SpectraXR.exe`.

    Official
    Loaded strictly through the standard Khronos OpenXR loader registry (`HKLM\SOFTWARE\Khronos\OpenXR\1\ApiLayers\Implicit`). Zero Detours, zero MinHook, zero `ReadProcessMemory`.
    Isolated
    All HTML/CSS rendering, window capture, JSON-RPC servers, and hotkey polling happen out-of-process in `SpectraXR.exe`. The in-game layer DLL only maps read-only shared memory (`FILE_MAP_READ`).
    Zero-Idle
    When a HUD card is static, `SpectraXR_Layer.dll` performs zero GPU texture uploads and zero `VkQueue` / `ID3D12CommandQueue` submissions—it simply re-submits the existing `XrSwapchain` handle in `xrEndFrame`.
    Fail-Safe
    Every OpenXR hook is guarded by `SPECTRAXR_SAFE_CALL` (`try/catch` + SEH). Three consecutive internal frame errors trip the circuit breaker and pass 100% of calls straight through to the runtime.
    Universal
    Supports Vulkan (`XR_KHR_vulkan_enable` & `enable2`), Direct3D 12 (`XR_KHR_D3D12_enable`), and Direct3D 11 (`XR_KHR_D3D11_enable`) across Virtual Desktop (VDXR), SteamVR, and Meta Quest Link.
    Tiny
    Compiled with static C++ runtime (`/MT`) and zero external DLL dependencies. Direct2D + DirectWrite renders crisp sci-fi HTML/CSS tables in ~1.5 ms inside a 494 KB package.

    What SpectraXR does

    Seven subsystems working together across the in-process OpenXR layer and the out-of-process Host.

    Native OpenXR swapchains for Vulkan, Direct3D 12, and Direct3D 11

    When a VR game calls `xrCreateSession`, `SpectraXR_Layer.dll` inspects the `XrSessionCreateInfo::next` chain to detect the active graphics binding and instantiates the matching GPU backend (`VulkanBackend`, `D3D12Backend`, or `D3D11Backend`).

    • Vulkan (`Star Citizen VR` on VDXR / SteamVR): Dynamically resolves `vkGetInstanceProcAddr` and `vkGetDeviceProcAddr` without linking against `vulkan-1.dll`. Uses a persistently mapped host-visible staging buffer, `vkCmdPipelineBarrier`, and `vkCmdCopyBufferToImage`.
    • Direct3D 12 (`Spectra` / Unreal Engine 5.8): Uses a persistently mapped `D3D12_HEAP_TYPE_UPLOAD` heap with 256-byte row-pitch alignment (`D3D12_TEXTURE_DATA_PITCH_ALIGNMENT`), resource state transitions (`RENDER_TARGET` → `COPY_DEST` → `RENDER_TARGET`), and `ID3D12Fence` synchronization.
    • Direct3D 11 (`spectraxr_test_app.exe` & sim titles): Uses immediate context `UpdateSubresource` onto the acquired `ID3D11Texture2D`.
    • Automatic BGRA ↔ RGBA Swizzle: Prefers `B8G8R8A8_UNORM_SRGB` and automatically swizzles channels if the runtime only offers `R8G8B8A8`.

    Why static-frame skipping matters. Under the OpenXR spec, once an `XrSwapchain` image is released, the compositor keeps displaying it every frame. SpectraXR only touches the GPU queue on the single frame when a panel's `frameCounter` increments—costing 0 GPU uploads on static frames.

    Supported Graphics APIs in SpectraXR_Layer.dll9/9 CTest Verified
    Graphics APIOpenXR ExtensionTarget TitlesStatic Frame GPU Cost
    Vulkan 1.2 / 1.3XR_KHR_vulkan_enable / enable2Star Citizen VR (VDXR / SteamVR)0 queue submissions
    Direct3D 12XR_KHR_D3D12_enableSpectra (Unreal Engine 5.8)0 command lists
    Direct3D 11XR_KHR_D3D11_enablespectraxr_test_app.exe, Sims0 texture copies

    Crisp Direct2D HTML/CSS HUD cards and live desktop window capture

    Instead of bundling a 150 MB browser engine, `SpectraXR.exe` includes a native hardware-accelerated Direct2D + DirectWrite + WIC renderer that turns HTML/CSS HUD markup, PNG/JPEG images, or live desktop windows into premultiplied BGRA shared-memory buffers in ~1.5 ms.

    • HTML/CSS HUD Renderer: Supports `h1`, `h2`, `h3`, `p`, `table`/`tr`/`th`/`td`, `ul`/`li`, `hr`, `div`/`span`, inline `color` and `background` hex/rgba styles, automatic word wrapping, and translucent sci-fi HUD frames with glowing cyan corner brackets.
    • 5 Built-in Sci-Fi HUD Templates (`templates/hud_templates.h`): Trade Result Card, Quantum Route/Waypoint Table, Tactical Alert Banner, Vessel Telemetry Card, and Pilot Checklist Card.
    • Live Window Capture (`type: "window"`): Captures any desktop window by title substring or `HWND` using `PrintWindow(..., PW_RENDERFULLCONTENT)` with `BitBlt` fallback and WIC Fant scaling.

    Premultiplied alpha clarity. Every panel is rendered in premultiplied `B8G8R8A8` with `XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT`, giving razor-sharp typography in your headset without dark fringes.

    SPECTRAXR // NAVECORE TRADE INTEL1024×640 px · 1.4 ms
    LOCATIONBUY (aUEC)SELL (aUEC)STATUS
    SMO-18 (MicroTech)6,120--HIGH STOCK
    Shubin SCD-1 (Daymar)6,250--MED STOCK
    TDD New Babbage--7,580HIGH DEMAND

    Head-locked, cockpit-locked, gaze placement, and curved cylinder layers

    Each of the 16 concurrent HUD slots can be attached to `VIEW` (head-locked HUD), `LOCAL` (cockpit/world-locked), or `STAGE` (room-scale) reference spaces, and switched between flat quads and curved cylinders on the fly.

    • Place Panel Here (`panel.placeHere`): Samples your live head pose (`xrLocateSpace` of `VIEW` in `LOCAL` space) and pins any panel at a chosen distance (e.g. `0.90 m`) directly in front of where you are looking.
    • Recenter Compensation: Intercepts `XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING` in `xrPollEvent` and tracks recenter events in `StatusBlock`.
    • Curved Cockpit Panels (`XrCompositionLayerCylinderKHR`): Set `"curved": true` with `cylRadiusM` and `cylAngleRad` to wrap wide tables smoothly around the pilot's field of view when supported by the runtime.
    • Per-Game Layout Profiles: Save and load named layouts (`%LOCALAPPDATA%\SpectraXR\profiles\StarCitizen.exe.json`). When a matching game connects, SpectraXR auto-loads its profile.

    Smooth fades & auto-hide. Set `autoHideMs: 8000` on voice-assistant popups so they fade in, stay readable for 8 seconds, and smoothly fade out without touching a button.

    JSON-RPC: panel.placeHere (Head-Gaze Capture)LOCAL Space
    → {"jsonrpc":"2.0","id":4,"method":"panel.placeHere","params":{"id":1,"distanceM":0.90}}
    ← {"jsonrpc":"2.0","id":4,"result":{"ok":true,"id":1,"space":"LOCAL","pos":[0.18,1.52,-0.64],"rot":[0.0,-0.383,0.0,0.924]}}

    Built-in Web Control Dashboard on 127.0.0.1:47820

    `SpectraXR.exe` serves a zero-dependency web dashboard at http://127.0.0.1:47820/dashboard (accessible from the system tray icon or any browser) for live inspection, testing, and layout management.

    • Live WIC PNG Panel Previews (`GET /api/preview?id=1`): See the exact rendered pixels of every active VR panel right in your browser, even before putting on your headset.
    • OpenXR Session Telemetry: Displays the connected game executable (`StarCitizen.exe` / `Spectra.exe`), active OpenXR runtime, headset model, graphics API (`Vulkan` / `Direct3D 12` / `Direct3D 11`), frame counter, and recenter count.
    • One-Click Controls: Hide/show panels, toggle flat vs. curved cylinder mode, snap panels to head gaze, adjust opacity, and save/load per-game profiles.
    • Live Diagnostics Log (`GET /api/logs`): Streams the tail of `%LOCALAPPDATA%\SpectraXR\layer.log` directly in the browser.

    Loopback-only security. The HTTP/WebSocket server binds strictly to `127.0.0.1`, validates the `Origin` header against cross-site requests, and requires the random 128-bit session token from `%LOCALAPPDATA%\SpectraXR\token.txt`.

    Local Host HTTP & IPC Endpoints127.0.0.1:47820
    EndpointProtocolPurpose
    /dashboardHTTP GETInteractive Sci-Fi Web Control Center
    /api/preview?id=1HTTP GETLive WIC PNG image preview of panel slot #1
    /status & /api/logsHTTP GETJSON telemetry & layer.log diagnostics stream
    /apiWebSocket & POSTJSON-RPC 2.0 control endpoint (token-authenticated)
    \\.\pipe\SpectraXR-<user>Named PipeLow-latency local IPC for NaveCore & BHC-Voice

    Global hotkeys, XInput gamepads, and non-exclusive HOTAS buttons

    In a flight or space sim, you cannot alt-tab out of your cockpit to toggle an overlay. `InputBindingManager` (`host/input_bindings.cpp`) listens in the background without ever taking focus or exclusive device ownership from your game.

    • Win32 Global Hotkeys (`RegisterHotKey`): Instant keyboard shortcuts for `toggle_overlay`, `place_panel_here`, `send_test_panel`, `opacity_up`, `opacity_down`, and `dismiss_popup`.
    • Non-Exclusive HOTAS Polling (`winmm.dll` `joyGetPosEx`): Reads throttle/stick button presses in the background without interfering with Star Citizen's DirectInput bindings.
    • XInput Gamepad Combos (`xinput1_4.dll`): Optional controller chord bindings configured in `%LOCALAPPDATA%\SpectraXR\bindings.json`.

    Triggerable via API too. Voice commands in BHC-Voice can trigger any input action directly via JSON-RPC `input.triggerAction` (e.g., saying "Pin panel here" or "Dismiss popup").

    Default Cockpit Bindings (%LOCALAPPDATA%\SpectraXR\bindings.json)Customizable
    ActionDefault HotkeyEffect in VR
    toggle_overlayCtrl + Shift + F12Pause or resume all VR overlay panels immediately
    place_panel_hereCtrl + Shift + F11Lock active panel 0.90 m ahead of current VR head gaze
    send_test_panelCtrl + Shift + F10Publish sample BHC-Voice commodity trade card
    opacity_up / downCtrl + Shift + PgUp / PgDnAdjust global HUD panel opacity by ±10%
    dismiss_popupCtrl + Shift + BackspaceHide the most recently displayed popup card

    Ready-made SDKs for BHC-Voice (Python), NaveCore (C++17), and Unreal Engine 5.8

    SpectraXR ships with first-class client libraries so your existing tools can push rich VR panels in a few lines of code.

    • Python Package (`clients/python/spectraxr/`): Zero-dependency `SpectraXRClient` supporting both Windows Named Pipe and WebSocket transports, automatic token discovery, and all 5 Sci-Fi HUD template builders.
    • C++17 Single-Header Client (`clients/cpp/spectraxr_client.hpp`): Drop-in header for NaveCore (`spectraxr::client::Client`) with automatic Named-Pipe connection retry and typed panel methods.
    • Unreal Engine 5.8 Plugin (`clients/ue5_plugin/SpectraXR/`): Provides `USpectraXRSubsystem` (Blueprint-callable `UGameInstanceSubsystem`) and `USpectraXRStereoLayerBridge` (Phase 10 native `UStereoLayerComponent` shared-memory texture bridge for Spectra).

    Sub-millisecond local transport. Over `\\.\pipe\SpectraXR-`, sending a JSON-RPC command from `NaveCore` or `BHC-Voice` to `SpectraXR.exe` completes in under a millisecond.

    BHC-Voice Python SDK Example (clients/python/spectraxr)Named Pipe
    from spectraxr import SpectraXRClient, build_trade_card_html
    with SpectraXRClient(transport="pipe") as xr:
    html = build_trade_card_html("GOLD", "STANTON", stops, "SMO-18 -> New Babbage")
    xr.create_html_panel(1, "bhc-trade", html, space="VIEW", auto_hide_ms=12000)

    3D Ray-Quad & Ray-Cylinder interaction without fighting the game for input

    Calling `xrSyncActions` inside an API layer can conflict with a game's own OpenXR action sets. SpectraXR solves this with a pure mathematical 3D raycast engine (`src/interaction.h/.cpp`) exposed via `panel.raycast`.

    • Exact Planar & Cylindrical Hit-Testing: Intersects any 3D ray (head-gaze pose from `StatusBlock` or an external controller/hand ray) against all active `XrCompositionLayerQuad` and `XrCompositionLayerCylinderKHR` panels.
    • Normalized UV & Pixel Coordinates: Returns `hitPanelId`, `distanceM`, normalized $(u, v) \in [0, 1]^2$, pixel coordinates $(x, y)$, and 3D world hit position.
    • Depth & `sortOrder` Priority: Automatically selects the closest visible panel and breaks ties using `sortOrder`.

    Zero input conflict. Your game keeps 100% ownership of its OpenXR controllers and action sets while your copilot knows exactly which panel and pixel you are looking at.

    JSON-RPC: panel.raycast (3D UV Hit-Testing)Phase 8 Verified
    → {"jsonrpc":"2.0","id":9,"method":"panel.raycast","params":{"origin":[0,0,0],"dir":[0,0,-1]}}
    ← {"jsonrpc":"2.0","id":9,"result":{"hit":true,"panelId":7,"distanceM":0.9,"u":0.5,"v":0.5,"pixelX":400,"pixelY":200}}

    Follow a VR HUD frame from voice command to headset

    Click each stage of the SpectraXR pipeline below to see how a panel reaches your eyes in under a tenth of a millisecond of game-thread time.

    1. JSON-RPC 2.0 over Named Pipe or WebSocket

    BHC-Voice (Python) or NaveCore (C++/UE5) sends a `panel.create` or `panel.setHtml` request over `\\.\pipe\SpectraXR-<username>` or `ws://127.0.0.1:47820/api`, authenticated by the local session token in `%LOCALAPPDATA%\SpectraXR\token.txt`.

    OpenXR API Layer
    An official plugin mechanism built into the Khronos OpenXR Loader. Layers sit cleanly between the game and the VR runtime without modifying game files or memory.
    XrCompositionLayerQuad
    A first-class planar surface submitted to the VR runtime's compositor, which warps and composites it at native headset refresh rate.
    XrCompositionLayerCylinderKHR
    A curved cylindrical surface (`XR_KHR_composition_layer_cylinder`) that wraps wide cockpit displays smoothly around the viewer.
    Seqlock (`seq`)
    A lock-free sequence counter in `PanelDesc`. The Host increments `seq` to odd before writing and even after writing; the Layer reads without ever blocking the game thread.
    Triple-Buffered Section
    Each panel's pixel mapping (`Local\SpectraXR_Panel_<id>_<gen>`) holds 3 full BGRA frames so `SpectraXR.exe` and `SpectraXR_Layer.dll` never contend on the same buffer.
    Circuit Breaker
    If `SpectraXR_Layer.dll` catches 3 consecutive exceptions or internal errors, it disables overlay injection for the rest of the session and passes every OpenXR call straight through.

    Try the HUD Panel & JSON-RPC Builder

    Configure a VR panel below to preview how SpectraXR styles it and generate the exact JSON-RPC 2.0 payload and Python SDK snippet.

    Composition Layer Geometry
    Typical cockpit reading distance is 0.75 to 1.20 meters (`posZ = -distance`).

    Built so an overlay bug can never crash your VR session

    A VR game running a 2-hour cargo haul cannot afford a crash from a companion tool. SpectraXR wraps every hook in a fail-safe harness and monitors a 2.5-second heartbeat from the Host.

    Circuit Breaker & Heartbeat Watchdog, simulated

    1. 1Game calls `xrEndFrame` while `SpectraXR_Layer.dll` reads shared memory
    2. 2Simulate either a Host disconnect or 3 consecutive GPU upload faults
    3. 3Watch the 2,500 ms heartbeat watchdog or 3-strike circuit breaker react
    4. 4Verify the game continues running at full frame rate with 0 crashes

    In both failure modes, `SpectraXR_Layer.dll` immediately stops appending overlay layers and forwards the game's original `XrFrameEndInfo` untouched.

    
          
    • `SPECTRAXR_SAFE_CALL` on every hook

      Every intercepted OpenXR entry point catches all C++ exceptions and structured hardware faults, logging the event and returning the underlying runtime's `XrResult`.

    • 3-Strike Circuit Breaker

      If 3 consecutive frames encounter an internal swapchain or shared-memory error, the layer trips `circuitBreakerTripped = 1` and becomes a pure passthrough for the rest of the session.

    • 2,500 ms Host Heartbeat Watchdog

      If `SpectraXR.exe` is closed or killed, `hostHeartbeatMs` stops advancing. Within 2.5 seconds the layer cleanly hides all dynamic panels without disturbing the game.

    • Executable Allow-List (`config.json`)

      Control which games activate the overlay via `%LOCALAPPDATA%\SpectraXR\config.json` (`allowedExecutables`).

    • Instant Kill-Switch (No Admin Needed)

      Drop a `disable.flag` file into `%LOCALAPPDATA%\SpectraXR\`, set `DISABLE_XR_APILAYER_NOVENDOR_SPECTRAXR=1`, or run `scripts\panic-off.ps1` to bypass the layer immediately.

    Emergency layer disable command (PowerShell):

    New-Item -Path "$env:LOCALAPPDATA\SpectraXR\disable.flag" -ItemType File -Force

    100% local by design

    SpectraXR makes zero outbound internet connections, has no cloud accounts, and never loads `ws2_32.dll` inside the game process. Here is every IPC channel and file it touches on your PC.

    Component / ChannelScopeSecurity & Access
    `Local\SpectraXR_Control_v1`Session-local Windows Shared Memory (`8,256 B`)Written by `SpectraXR.exe`; mapped read-only (`FILE_MAP_READ`) by `SpectraXR_Layer.dll`.
    `Local\SpectraXR_Panel_<id>_<gen>`Session-local Triple-Buffered Pixel MappingHolds 3 premultiplied BGRA frames per panel; mapped read-only by the layer.
    `Local\SpectraXR_Status_v1`Session-local Telemetry Block (`640 B`)Publishes runtime name, graphics API, FPS frame counter, and viewer head pose (`xrLocateSpace`).
    `\\.\pipe\SpectraXR-<username>`Local Windows Named PipeNewline-delimited JSON-RPC 2.0 for `NaveCore` and `BHC-Voice`, authenticated by `token.txt`.
    `127.0.0.1:47820`Loopback HTTP / WebSocket ServerBinds strictly to `127.0.0.1` (`INADDR_LOOPBACK`), checks `Origin`, and requires `token.txt`.
    External Internet TrafficNeverZero telemetry, zero analytics, zero external requests.

    Where your files live (`%LOCALAPPDATA%\SpectraXR\`)

    • token.txt: random 128-bit hex token for JSON-RPC auth
    • bindings.json: global hotkey, XInput & HOTAS bindings
    • config.json: optional executable allow-list
    • profiles\<exe>.json: saved per-game panel layouts
    • layer.log: OpenXR layer diagnostic log (shared-read)
    • disable.flag: optional non-admin kill-switch marker

    What SpectraXR is—and what it is not

    Clear boundaries make a reliable tool. Here are the design trade-offs you should know.

    • OpenXR games only

      SpectraXR is an OpenXR API Layer. It works with any D3D11, D3D12, or Vulkan title running on OpenXR (Virtual Desktop VDXR, SteamVR OpenXR, Meta Quest Link). Legacy OpenVR-only titles that do not use OpenXR are not intercepted unless run through an OpenXR bridge.

    • HUD HTML subset, not a full web browser

      To keep `SpectraXR.exe` under 300 KB with zero external DLLs and ~1.5 ms render times, the built-in Direct2D renderer supports structured HUD HTML/CSS (`h1`–`h3`, `table`, `ul`, `p`, `hr`, colors, borders) rather than full JavaScript web apps. If you need a full browser window in VR, use SpectraXR's live `type: "window"` capture mode.

    • No game memory reading or hooking

      SpectraXR never reads ship health or coordinates out of game memory. All telemetry displayed on panels comes from legitimate external sources such as your voice assistant (`BHC-Voice`), `NaveCore`, or game log/API feeds.

    • Protected DRM windows

      Live window capture (`PrintWindow` with `PW_RENDERFULLCONTENT`) captures standard Win32, WPF, Electron, and browser windows, but windows protected by hardware DRM (`WDA_EXCLUDEFROMCAPTURE`) will appear blank by OS design.

    • One-time Admin registration for system-wide implicit layer

      Testing with `spectraxr_test_app.exe` requires no Administrator rights and no registry changes. Registering `SpectraXR_Layer.dll` system-wide under `HKLM\SOFTWARE\Khronos\OpenXR\1\ApiLayers\Implicit` (`scripts\install.ps1`) requires an elevated PowerShell prompt once.

    Clean-room C++17 architecture, hardware-verified

    Written from scratch in modern C++17 against the official Khronos OpenXR 1.1 and Vulkan 1.3 headers (Apache-2.0) and standard Windows SDK libraries, compiled with `/W4 /permissive- /WX`.

    SpectraXR Two-Process Architecture BHC-Voice and NaveCore talk to SpectraXR.exe over Named Pipe or WebSocket. SpectraXR.exe renders HTML/Window panels into read-only Windows Shared Memory, which SpectraXR_Layer.dll composites inside the game process during xrEndFrame. Clients: BHC-Voice (Python) · NaveCore (C++/UE5) · Web UI Named Pipe (\\.\pipe\SpectraXR-<user>) & WebSocket (127.0.0.1:47820) JSON-RPC 2.0 + token.txt Out-of-Process Host (SpectraXR.exe) Direct2D/DirectWrite HTML Renderer · WIC Image & Live Window Capture PanelManager · Per-Game Profiles · Global Hotkeys, XInput & HOTAS Seqlock + Triple-Buffered BGRA Windows Shared Memory (Local\SpectraXR_*) ControlBlock (8,256 B) · Panel Sections (3× BGRA) · StatusBlock (640 B) FILE_MAP_READ only In-Process OpenXR Layer (SpectraXR_Layer.dll) VulkanBackend · D3D12Backend · D3D11Backend · 3D Raycast Engine Appends XrCompositionLayerQuad & XrCompositionLayerCylinderKHR in xrEndFrame Guarded by SPECTRAXR_SAFE_CALL & 3-Strike Circuit Breaker
    • 9/9 Automated CTest Suites Passing. Every phase is verified by automated tests (`protocol_test`, `layer_smoke_test`, `phase2_integration_test`, `vulkan_backend_test`, `d3d12_backend_test`, `phase5_lifecycle_test`, `phase6_dashboard_input_test`, `phase7_content_clients_test`, `phase8_interaction_test`).
    • Hardware GPU Readback Verified. Both `VulkanBackend` and `D3D12Backend` are tested on real NVIDIA RTX hardware by reading back uploaded swapchain textures from GPU memory and verifying pixel-exact BGRA/RGBA values.
    • 20-Cycle VR Session Stress Tested. `phase5_lifecycle_test` runs 20 rapid `xrCreateSession` / `xrEndFrame` / `xrDestroySession` cycles and verifies 100% swapchain and `XrSpace` destruction with zero leaks.
    • Strict ABI Static Assertions. `shared_protocol.h` enforces compile-time `sizeof` and `offsetof` assertions on `PanelDesc` (`512 B`), `ControlBlock` (`8,256 B`), and `StatusBlock` (`640 B`).
    • Clean-Room Provenance. Zero GPL/LGPL code. Uses only Apache-2.0 Khronos OpenXR/Vulkan headers and standard Windows SDK libraries.

    Testing it, step by step

    Start without touching any registry keys, then enable it globally for your games when you are ready.

    1. Start the SpectraXR Host

      Run .\build\Release\SpectraXR.exe --demo-panel. A system tray icon appears and publishes the sample BHC-Voice commodity panel into shared memory.

    2. Open the Web Control Dashboard

      Visit http://127.0.0.1:47820/dashboard in your browser to see the live WIC PNG preview of Panel #1, inspect hotkey/HOTAS bindings, and test live opacity and curve controls.

    3. Test in your VR headset (zero registry changes)

      With Virtual Desktop (VDXR), SteamVR, or Quest Link active, run .\build\Release\spectraxr_test_app.exe --seconds 30. It chains SpectraXR_Layer.dll directly in-process so you immediately see the stereo 3D HUD panel in your headset.

    4. Try head-gaze placement & hotkeys

      Look slightly to the left or right in VR and press Ctrl+Shift+F11 (`place_panel_here`) to pin the panel in 3D `LOCAL` cockpit space, or press Ctrl+Shift+F12 to pause/resume the overlay.

    5. Push live panels from Python or C++ (BHC-Voice & NaveCore)

      Run python .\tools\python\send_panel.py --pipe or connect using clients/python/spectraxr or clients/cpp/spectraxr_client.hpp.

    6. Enable system-wide for Star Citizen VR & Spectra (optional, Admin)

      Run .\scripts\check-layers.ps1 to inspect existing OpenXR layers, then run .\scripts\install.ps1 in an elevated PowerShell prompt. Use .\scripts\uninstall.ps1 or .\scripts\panic-off.ps1 anytime to remove or disable it.

    All 10 phases complete in Version 1.0

    Every phase from the implementation plan has been built, hardware-tested, and packaged.

    Completed in v1.0 (Phases 0–5)

    • Phase 0: OpenXR Loader & Diagnostics CTest Passed

      NegotiateLoaderApiLayerInterface, self-interception fix, and shared-read logging to `layer.log`.

    • Phase 1: D3D11 Quad & Safety Harness CTest Passed

      `D3D11Backend`, `SPECTRAXR_SAFE_CALL`, 3-strike circuit breaker, and `spectraxr_test_app.exe`.

    • Phase 2: Host, Shared Memory & HTML Renderer CTest Passed

      `SpectraXR.exe`, triple-buffered seqlock IPC, Direct2D/DirectWrite HTML HUD renderer, and WebSocket JSON-RPC 2.0 server.

    • Phase 3: Vulkan Backend for Star Citizen VR RTX Verified

      Zero-link dynamic Vulkan loader, staging ring buffer, image layout barriers, and static-frame upload skipping.

    • Phase 4: Direct3D 12 Backend for UE5.8 / Spectra RTX Verified

      256-byte pitch-aligned upload heap, `CopyTextureRegion`, resource barriers, and fence sync.

    • Phase 5: Gaze Placement, Curved Layers & Named Pipe 20-Cycle Stress

      `xrLocateSpace` head-gaze capture (`panel.placeHere`), `XrCompositionLayerCylinderKHR`, per-game profiles, and `\\.\pipe\SpectraXR-<user>`.

    Completed in v1.0 (Phases 6–10)

    • Phase 6: Web Dashboard & HOTAS/Hotkey Input New in v1.0

      Embedded `/dashboard` UI, live WIC PNG panel previews, `RegisterHotKey`, XInput, and non-exclusive HOTAS polling.

    • Phase 7: Window Capture, Templates & SDKs New in v1.0

      `PrintWindow` live window capture, 5 Sci-Fi HUD templates, Python `spectraxr` package, C++17 header client, and UE5.8 plugin.

    • Phase 8: 3D Ray-Quad & Ray-Cylinder Interaction New in v1.0

      Exact 3D raycast UV & pixel hit-testing (`panel.raycast`) with zero `xrSyncActions` conflict.

    • Phase 9: Installer, Layer Inspector & Provenance New in v1.0

      Inno Setup script (`SpectraXR.iss`), 494 KB portable ZIP release with `SHA256SUMS.txt`, and `check-layers.ps1`.

    • Phase 10: Native UE5.8 Stereo-Layer Bridge New in v1.0

      `USpectraXRStereoLayerBridge` component for native Unreal Engine 5.8 stereo layer rendering in `Spectra`.

    Questions pilots & developers ask

    Is SpectraXR safe to use with Star Citizen VR and Easy Anti-Cheat?

    SpectraXR is architected specifically to follow the official Khronos OpenXR Implicit API Layer specification (`NegotiateLoaderApiLayerInterface`). It never hooks game functions, never patches vtables, never calls `ReadProcessMemory` or `WriteProcessMemory`, and never loads networking DLLs inside the game process. It only submits standard `XrCompositionLayerQuad` and `XrCompositionLayerCylinderKHR` structs during `xrEndFrame`.

    Can I test SpectraXR in my headset without changing Windows Registry keys?

    Yes! Run `SpectraXR.exe --demo-panel` and then launch `spectraxr_test_app.exe --seconds 30`. The test app loads your active OpenXR runtime (Virtual Desktop VDXR, SteamVR, or Quest Link) and chains `SpectraXR_Layer.dll` directly in-process without needing any registry edits or Administrator rights.

    How much FPS / GPU overhead does SpectraXR add in VR?

    On frames where your HUD panels do not change their text or pixels (which is over 99% of frames for a trade card or route table), `SpectraXR_Layer.dll` performs zero GPU texture uploads and zero queue submissions—it only appends the existing `XrSwapchain` struct pointer to `XrFrameEndInfo::layers` (~0.03 ms CPU time).

    How does "Place Panel Here" (`panel.placeHere`) work?

    During `xrEndFrame`, the layer calls `xrLocateSpace(viewSpace, localSpace, displayTime)` and writes your headset's current position and quaternion orientation into `StatusBlock`. When you press `Ctrl+Shift+F11` (or call `panel.placeHere`), the Host places the panel `0.90 m` along your gaze vector and switches it to `LOCAL` cockpit space so it stays pinned there while you look around.

    Does it work alongside OpenXR Toolkit or OpenKneeboard?

    Yes. Run `scripts\check-layers.ps1` to view the installed implicit layer chain. SpectraXR preserves all existing `XrFrameEndInfo::layers` submitted by the game and earlier layers, and respects the runtime's `maxLayerCount` limit.

    How do BHC-Voice (Python) and NaveCore (C++ / UE5) connect to it?

    Both connect to `\\.\pipe\SpectraXR-<username>` (or `ws://127.0.0.1:47820/api`), read the local token from `%LOCALAPPDATA%\SpectraXR\token.txt`, and send newline-delimited JSON-RPC 2.0 commands using `clients/python/spectraxr` or `clients/cpp/spectraxr_client.hpp`.

    What happens if `SpectraXR.exe` crashes or is closed while I am in VR?

    Nothing happens to your game. `SpectraXR_Layer.dll` checks `hostHeartbeatMs` on every frame; if the Host heartbeat is older than 2,500 ms, the layer automatically hides dynamic panels and continues forwarding `xrEndFrame` cleanly.

    Ready for your cockpit.

    SpectraXR v1.0 (`dist/SpectraXR-v1.0.0-win64.zip`, 494 KB) is built, tested across all 9 CTest suites, and ready for VR headset testing in `spectraxr_test_app.exe`, `Spectra` (UE5.8), and `Star Citizen VR`.

    Made by Biohazard Corp (`NaveCore` · `BHC-Voice` · `Spectra` · `SpectraXR`). More at biohazard-corp.nl.