Interface: Session#

Defines the interface for CloudXR streaming sessions.

Provides the core functionality for managing CloudXR streaming sessions, including connection management, rendering, and communication with the CloudXR Runtime.

Example#

// Create a session
const session = createSession(sessionOptions, delegates);

// Connect to CloudXR Runtime
if (session.connect()) {
  console.info('Connection initiated');
}

// In your render loop
function renderFrame(time, frame) {
  try {
    // Send tracking data
    session.sendTrackingStateToServer(time, frame);

    // Render CloudXR content
    session.render(time, frame, xrWebGLLayer);
  } catch (error) {
    console.error('Error during frame rendering:', error);
  }
}

Properties#

state#

readonly state: SessionState

Current state of the session.

This readonly property provides the current state of the session, which can be used to determine what operations are available and to monitor the session lifecycle.

Example#

// Check if session is ready for rendering
if (session.state === SessionState.Connected) {
  // Safe to call render() and sendTrackingStateToServer()
}

// Monitor state changes
console.info('Session state:', session.state);

availableMessageChannels#

readonly availableMessageChannels: MessageChannel[]

Available message channels announced by the server.

This array is updated automatically when the server announces new channels or closes existing channels. Each channel provides bi-directional communication.

Channels are opened automatically on the first sendServerMessage() call.

Example#

// Get first available channel
const channels = session.availableMessageChannels;
if (channels.length > 0) {
  const channel = channels[0];
  console.log('Channel UUID:', channel.uuid);
  console.log('Channel status:', channel.status);

  // Send message (auto-opens channel)
  const message = new TextEncoder().encode("Hello Server");
  channel.sendServerMessage(message);

  // Receive messages
  while (true) {
    const data = await channel.receiveMessage();
    if (data === null) break;
    console.log('Received:', new TextDecoder().decode(data));
  }

  // Close when done
  channel.disconnect();
}

Methods#

connect()#

connect(): void

Connect to the CloudXR server and start streaming.

Initiates connection to the CloudXR Runtime and transitions the session to SessionState.Connecting, then SessionState.Connected once streaming is active.

Returns#

void

Throws#

If called when session is not in Initialized or Disconnected state

Example#

try {
  session.connect();
  console.info('Connection initiated');
} catch (error) {
  console.error('Failed to initiate connection:', error.message);
}

disconnect()#

disconnect(): void

Disconnects from the CloudXR Runtime and terminates any streams.

Gracefully disconnects from the CloudXR Runtime and cleans up resources. The session transitions through the following states:

  1. SessionState.Disconnecting - Disconnection in progress

  2. SessionState.Disconnected - Successfully disconnected

After disconnection, the session can be reconnected by calling connect() again.

Returns#

void

Example#

// Disconnect when done
session.disconnect();
console.info('Disconnection initiated');

// Disconnect on user action
document.getElementById('disconnect-btn').onclick = () => {
  session.disconnect();
};

sendTrackingStateToServer()#

sendTrackingStateToServer(timestamp, frame): boolean

Sends the view pose and input tracking data to the CloudXR Runtime.

Sends the current viewer pose (head position/orientation) and input tracking data (controllers, hand tracking) to the CloudXR Runtime. This data is essential for the Runtime to render the correct view and handle user input.

This method also surfaces any deferred exceptions from internal callbacks (e.g., message handling, video frame processing). Always wrap calls in try-catch.

Parameters#

timestamp#

number

The current timestamp (DOMHighResTimeStamp) from the XR frame

frame#

XRFrame

The XR frame containing tracking data to send to the Runtime

Returns#

boolean

True if the tracking data was sent successfully, false otherwise. Returns false if no viewer pose is available.

Throws#

If session is not in Connected state

Throws#

If a deferred exception occurred in an internal callback

Example#

// In your WebXR render loop
function renderFrame(time, frame) {
  try {
    // Send tracking data first
    if (!session.sendTrackingStateToServer(time, frame)) {
      console.warn('Failed to send tracking state');
      return;
    }

    // Then render the frame
    session.render(time, frame, xrWebGLLayer);
  } catch (error) {
    console.error('Error in render frame:', error);
  }
}

// Start the render loop
xrSession.requestAnimationFrame(renderFrame);

render()#

render(timestamp, frame, layer): void

Renders a frame from CloudXR.

Renders the current frame received from the CloudXR Runtime into the specified WebXR layer. Call this method every frame in your WebXR render loop after sending tracking data.

This method also surfaces any deferred exceptions from internal callbacks (e.g., message handling, video frame processing). Always wrap calls in try-catch.

Parameters#

timestamp#

number

The current timestamp (DOMHighResTimeStamp) from the XR frame

frame#

XRFrame

The XR frame to render

layer#

XRWebGLLayer

The WebXR layer to render into (typically xrSession.renderState.baseLayer)

Returns#

void

Throws#

If a deferred exception occurred in an internal callback

Throws#

If viewport or render operations fail

Example#

// Complete render loop
function renderFrame(time, frame) {
  try {
    // Send tracking data
    session.sendTrackingStateToServer(time, frame);

    // Render CloudXR content
    session.render(time, frame, xrSession.renderState.baseLayer);
  } catch (error) {
    console.error('Error in render frame:', error);
  }

  // Continue the loop
  xrSession.requestAnimationFrame(renderFrame);
}

// Start rendering
xrSession.requestAnimationFrame(renderFrame);

sendServerMessage()#

sendServerMessage(message): void

Send a custom message to the server (legacy API).

Parameters#

message#

any

The message object to send to the server (must be a valid JSON object)

Returns#

void

Deprecated#

Use availableMessageChannels to get MessageChannel objects and send messages directly.

Sends a custom JSON message to the server through the CloudXR protocol. The message is serialized and sent via the streaming connection on channel 0 (legacy).

Throws#

If session is not connected

Throws#

If message is not a valid JSON object (null, primitive, or array)

Example#

// Legacy API (deprecated)
const customMessage = {
  type: 'userAction',
  action: 'buttonPress',
  data: { buttonId: 1 }
};
session.sendServerMessage(customMessage);