rhodonite
    Preparing search index...

    Class WebXRSystem

    WebXRSystem class manages WebXR session and rendering for virtual reality experiences. This singleton class handles WebXR session lifecycle, camera setup for stereo rendering, input source management, and coordinate space transformations for VR applications.

    const webXRSystem = WebXRSystem.getInstance();
    await webXRSystem.readyForWebXR(requestButton, '/assets/');
    const controllers = await webXRSystem.enterWebXR({
      initialUserPosition: Vector3.fromCopyArray([0, 1.6, 0]),
      callbackOnXrSessionStart: () => console.log('VR started'),
      callbackOnXrSessionEnd: () => console.log('VR ended'),
      profilePriorities: ['oculus-touch', 'generic-trigger']
    });
    Index

    Accessors

    framebuffer isReadyForWebXR isWebXRMode leftProjectionMatrix leftViewMatrix requestedToEnterWebVR requestedToEnterWebXR rightProjectionMatrix rightViewMatrix xrSession

    Methods

    _getCameraComponentAt _getCameraComponentSIDAt _getCameraWorldPositionAt _getLeftViewport _getProjectMatrixAt _getRightViewport _getViewMatrixAt _getViewportAt _postRender _preRender enterWebXR exitWebXR getCanvasHeightForVr getCanvasWidthForVr getControllerEntities isMultiView readyForWebXR resetViewerTransform init

    Accessors

    • get framebuffer(): WebGLFramebuffer | undefined

      Gets the WebXR framebuffer for rendering.

      Returns WebGLFramebuffer | undefined

      The WebGL framebuffer provided by the XR system, or undefined if not available.

    • get isReadyForWebXR(): boolean

      Checks if the system is ready to enter WebXR.

      Returns boolean

      True if WebXR initialization is complete and ready for session start.

    • get isWebXRMode(): boolean

      Checks if currently in WebXR rendering mode.

      Returns boolean

      True if WebXR mode is active.

    • get requestedToEnterWebVR(): boolean

      Legacy property for backward compatibility.

      Returns boolean

      True if WebXR session entry has been requested.

      Use requestedToEnterWebXR instead.

    • get requestedToEnterWebXR(): boolean

      Checks if a WebXR session has been requested.

      Returns boolean

      True if WebXR session entry has been requested.

    • get xrSession(): XRSession | undefined

      Gets the current XR session object.

      Returns XRSession | undefined

      The active XRSession, or undefined if no session is active.

    Methods

    _getCameraComponentAt

    • _getCameraComponentAt(index: number): CameraComponent
      Internal

      Gets the camera component for the specified eye.

      Parameters

      • index: number

        Eye index (0: left, 1: right).

      Returns CameraComponent

      The CameraComponent for the specified eye.

    _getCameraComponentSIDAt

    • _getCameraComponentSIDAt(index: number): number
      Internal

      Gets the component SID (System ID) for the specified camera.

      Parameters

      • index: number

        Eye index (0: left, 1: right).

      Returns number

      The SID of the CameraComponent for the specified eye.

    _getCameraWorldPositionAt

    • _getCameraWorldPositionAt(displayIdx: number): Vector3
      Internal

      Gets the world position of the specified VR camera. Combines XR pose data with user position offset and viewer transformations.

      Parameters

      • displayIdx: number

        Eye index (0: left, 1: right).

      Returns Vector3

      The world position of the VR camera.

    _getLeftViewport

    • _getLeftViewport(): Vector4
      Internal

      Gets the viewport configuration for the left eye.

      Returns Vector4

      The viewport vector (x, y, width, height) for the left eye.

    _getProjectMatrixAt

    • _getProjectMatrixAt(index: number): MutableMatrix44
      Internal

      Gets the projection matrix for the specified eye.

      Parameters

      • index: number

        Eye index (0: left, 1: right).

      Returns MutableMatrix44

      The projection matrix for the specified eye.

    _getRightViewport

    • _getRightViewport(): Vector4
      Internal

      Gets the viewport configuration for the right eye. Accounts for multiview rendering mode differences.

      Returns Vector4

      The viewport vector (x, y, width, height) for the right eye.

    _getViewMatrixAt

    • _getViewMatrixAt(index: number): Matrix44
      Internal

      Gets the view matrix for the specified eye.

      Parameters

      • index: number

        Eye index (0: left, 1: right).

      Returns Matrix44

      The view matrix for the specified eye.

    _getViewportAt

    • _getViewportAt(index: number): Vector4
      Internal

      Gets the viewport configuration for the specified eye.

      Parameters

      • index: number

        Eye index (0: left, 1: right).

      Returns Vector4

      The viewport vector (x, y, width, height) for the specified eye.

    _postRender

    • _postRender(): void
      Internal

      Performs post-rendering cleanup for WebXR. Currently handles multiview framebuffer operations when enabled. Called once per frame after rendering is complete.

      Returns void

    _preRender

    • _preRender(time: number, xrFrame: XRFrame): void
      Internal

      Performs pre-rendering updates for WebXR. Updates view matrices, input sources, and gamepad states. Called once per frame before rendering begins.

      Parameters

      • time: number

        Current time in milliseconds.

      • xrFrame: XRFrame

        The XRFrame object for this rendering frame.

      Returns void

    • Initiates a WebXR VR session with specified configuration. Requests an immersive VR session, sets up reference space, WebGL layer, and input handling.

      Parameters

      • options: {
            callbackOnXrSessionEnd: () => void;
            callbackOnXrSessionStart: () => void;
            initialUserPosition?: Vector3;
            profilePriorities: string[];
        }

        Configuration object for WebXR session.

        • callbackOnXrSessionEnd: () => void

          Callback function executed when the XR session ends.

        • callbackOnXrSessionStart: () => void

          Callback function executed when the XR session starts.

        • OptionalinitialUserPosition?: Vector3

          Initial position of the user in world space. Defaults to [0, 1.1, 0].

        • profilePriorities: string[]

          Array of controller profile names in priority order for input mapping.

      Returns Promise<IEntity[] | undefined>

      Promise that resolves to an array of controller entities, or undefined on failure.

      const controllers = await webXRSystem.enterWebXR({
        initialUserPosition: Vector3.fromCopyArray([0, 1.6, 2]),
        callbackOnXrSessionStart: () => {
          console.log('VR session started');
          // Initialize VR-specific UI or game logic
        },
        callbackOnXrSessionEnd: () => {
          console.log('VR session ended');
          // Clean up VR-specific resources
        },
        profilePriorities: ['oculus-touch-v2', 'oculus-touch', 'generic-trigger']
      });

    • Exits the current WebXR session and returns to normal rendering mode. Gracefully terminates the XR session, triggering cleanup callbacks.

      Returns Promise<void>

      // Exit VR mode when user clicks a button
      exitButton.addEventListener('click', async () => {
        await webXRSystem.exitWebXR();
      });

    • Gets the canvas height configured for VR rendering.

      Returns number

      The height of the VR canvas in pixels.

    • Gets the canvas width configured for VR rendering.

      Returns number

      The width of the VR canvas in pixels.

    • Checks if multiview rendering is supported and enabled.

      Returns boolean

      True if multiview VR rendering is supported.

    • Prepares the WebXR system for VR session initialization. Checks for WebXR support, loads required modules, and sets up the entry point.

      Parameters

      • requestButtonDom: HTMLElement

        HTML element to serve as the VR entry button. If null, creates a default button.

      • basePath: string

        Base path for loading controller models and assets.

      Returns Promise<never[]>

      Promise that resolves to an empty array on success.

      When not running in a browser environment or WebXR is not supported.

      const enterButton = document.getElementById('enter-vr-button');
      await webXRSystem.readyForWebXR(enterButton, '/assets/controllers/');

    • Resets all viewer transformation parameters to their default values. Useful for resetting user position and orientation to origin.

      Returns void

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods