HUD and Streaming Metrics

CloudXR Framework provides two ways to monitor streaming performance during an active session:

• Built-in HUD View: A ready-made SwiftUI overlay for quick visual debugging during development

• Time Series Metrics API: Programmatic access to raw per-frame performance data for custom visualization or export to external monitoring systems

Built-in HUD View

HUDView is a ready-made SwiftUI view that displays real-time streaming metrics as an overlay. It is useful during development and debugging to get quick assessments of streaming quality.

Configuration

Use HUDConfig to control which metric categories are displayed:

var hudConfig = HUDConfig()
hudConfig.showRateMetrics = true       // Frame rate and pose rate
hudConfig.showLatencyMetrics = true    // End-to-end latency breakdown
hudConfig.showBandwidthMetrics = true  // Bandwidth usage

Displaying the HUD

Add HUDView to your view hierarchy, passing the active session and configuration:

import CloudXRKit

struct StreamingOverlay: View {
    let session: CloudXRSession
    @State private var hudConfig = HUDConfig()

    var body: some View {
        HUDView(session: session, hudConfig: hudConfig)
    }
}

The HUD displays the following metrics:

• Rate

  • Frame rate (FPS): frequency at which frames are submitted for display

  • Pose rate (Hz): frequency at which the headset updates pose

• Latency (msec)

  • Pose to frame arrival: duration from receiving a pose update to the arrival of the frame from the server

  • Pose to dequeue: duration from receiving a pose update to the frame being dequeued after smoothing

  • Pose to frame display: duration from receiving a pose update to submitting the frame for display

• Bandwidth (Mbps)

  • Available bandwidth: total network bandwidth available

  • Streaming rate: video streaming rate from server to client

Session Information

For a snapshot of key-value session metadata (e.g., resolution, codec, connection type), use getHUDSessionInfo():

let info: [HUDTextInfo] = session.getHUDSessionInfo()
for item in info {
    print("\(item.label): \(item.value)")
}

Time Series Metrics API

For applications that need to visualize metrics in a custom UI, export data to an external monitoring system, or perform their own analysis, the time series API provides direct access to raw per-frame performance data.

Retrieving Time Series Data

Call getHUDTimeseries() on the session to get the current metric data:

let timeseriesGroups: [[HUDTimeseriesData]] = session.getHUDTimeseries()

The return value is a list of logical groups, where each group contains related HUDTimeseriesData entries (i.e., rate metrics are grouped together, and latency metrics are grouped together).

HUDTimeseriesData

Each HUDTimeseriesData instance contains the following properties:

Property	Type	Description
title	String	The name of the metric (e.g., “Frame Rate”, “Pose to Display”)
timeseriesData	[Float]	Raw per-frame sample values, containing up to 450 most recent samples
latestValue	Float?	The most recent sample value, if available
averageValue	Float?	The average across all current samples, if available
percentiles	[(p: Float, value: Float)]	Aggregated percentile data (p ranges from 0 to 100)
range	(min: Float, max: Float)	Suggested Y-axis range for plotting this metric

Buffer Size and Polling

Important

Internally, HUDTimeseriesData holds up to 450 most recent samples (approximately 5 seconds at 90 FPS). Older samples are discarded as new ones arrive.

If your application needs to visualize the HUD data in a custom UI or export it to an external metrics system, it is recommended to poll the data periodically (e.g., every 1 second) to avoid losing samples between reads.