Atlas - README-xr.md
Home / ext / SDL / docs
Rendered HTML view | Size: 9678 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
OpenXR / VR Development with SDL
This document covers how to build OpenXR (VR/AR) applications using SDL's GPU API with OpenXR integration.
Overview
SDL3 provides OpenXR integration through the GPU API, allowing you to render to VR/AR headsets using a unified interface across multiple graphics backends (Vulkan, D3D12, Metal).
Key features:
- Automatic OpenXR instance and session management
- Swapchain creation and image acquisition
- Support for multi-pass stereo rendering
- Works with desktop VR runtimes (SteamVR, Oculus, Windows Mixed Reality) and standalone headsets (Meta Quest, Pico)
Desktop Development
Requirements

OpenXR Loader (openxr_loader.dll / libopenxr_loader.so)
On Windows: Usually installed with VR runtime software (Oculus, SteamVR)
On Linux: Install via package manager (e.g., libopenxr-loader1 on Ubuntu)

Can also use SDL_HINT_OPENXR_LIBRARY to specify a custom loader path


OpenXR Runtime

At least one OpenXR runtime must be installed and active

Examples: SteamVR, Oculus Desktop, Monado (Linux)


VR Headset

Connected and recognized by the runtime

Basic Usage
```c
include 
include 
include 
// These will be populated by SDL
XrInstance xr_instance = XR_NULL_HANDLE;
XrSystemId xr_system_id = 0;
// Create GPU device with XR enabled
SDL_PropertiesID props = SDL_CreateProperties();
SDL_SetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_ENABLE_BOOLEAN, true);
SDL_SetPointerProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_INSTANCE_POINTER, &xr_instance);
SDL_SetPointerProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_SYSTEM_ID_POINTER, &xr_system_id);
// Optional: Override app name/version (defaults to SDL_SetAppMetadata values if not set)
SDL_SetStringProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_APPLICATION_NAME_STRING, "My VR App");
SDL_SetNumberProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_APPLICATION_VERSION_NUMBER, 1);
SDL_GPUDevice *device = SDL_CreateGPUDeviceWithProperties(props);
SDL_DestroyProperties(props);
// xr_instance and xr_system_id are now populated by SDL
```
See test/testgpu_spinning_cube_xr.c for a complete example.

Android Development
Building OpenXR applications for Android standalone headsets (Meta Quest, Pico, etc.) requires additional manifest configuration beyond standard Android apps.
Android Manifest Requirements
The manifest requirements fall into three categories:

OpenXR Standard (Khronos) - Required for all OpenXR apps
Platform-Specific - Required for specific headset platforms
Optional Features - Enable additional capabilities


OpenXR Standard Requirements (All Platforms)
These are required by the Khronos OpenXR specification for Android:
Permissions
```xml



```
Queries (Android 11+)
Required for the app to discover OpenXR runtimes:
xml
<queries>
    <provider android:authorities="org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker" />
    <intent>
        <action android:name="org.khronos.openxr.OpenXRRuntimeService" />
    </intent>
    <intent>
        <action android:name="org.khronos.openxr.OpenXRApiLayerService" />
    </intent>
</queries>
Hardware Features
```xml








```
Intent Category
xml
<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <!-- Khronos OpenXR immersive app category -->
        <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
    </intent-filter>
</activity>

Meta Quest Requirements
These are required for apps to run properly on Meta Quest devices. Without these, your app may launch in "pancake" 2D mode instead of VR.
VR Intent Category (Critical!)
xml
<activity ...>
    <intent-filter>
        ...
        <!-- CRITICAL: Without this, app launches in 2D mode on Quest! -->
        <category android:name="com.oculus.intent.category.VR" />
    </intent-filter>
</activity>
Supported Devices
xml
<application ...>
    <!-- Required: Specifies which Quest devices are supported -->
    <meta-data android:name="com.oculus.supportedDevices"
               android:value="quest|quest2|questpro|quest3|quest3s" />
</application>
Focus Handling (Recommended)
xml
<application ...>
    <!-- Properly handles when user opens the Quest system menu -->
    <meta-data android:name="com.oculus.vr.focusaware"
               android:value="true" />
</application>
Hand Tracking (Optional)
```xml



    
    
    

```
VR Splash Screen (Optional)
xml
<application ...>
    <meta-data android:name="com.oculus.ossplash"
               android:value="true" />
    <meta-data android:name="com.oculus.ossplash.colorspace"
               android:value="QUEST_SRGB_NONGAMMA" />
    <meta-data android:name="com.oculus.ossplash.background"
               android:resource="@drawable/vr_splash" />
</application>

Pico Requirements
For Pico Neo, Pico 4, and other Pico headsets:
VR Intent Category
xml
<activity ...>
    <intent-filter>
        ...
        <!-- Pico VR category -->
        <category android:name="com.picovr.intent.category.VR" />
    </intent-filter>
</activity>
Supported Devices (Optional)
xml
<application ...>
    <!-- Pico device support -->
    <meta-data android:name="pvr.app.type"
               android:value="vr" />
</application>

HTC Vive Focus / VIVE XR Elite
xml
<activity ...>
    <intent-filter>
        ...
        <!-- HTC Vive category -->
        <category android:name="com.htc.intent.category.VRAPP" />
    </intent-filter>
</activity>

Quick Reference Table
| Declaration | Purpose | Scope |
|-------------|---------|-------|
| org.khronos.openxr.permission.OPENXR | Runtime communication | All OpenXR |
| android.hardware.vr.headtracking | Marks app as VR | All OpenXR |
| org.khronos.openxr.intent.category.IMMERSIVE_HMD | Khronos standard VR category | All OpenXR |
| com.oculus.intent.category.VR | Launch in VR mode | Meta Quest |
| com.oculus.supportedDevices | Device compatibility | Meta Quest |
| com.oculus.vr.focusaware | System menu handling | Meta Quest |
| com.picovr.intent.category.VR | Launch in VR mode | Pico |
| com.htc.intent.category.VRAPP | Launch in VR mode | HTC Vive |

Example Manifest
SDL provides an example XR manifest template at:
test/android/cmake/AndroidManifest.xr.xml.cmake
This template includes:
- All Khronos OpenXR requirements
- Meta Quest support (configurable via SDL_ANDROID_XR_META_SUPPORT CMake option)
- Proper intent filters for VR launching

Common Issues
App launches in 2D "pancake" mode
Cause: Missing platform-specific VR intent category.
Solution: Add the appropriate category for your target platform:
- Meta Quest: com.oculus.intent.category.VR
- Pico: com.picovr.intent.category.VR
- HTC: com.htc.intent.category.VRAPP
"No OpenXR runtime found" error
Cause: The OpenXR loader can't find a runtime.
Solutions:
- Desktop: Ensure VR software (SteamVR, Oculus) is installed and running
- Android: Ensure your manifest has the correct <queries> block for runtime discovery
- Linux: Install libopenxr-loader1 and configure the active runtime
OpenXR loader not found
Cause: openxr_loader.dll / libopenxr_loader.so is not in the library path.
Solutions:
- Install the Khronos OpenXR SDK
- On Windows, VR runtimes typically install this, but may not add it to PATH
- Use SDL_HINT_OPENXR_LIBRARY to specify the loader path explicitly
Vulkan validation errors on shutdown
Cause: GPU resources destroyed while still in use.
Solution: Call SDL_WaitForGPUIdle(device) before releasing any GPU resources or destroying the device.

Additional Resources

Khronos OpenXR Specification
Meta Quest Developer Documentation
Pico Developer Documentation
SDL GPU API Documentation
Example code: test/testgpu_spinning_cube_xr.c

[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.