CloudXR SDK API

This is a high-level reference of the CloudXR functions, structures, and variables. For deeper details in how to put this into use, please see the section on Client Development.

API Functions

cxrError cxrCreateReceiver(const cxrReceiverDesc *description, cxrReceiverHandle *receiver)

Initialize the CloudXR client and create a Receiver handle to be used by all other API calls.

Note

The returned cxrReceiverHandle must be passed as the first parameter to all other CloudXR client API calls.

Parameters

  • description – [in] A filled-out client receiver descriptor struct (see cxrReceiverDesc).

  • receiver – [out] A pointer to return back to the client an opaque handle representing the Receiver interface.

cxrError cxrConnect(cxrReceiverHandle receiver, const char *serverAddr, cxrConnectionDesc *description)

Establish a connection to a CloudXR server.

Parameters

  • receiver – [in] cxrReceiverHandle handle that was obtained from cxrCreateReceiver().

  • serverAddr – [in] IP address of the CloudXR server.

  • description – [in] Optional settings that control connection behavior (see cxrConnnectionDesc).

void cxrDestroyReceiver(cxrReceiverHandle receiver)

Terminate a streaming session and free the associated CloudXR resources.

Note

The Receiver handle is invalid upon return from this call.

Parameters
cxrError cxrLatchFrame(cxrReceiverHandle receiver, cxrFramesLatched *framesLatched, uint32_t frameMask, uint32_t timeoutMs)

Acquire the next available decoded video frames from network stream.

This call attempts to acquire the next available decoded video frames for all streams in streamMask, together in lock-step. It can be called repeatedly with different masks in order to acquire frames without concurrent locking.

Parameters

  • receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()

  • framesLatched – [inout] pointer to a cxrFramesLatched struct with a lifetime until cxrReleaseFrame.

  • frameMask – [in] a bitfield mask set to 1<<[frame number] for generic frames, or use special values like cxrFrameMask_All.

  • timeoutMs – [in] number of milliseconds to wait for frame(s) before returning in error.

Returns cxrError_Parameter_Invalid

An empty mask was passed in

Returns cxrError_Frame_Not_Released

A prior call to cxrLatchFrame was not ended with a call to cxrReleaseFrame

Returns cxrError_Frame_Not_Ready

The timeoutMs elapsed without any frame(s) available

Returns cxrError_Receiver_Not_Running

The Receiver object is not yet connected and streaming

Returns cxrError_Decoder_No_Texture

No texture surface is available to return data back to the application

Returns cxrError_Frame_Not_Latched

A frame was available but a low-level failure occurred during data copy

cxrBool cxrBlitFrame(cxrReceiverHandle receiver, cxrFramesLatched *framesLatched, uint32_t frameMask)

ANDROID-ONLY Render a masked set of the latched video frame(s) to the currently bound target surface.

Parameters

  • receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()

  • framesLatched – [inout] pointer to a cxrFramesLatched struct with a lifetime until cxrReleaseFrame.

  • frameMask – [in] a bitfield mask set to 1<<[frame number] for generic frames, or use cxrFrameMask special values.

cxrError cxrReleaseFrame(cxrReceiverHandle receiver, cxrFramesLatched *framesLatched)

Release a previously latched set of video frames from cxrLatchFrame.

Note

The cxrFramesLatched data is invalid upon return from this call.

Parameters
cxrError cxrSendLightProperties(cxrReceiverHandle receiver, const cxrLightProperties *lightProps)

Provide estimated world lighting properties to the server.

This is used to send ARCore or ARKit lighting estimates to the server, for live integration into 3D rendered scene lighting. It supports a primary light source as well as ambient spherical harmonics. On the server side, apps can query this data using: 

   IVRSystem::GetArrayTrackedDeviceProperty(cxrTrackedDeviceProperty)

cxrError cxrSendInputEvent(cxrReceiverHandle receiver, const cxrInputEvent *inputEvent)

Send non-VR-controller input events to the server for app-specific handling.

