Performance Guide#

This performance reference covers CloudXR.js and WebXR tuning controls for balancing visual quality and frame stability.

Quick Reference#

Setting	Set in	Balanced	Performance-focused
`framebufferScaleFactor`	`XRWebGLLayer`	`1.4`-`1.5`	`1.2`
`fixedFoveation`	`XRWebGLLayer`	`0.666`	`1.0`
`deviceFrameRate`	CloudXR.js + WebXR	`90`	`90` (or lower if unstable)
`antialias`	WebGL context	`false`	`false`
`perEyeWidth` / `perEyeHeight`	CloudXR.js	`2048` / `1792`	`1792` / `1536`
`maxStreamingBitrateKbps`	CloudXR.js	`150000`	`100000`

Primary Tuning Controls#

framebufferScaleFactor (WebXR): client render resolution scaling
fixedFoveation (WebXR): peripheral quality reduction for performance
deviceFrameRate (CloudXR.js + WebXR): target refresh and stream timing alignment
perEyeWidth / perEyeHeight (CloudXR.js): stream resolution per eye
maxStreamingBitrateKbps (CloudXR.js): stream bitrate ceiling
antialias (WebGL): multisampling cost/quality tradeoff

Framebuffer Scale Factor#

framebufferScaleFactor controls XR framebuffer resolution scaling and strongly affects image clarity and frame time.

Higher values improve clarity but increase GPU cost.
On Quest-class devices, 1.4-1.5 is a practical high-quality range.

Fixed Foveation#

fixedFoveation reduces peripheral shading cost to improve performance.

0.666 (medium) is a good default balance.
1.0 (high) prioritizes performance with more peripheral degradation.

WebGL Antialiasing#

Set WebGL antialias to false by default for headset workloads. The quality gain is typically small relative to frame-time cost.

Stream Resolution and Bitrate#

perEyeWidth / perEyeHeight and maxStreamingBitrateKbps must be tuned together:

Resolution controls source detail and encode/decode workload.
Bitrate controls compression quality under available network bandwidth.
Per-eye width must be a multiple of 16.
Per-eye height must be a multiple of 64.

Device Frame Rate#

Set frame rate in both layers:

CloudXR.js deviceFrameRate for stream timing behavior.
WebXR updateTargetFrameRate (when supported) for device refresh target.

Keeping these two frame rate settings the same improves pose-to-photon stability.

Recommended Baseline (Meta Quest 3)#

Note

Quest 2 and Quest 3S devices have less powerful hardware than Quest 3. Start with slightly reduced settings on these devices (e.g., lower framebufferScaleFactor and resolution) and profile performance before increasing quality. Monitor frame rate and adjust parameters as needed.

Start with this balanced baseline and tune from measured results:

framebufferScaleFactor around 1.4 to 1.5
fixedFoveation around 0.666 (medium)
deviceFrameRate set to 90 when supported
perEyeWidth: 2048 and perEyeHeight: 1792
maxStreamingBitrateKbps: 150000
WebGL antialias: false

Pico 4 Ultra and HTTPS#

Pico 4 Ultra requires HTTPS web hosting for immersive WebXR workflows. Ensure your deployment uses wss:// signaling through a secure proxy where applicable.

Profiling Workflow#

Use remote debugging tools (for example, Chromium DevTools via chrome://inspect) to record:

frame pacing and long JavaScript tasks
network stalls and bandwidth pressure
stream startup and reconnect behaviors

Tune one parameter at a time and validate across representative network conditions.

Troubleshooting Performance Issues#

Frame rate drops below target#

Reduce framebufferScaleFactor.
Increase foveation level.
Reduce resolution and/or bitrate for constrained networks.

Visual quality issues#

Increase bitrate when network allows.
Increase per-eye resolution when server/client performance allows.
Reduce foveation level if peripheral quality is too low.

Stuttering or judder#

Check frame pacing in devtools.
Look for network jitter and packet loss.
Lower bitrate/resolution to restore stable frame timing.