void cxrTraceEvent(char *name, uint32_t eventId, cxrBool begin)

Add an event to the trace timeline.

This function allows for the insertion of custom events into the trace timeline of CloudXR. Note that to log an event this function must be called twice.

Example of logging an event: void foo() { cxrTraceEvent(“ButtonPressed”, 0x23, cxrTrue); cxrTraceEvent(“ButtonPressed”, 0x23, cxrFalse); }

Parameters

  • name – [in] name of the event to add to the timeline

  • eventId – [in] a custom Id value that can be used to identify the event in the timeline

  • begin – [in] true indicates the beginning of an event, false indicates the end of the event.

cxrError cxrSendAudio(cxrReceiverHandle receiver, const cxrAudioFrame *audioFrame)

Send client input audio (i.e. microphone) to the server.

Note

To use this API set the sendAudio boolean (see cxrDeviceDesc).

Parameters

  • receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()

  • audioFrame – [in] A filled-out struct containing the audio data to send (see cxrAudioFrame).

cxrError cxrSendPose(cxrReceiverHandle receiver, const cxrVRTrackingState *trackingState)

Explicitly push XR tracking state.

Parameters
cxrError cxrGetConnectionStats(cxrReceiverHandle receiver, cxrConnectionStats *stats)

Get Connection statistics during the lifetime of the session.

Note

For best results it is reccommended to poll this API no more than once per second.

Parameters

API Structures

enum cxrConnectionQuality

Values:

enumerator cxrConnectionQuality_Unstable = 0

Initial value while estimating quality. Thereafter, expect disconnects. Details in cxrConnectionQualityReasons.

enumerator cxrConnectionQuality_Bad = 1

Expect very low bitrate and/or high latency. Details in cxrConnectionQualityReasons.

enumerator cxrConnectionQuality_Poor = 2

Expect low bitrate and/or high latency. Details in cxrConnectionQualityReasons.

enumerator cxrConnectionQuality_Fair = 3

Expect frequent impact on bitrate or latency. Details in cxrConnectionQualityReasons.

enumerator cxrConnectionQuality_Good = 4

Expect ocassional impacts on bitrate or latency.

enumerator cxrConnectionQuality_Excellent = 5

Expect infrequent impacts on bitrate or latency.

enum cxrConnectionQualityReason

Values:

enumerator cxrConnectionQualityReason_EstimatingQuality = 0x0

Inital value while estimating quality.

enumerator cxrConnectionQualityReason_LowBandwidth = 0x1

The percentage of unutilized bandwidth is too low to maintain bitrate.

enumerator cxrConnectionQualityReason_HighLatency = 0x2

The round trip time is too high to maintain low latency.

enumerator cxrConnectionQualityReason_HighPacketLoss = 0x4

The packet loss is too high to overcome without re-transmission.

enum cxrTrackedDeviceProperty

Values:

enumerator Prop_CloudXRServerState_Int32 = 10100
enumerator Prop_ArLightColor_Vector3
enumerator Prop_ArLightDirection_Vector3
enumerator Prop_ArAmbientLightSh0_Vector3
enum cxrDeviceActivityLevel

Device Active/Idle State.

Values:

enumerator cxrDeviceActivityLevel_Unknown = -1

Unknown state.

enumerator cxrDeviceActivityLevel_Idle = 0

No activity for the last 10 seconds.

enumerator cxrDeviceActivityLevel_UserInteraction = 1

Activity is happening now (movement or prox sensor)

enumerator cxrDeviceActivityLevel_UserInteraction_Timeout = 2

No activity for the last 0.5 seconds.

enumerator cxrDeviceActivityLevel_Standby = 3

Idle for at least 5 seconds (configurable in Settings : Power Management)

enum cxrTrackingResult

Values:

enumerator cxrTrackingResult_Uninitialized = 1

Tracking hasn’t been initialized yet.

enumerator cxrTrackingResult_Calibrating_InProgress = 100

Calibration in progress.

enumerator cxrTrackingResult_Calibrating_OutOfRange = 101

Devices are outside of the calibration range.

enumerator cxrTrackingResult_Running_OK = 200

Tracking is running OK.

enumerator cxrTrackingResult_Running_OutOfRange = 201

Devices are out of the tracking range.

enumerator cxrTrackingResult_Fallback_RotationOnly = 300

Tracking is limited to rotation-only, usually IMU-based, as a fallback.

enum cxrButtonId

Values:

enumerator cxrButton_System
enumerator cxrButton_ApplicationMenu
enumerator cxrButton_Grip_Touch
enumerator cxrButton_Grip_Click
enumerator cxrButton_Trigger_Touch
enumerator cxrButton_Trigger_Click
enumerator cxrButton_Touchpad_Touch
enumerator cxrButton_Touchpad_Click
enumerator cxrButton_Joystick_Touch
enumerator cxrButton_Joystick_Click
enumerator cxrButton_A
enumerator cxrButton_B
enumerator cxrButton_X = cxrButton_A
enumerator cxrButton_Y = cxrButton_B
enumerator cxrButton_Num
enum cxrAnalogId

Values:

enumerator cxrAnalog_Trigger
enumerator cxrAnalog_TouchpadX
enumerator cxrAnalog_TouchpadY
enumerator cxrAnalog_JoystickX
enumerator cxrAnalog_JoystickY
enumerator cxrAnalog_Grip
enumerator cxrAnalog_Grip_Force
enumerator cxrAnalog_Num
enum cxrControllerId

Values:

enumerator cxrController_Left = 0
enumerator cxrController_Right = 1
enum cxrUniverseOrigin

Values:

enumerator cxrUniverseOrigin_Seated
enumerator cxrUniverseOrigin_Standing
enum cxrHmdTrackingFlags

Values:

enumerator cxrHmdTrackingFlags_HasProjection = 0x00000001

Tracking state has updated projection parameters.

enumerator cxrHmdTrackingFlags_HasIPD = 0x00000002

Tracking state has updated IPD.

enumerator cxrHmdTrackingFlags_HasRefresh = 0x00000004

Tracking state has updated refresh rate.

enumerator cxrHmdTrackingFlags_HasPoseID = 0x00000008

Tracking state contains a 64-bit pose ID.

enum cxrControllerType

Values:

enumerator cxrControllerType_HtcVive
enumerator cxrControllerType_ValveIndex
enumerator cxrControllerType_OculusTouch
enumerator cxrControllerType_None
enum cxrDeliveryType

Values:

enumerator cxrDeliveryType_Mono_RGB
enumerator cxrDeliveryType_Mono_RGBA
enumerator cxrDeliveryType_Stereo_RGB
enum cxrStreamingMode

Values:

enumerator cxrStreamingMode_XR
enumerator cxrStreamingMode_Generic
enum cxrFoveationMode

Values:

enumerator cxrFoveation_PiecewiseQuadratic = 0
enum cxrGraphicsContextType

Values:

enumerator cxrGraphicsContext_D3D11
enumerator cxrGraphicsContext_D3D12
enumerator cxrGraphicsContext_GL
enumerator cxrGraphicsContext_GLES
enumerator cxrGraphicsContext_Vulkan
enumerator cxrGraphicsContext_Metal
enumerator cxrGraphicsContext_Cuda
enumerator cxrGraphicsContext_NvMedia
enumerator cxr_GraphicsContext_Max = ~0
enum cxrDebugFlags

These bitfield masks denote various debugging flags handled by either the Receiver or by the Server. Note that many of these may have some significant performance impact either constantly or at some interval.

Values:

enumerator cxrDebugFlags_LogVerbose = 0x00000001

record very verbose output

enumerator cxrDebugFlags_LogQuiet = 0x00000002

do not open normal log files at all

enumerator cxrDebugFlags_LogPrivacyDisabled = 0x00000010

disable any privacy filtering in output

enumerator cxrDebugFlags_TraceLocalEvents = 0x00000100

record trace of local event timing

enumerator cxrDebugFlags_TraceStreamEvents = 0x00000200

record trace of c/s stream event timing

enumerator cxrDebugFlags_TraceQosStats = 0x00000400

record QoS statistics

enumerator cxrDebugFlags_DumpImages = 0x00001000

Dump images from stream.

enumerator cxrDebugFlags_DumpAudio = 0x00002000

Dump audio from stream.

enumerator cxrDebugFlags_EmbedServerInfo = 0x00004000

server embeds stats into frame buffers for streaming

enumerator cxrDebugFlags_EmbedClientInfo = 0x00008000

client embeds stats into frame buffers or overlays

enumerator cxrDebugFlags_CaptureServerBitstream = 0x00010000

record the server-sent video bitstream

enumerator cxrDebugFlags_CaptureClientBitstream = 0x00020000

record the client-received video bitstream

enumerator cxrDebugFlags_FallbackDecoder = 0x00100000

try to use a fallback decoder for platform

enumerator cxrDebugFlags_EnableSXRDecoder = 0x00200000

[ANDROID only] enable the experimental SXR decoder

enumerator cxrDebugFlags_EnableAImageReaderDecoder = 0x00400000

[ANDROID only] enable the AImageReader decoder

enumerator cxrDebugFlags_OutputLinearRGBColor = 0x00800000

[ANDROID only] cxrBlitFrame output will be linear instead of sRGB

enum cxrServerState

Values:

enumerator cxrServerState_NotRunning = 0

Initial state, not yet running.

enumerator cxrServerState_Connecting = 1

Server is connecting to client, finished the RTSP handshake.

enumerator cxrServerState_Running = 2

Server is connected and ready to accept video and audio input for streaming

enumerator cxrServerState_HMD_Active = 3

[VR only] HMD is active

enumerator cxrServerState_HMD_Idle = 4

[VR only] HMD is idle

enumerator cxrServerState_Disconnected = 5

Server is disconnected from the client.

enumerator cxrServerState_Error = 6

Server in an error state.

enum cxrClientState

Values:

enumerator cxrClientState_ReadyToConnect = 0

Initial state, no connection attempt pending.

enumerator cxrClientState_ConnectionAttemptInProgress = 1

Attempting to connect to server.

enumerator cxrClientState_ConnectionAttemptFailed = 2

Error occurred during connection attempt.

enumerator cxrClientState_StreamingSessionInProgress = 3

Connected, streaming session in progress.

enumerator cxrClientState_Disconnected = 4

Streaming session has ended.

enumerator cxrClientState_Exiting = 5

Client is shutting down.

enum cxrNetworkInterface

Values:

enumerator cxrNetworkInterface_Unknown = 0

Network interface is unknown.

enumerator cxrNetworkInterface_Ethernet = 1

Network interface is Ethernet.

enumerator cxrNetworkInterface_WiFi5Ghz = 2

Network interface is 5GHz Wi-Fi.

enumerator cxrNetworkInterface_WiFi24Ghz = 3

Network interface is 2.4GHz Wi-Fi.

enumerator cxrNetworkInterface_MobileLTE = 4

Network interface is mobile LTE.

enumerator cxrNetworkInterface_Mobile5G = 5

Network interface is mobile 5G.

enum cxrNetworkTopology

Values:

enumerator cxrNetworkTopology_Unknown = 0

Client Server connection unknown.

enumerator cxrNetworkTopology_LAN = 1

Client and Server are connected over LAN.

enumerator cxrNetworkTopology_WAN = 2

Client and Server are connected over WAN.

enum cxrStateReason

Values:

enumerator cxrStateReason_NoError = 0
enumerator cxrStateReason_HEVCUnsupported = 1
enumerator cxrStateReason_VersionMismatch = 2
enumerator cxrStateReason_DisabledFeature = 3
enumerator cxrStateReason_RTSPCannotConnect = 4
enumerator cxrStateReason_HolePunchFailed = 5
enumerator cxrStateReason_NetworkError = 6
enumerator cxrStateReason_AuthorizationFailed = 7
enumerator cxrStateReason_DeviceDescriptorMismatch = 8
enumerator cxrStateReason_DisconnectedExpected = 100

The server signalled it was disconnecting to the client properly before closing the connection.

enumerator cxrStateReason_DisconnectedUnexpected = 101

The connection to the server abruptly terminated without any notice.

enum cxrError

Values:

enumerator cxrError_Success = 0
enumerator cxrError_Failed = 1
enumerator cxrError_No_Addr = 2
enumerator cxrError_No_Share_Context = 3
enumerator cxrError_Incompatible_Share_Context = 4
enumerator cxrError_Frame_Not_Released = 5
enumerator cxrError_Frame_Not_Latched = 6
enumerator cxrError_Receiver_Not_Running = 7
enumerator cxrError_Decoder_No_Texture = 8
enumerator cxrError_Decoder_Frame_Not_Ready = 9
enumerator cxrError_Receiver_Invalid = 10
enumerator cxrError_Timeout = 11
enumerator cxrError_Frame_Invalid = 12
enumerator cxrError_Unsupported_Version = 13
enumerator cxrError_Chaperone_Invalid = 14
enumerator cxrError_Not_Implemented = 15
enumerator cxrError_Parameter_Invalid = 16
enumerator cxrError_Frame_Not_Ready = 17
enumerator cxrError_No_Decoder = 18
enumerator cxrError_Could_Not_Connect_To_Server = 19
enumerator cxrError_Universe_ID_Invalid = 20
enumerator cxrError_Streamer_Not_Ready = 21
enumerator cxrError_Server_Has_No_Client = 22
enumerator cxrError_Device_Description_Not_Received = 23
enumerator cxrError_Invalid_Stream_Count = 24
enumerator cxrError_Module_Load_Failed = 25
enumerator cxrError_ConnectionAlreadyInProgress = 26
enumerator cxrError_ClientRequestedExit = 27
enumerator cxrError_PoseNotInPushMode = 28
enumerator cxrError_AuthorizationHeader_Invalid = 29
enumerator cxrError_No_Receiver_Desc = 30
enumerator cxrError_Audio_Frame_Unsupported_Size = 31
enumerator cxrError_No_Connection_Desc = 32
enumerator cxrError_Max = ~0u
typedef struct cxrReceiver *cxrReceiverHandle

CloudXR SDK client interface.

The Receiver is the primary interface handle for a client of the CloudXR SDK to connect to a server, describe client device properties, send position and input updates, stream live video/audio, and acquire video frames to render out locally.

typedef uint8_t cxrBool
typedef void *cxrTextureHandle
const uint32_t cxrFrameMask_Left = 0x01

Maps to index/stream 0 for stereo modes.

const uint32_t cxrFrameMask_Right = 0x02

Maps to index/stream 1 for stereo modes.

const uint32_t cxrFrameMask_Special = 0x80000000

Special-case masks that aren’t direct indices are noted by setting this bit.

const uint32_t cxrFrameMask_All = 0xFFFFFFFF

Requests the system map to all available frames.

const unsigned int CXR_MAX_AMBIENT_LIGHT_SH = 9
const int CXR_NUM_CONTROLLERS = 2
const uint32_t CXR_AUDIO_CHANNEL_COUNT = 2

Audio is currently always stereo.

const uint32_t CXR_AUDIO_SAMPLE_SIZE = sizeof(int16_t)

Audio is currently singed 16-bit samples (little-endian)

const uint32_t CXR_AUDIO_SAMPLING_RATE = 48000

Audio is currently always 48khz.

const uint32_t CXR_AUDIO_FRAME_LENGTH_MS = 5

Sent audio has a 5 ms default frame length. Received audio has 5 or 10 ms frame length, depending on the configuration.

const uint32_t CXR_AUDIO_BYTES_PER_MS = CXR_AUDIO_CHANNEL_COUNT * CXR_AUDIO_SAMPLE_SIZE * CXR_AUDIO_SAMPLING_RATE / 1000

Total bytes of audio per ms.

const char *const cxrUserDataFileName = "CloudXR User Data"
const char *const cxrUserDataMutexName = "CloudXR User Data Mutex"
const uint32_t cxrUserDataMaxSize = 8 * 1024
inline uint32_t ButtonMaskFromId(cxrButtonId id)
const char *cxrErrorString(cxrError E)
cxrFalse 0
cxrTrue 1
CXR_MAX_NUM_VIDEO_STREAMS 6

max number of video streams supported for Receiver_Generic mode

CXR_NUM_VIDEO_STREAMS_XR 2

In Receiver_XR mode number of streams is always 2.

CLOUDXR_LOG_MAX_DEFAULT -1

Constant for logging to use a default setting.

struct cxrClientCallbacks
#include <CloudXRClient.h>

Callback functions for the Receiver to interact with client code.

These functions are used to either request something from the client or to provide data or notifications to the client.

Public Members

void (*GetTrackingState)(void *context, cxrVRTrackingState *trackingState)

Return HMD and controller states and poses. Called at a fixed frequency by the Receiver, as specified by cxrDeviceDesc::posePollFreq. This callback must be implemented for the server to render changing position and orientation of client device and controller(s).

void (*TriggerHaptic)(void *context, const cxrHapticFeedback *haptic)

Notify the client it should trigger controller vibration.

cxrBool (*RenderAudio)(void *context, const cxrAudioFrame *audioFrame)

Notify the client to play out the passed audio buffer.

Returns

cxrTrue if data consumed/played, cxrFalse if cannot play or otherwise discarded

void (*ReceiveUserData)(void *context, const void *data, uint32_t size)

Reserved for Future Use

void (*UpdateClientState)(void *context, cxrClientState state, cxrStateReason reason)

Notify the client of underlying state changes and why the changed occurred, for both abnormal and expected cases. This callback must be implemented if you call cxrConnect() with the async flag set in cxrConnnectionDesc in order to be notified of connection state changes in the background thread.

struct cxrReceiverDesc
#include <CloudXRClient.h>

This contains details of the client device and overall session characteristics. It is passed to cxrCreateReceiver for construction of the cxrReceiverHandle instance and connection to server for streaming.

Public Members

uint32_t requestedVersion

Must set to CLOUDXR_VERSION_DWORD.

cxrDeviceDesc deviceDesc

Describes the client device hardware.

cxrClientCallbacks clientCallbacks

Pointers to client callback functions (NULL for unsupported callbacks)

void *clientContext

App-specific pointer passed back to client in all callback functions.

const cxrGraphicsContext *shareContext

The API-specific client graphics context to be shared with CloudXR.

Note

On certain graphics APIs, such as DirectX, the share context may be NULL. However, the share context cannot be NULL on OpenGL ES on Android devices.

uint32_t numStreams

Number of video streams to open. Ignored for XR which is always 2.

cxrStreamingMode receiverMode

Request XR (VR/AR) mode (usually 2 streams), or generic mode (1 or more streams)

uint32_t debugFlags

Features to aid debugging (see cxrDebugFlags)

int32_t logMaxSizeKB

Maximum size for the client log in KB. -1 for default, 0 to disable size limit.

int32_t logMaxAgeDays

Delete log and diagnostic files older than this. -1 for default, 0 to disable.

struct cxrConnectionStats
#include <CloudXRClient.h>

This structure is passed into cxrGetConnectionStats. There are three categories of statistics:

The frame stats relate to the timing of video frames as they move from server to client and are prefixed with frame.

The network stats relate to the performance of the connection between server and client and are prefixed with bandwidth, roundTrip, jitter and totalPackets.

The quality stats relate to the overall health of the connection and are prefixed with quality.

Public Members

float framesPerSecond

The average number of frames per second.

float frameDeliveryTime

The average time between a frame being submitted on the server and getting latched and released on the client.

float frameQueueTime

The average time a frame spends queued on the client before it is latched and released.

float frameLatchTime

The average time the client application spends waiting for a frame to be latched.

uint32_t bandwidthAvailableKbps

The estimated available bandwidth from server to client.

uint32_t bandwidthUtilizationKbps

The average video streaming rate from server to client.

uint32_t bandwidthUtilizationPercent

The estimated bandwidth utilization percent from server to client.

uint32_t roundTripDelayMs

The estimated network round trip delay between server and client in milliseconds.

uint32_t jitterUs

The estimated jitter from server to client in microseconds.

uint32_t totalPacketsReceived

The cumulative number of video packets received on the client.

uint32_t totalPacketsLost

The cumulative number of video packets lost in transit from server to client.

uint32_t totalPacketsDropped

The cumulative number of video packets dropped without getting displayed on the client.

cxrConnectionQuality quality

The quality of the connection as one of the five values in cxrConnectionQuality.

Note

If the quality is cxrConnectionQuality_Fair the qualityReasons flags will be populated.

uint32_t qualityReasons

The reasons for connection quality as one or more cxrConnectionQualityReason flags.

struct cxrConnectionDesc

Public Members

cxrBool async

Calls to cxrConnect will spawn a background thread to attempt the connection and return control. to calling thread immediately without blocking until a connection is established or fails.

uint32_t maxVideoBitrateKbps

Bitrate for all video traffic is capped at this value. A value of 0 means unlimited.

cxrNetworkInterface clientNetwork

Network adapter type used by the client to connect to the server.

cxrNetworkTopology topology

Topology of the connecton between Client and Server.

struct cxrMatrix34
#include <CloudXRCommon.h>

CloudXR uses a right-handed system, where: +y is up +x is to the right -z is forward Distance units are in meters.

struct cxrVector2
struct cxrVector3

Public Members

float v[3]

x, y, z values of the vector.

struct cxrQuaternion

Public Members

float w

w value.

float x

x value.

float y

y value.

float z

z value.

struct cxrLightProperties
struct cxrChaperone
struct cxrTrackedDevicePose

Public Members

cxrVector3 position

Device 3D position.

cxrQuaternion rotation

Normalized quaternion representing the orientation.

cxrVector3 velocity

Device velocity in tracker space in m/s.

cxrVector3 angularVelocity

Device angular velocity in radians/s.

cxrTrackingResult trackingResult

Device’s tracking result.

cxrBool poseIsValid

Whether this pose is valid or not.

cxrBool deviceIsConnected

Whether the device is physically connected or not.

struct cxrHmdTrackingState

Public Members

uint64_t flags

A bitwise-mask of values from cxrHmdTrackingFlags

float proj[2][4]

If cxrHmdTrackingFlags_HasProjection is set, allows you to update the projection parameters specified in the device description at a per-pose granularity.

float ipd

If cxrHmdTrackingFlags_HasIPD is set, allows you to update the headset interpupilary distance parameters specified in the device description at a per-pose granularity.

float displayRefresh

If cxrHmdTrackingFlags_HasRefresh is set, overrides the headset display target refresh/fps specified in the device description (up to per-pose granularity).

uint64_t poseID

A user-specified 64-bit value associated with this pose. The same value will be delivered to the client in the poseID of the cxrFramesLatched structure associated with this pose.

cxrTrackedDevicePose pose

The headset’s 3D pose.

cxrDeviceActivityLevel activityLevel

The headset’s activity level.

struct cxrControllerTrackingState

Public Members

cxrTrackedDevicePose pose

The controller’s 3D pose.

uint32_t booleanComps

A bitmask indicating which buttons are pressed.

uint32_t booleanCompsChanged

A bitmask indicating which buttons had their state change since the last controller state.

float scalarComps[cxrAnalog_Num]

An array of scalars indicating the value for analog inputs, normalized to the range [0, 1.0f].

struct cxrVRTrackingState

Public Members

cxrHmdTrackingState hmd

Tracking state for the headset.

cxrControllerTrackingState controller[CXR_NUM_CONTROLLERS]

Tracking state for left / right hand controller, index 0 is the left hand.

float poseTimeOffset

Offset in seconds from the actual time of the pose that affects the amount of pose extrapolation. Default is 0.

struct cxrDeviceDesc

Public Members

cxrDeliveryType deliveryType

Tells server that client expects mono or stereo frames, and RGB or RGBA format.

uint32_t width

Requested render width, typically this is display width.

uint32_t height

Requested render height, typically this is display height.

Note

Width and height should be even values, ideally a multiple of 32.

float maxResFactor

Suggested maximum oversampling size on server. Server downsamples larger res to this. Valid range 0.5-2.0, with 1.2 as a common value.

float fps

Device display refresh rate, client needs server to provide stream at this rate.

float ipd

Inter-pupillary distance.

float proj[2][4]

Per eye raw projection extents: tangents of the half-angles from the center view axis. 0|1 for left|right eye, then 0-3 for left, right, top, bottom edges.

float predOffset

A time offset in seconds to adjust the server time prediction model to account for device-specific delay rendering stream to screen.

cxrBool receiveAudio

This device can receive and play audio FROM the server (e.g. game/app sounds)

cxrBool sendAudio

This device can send captured audio TO the server (e.g. microphone)

cxrBool embedInfoInVideo

Request the server embed debug information in each frame prior to encoding.

cxrBool disablePosePrediction

Use the raw client-provided pose without any pose extrapolation.

cxrBool angularVelocityInDeviceSpace

True if angular velocity in device space, false if in world space.

cxrBool disableVVSync

Disables VVSync and instead runs server at fixed frame rate based on client fps.

uint32_t foveatedScaleFactor

Request server foveate rendered frames at % of display res. Values [25-100], zero to disable. 50 is reasonable for most uses.

uint32_t posePollFreq

Frequency to poll pose updates. Set 0 for default, or rate per second to invoke polling. Default is 250, maximum is 1000. Recommend at least 2x display refresh.

cxrControllerType ctrlType

Which pre-defined controller type should be emulated for this device.

uint32_t foveationModeCaps

A bitmask of supported foveation modes (1 bit per cxrFoveationMode enum value)

cxrChaperone chaperone

SteamVR-equivalent chaperone or ‘play space’.

float maxClientQueueSize

Maximum size of the decoded frame FIFO queue on the client(unit is frames)

struct cxrHapticFeedback
struct cxrGraphicsContext
struct cxrVideoFrame

Public Members

cxrTextureHandle texture

This frame’s texture handle can be cast to a platform texture when needed.

uint32_t width

Width of frame in texels.

uint32_t height

Height of frame in texels.

uint32_t pitch

Width of frame in bytes.

uint32_t widthFinal

Final width of frame after internal transforms, such as de-foveation.

uint32_t heightFinal

Final height of frame after internal transforms, such as de-foveation.

uint32_t streamIdx

Index of video stream this frame comes from.

uint64_t timeStamp

Timestamp when the frame was captured on the server.

struct cxrFramesLatched
#include <CloudXRCommon.h>

This structure is passed into cxrLatchFrame(), and if the latch succeeds it will contain data for the latched frames. The structure’s data must be freed by passing to cxrReleaseFrame() when done using it.

Public Members

uint32_t count

The number of frames latched/acquired.

cxrVideoFrame frames[CXR_MAX_NUM_VIDEO_STREAMS]

The video frame data for each frame latched.

cxrMatrix34 poseMatrix

The device position at that moment in time.

uint64_t poseID

The user-specified 64-bit value that was passed in the cxrHmdTrackingState structure and that is associated with the headset pose used for rendering this frame.

struct cxrAudioFrame