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
receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()
-
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
receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()
framesLatched – [inout] pointer to a cxrFramesLatched struct that was filled by cxrLatchFrame.
-
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
receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()
trackingState – [in] A filled-out struct containing the tracking state to send (see cxrVRTrackingState).
-
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
receiver – [in] cxrReceiverHandle handle from cxrCreateReceiver()
stats – [out] A struct to fill-in with the current connection statistics (see cxrConnectionStats).
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.
-
enumerator cxrConnectionQuality_Unstable = 0¶
-
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.
-
enumerator cxrConnectionQualityReason_EstimatingQuality = 0x0¶
-
enum cxrTrackedDeviceProperty¶
Values:
-
enumerator Prop_CloudXRServerState_Int32 = 10100¶
-
enumerator Prop_ArLightColor_Vector3¶
-
enumerator Prop_ArLightDirection_Vector3¶
-
enumerator Prop_ArAmbientLightSh0_Vector3¶
-
enumerator Prop_CloudXRServerState_Int32 = 10100¶
-
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)
-
enumerator cxrDeviceActivityLevel_Unknown = -1¶
-
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.
-
enumerator cxrTrackingResult_Uninitialized = 1¶
-
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¶
-
enumerator cxrButton_System¶
-
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¶
-
enumerator cxrAnalog_Trigger¶
-
enum cxrControllerId¶
Values:
-
enumerator cxrController_Left = 0¶
-
enumerator cxrController_Right = 1¶
-
enumerator cxrController_Left = 0¶
-
enum cxrUniverseOrigin¶
Values:
-
enumerator cxrUniverseOrigin_Seated¶
-
enumerator cxrUniverseOrigin_Standing¶
-
enumerator cxrUniverseOrigin_Seated¶
-
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.
-
enumerator cxrHmdTrackingFlags_HasProjection = 0x00000001¶
-
enum cxrControllerType¶
Values:
-
enumerator cxrControllerType_HtcVive¶
-
enumerator cxrControllerType_ValveIndex¶
-
enumerator cxrControllerType_OculusTouch¶
-
enumerator cxrControllerType_None¶
-
enumerator cxrControllerType_HtcVive¶
-
enum cxrDeliveryType¶
Values:
-
enumerator cxrDeliveryType_Mono_RGB¶
-
enumerator cxrDeliveryType_Mono_RGBA¶
-
enumerator cxrDeliveryType_Stereo_RGB¶
-
enumerator cxrDeliveryType_Mono_RGB¶
-
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¶
-
enumerator cxrGraphicsContext_D3D11¶
-
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
-
enumerator cxrDebugFlags_LogVerbose = 0x00000001¶
-
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.
-
enumerator cxrServerState_NotRunning = 0¶
-
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.
-
enumerator cxrClientState_ReadyToConnect = 0¶
-
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.
-
enumerator cxrNetworkInterface_Unknown = 0¶
-
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.
-
enumerator cxrNetworkTopology_Unknown = 0¶
-
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.
-
enumerator cxrStateReason_NoError = 0¶
-
enum cxrError¶
Values:
-
enumerator cxrError_Success = 0¶
-
enumerator cxrError_Failed = 1¶
-
enumerator cxrError_No_Addr = 2¶
-
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¶
-
enumerator cxrError_Success = 0¶
-
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)¶
-
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.
-
void (*GetTrackingState)(void *context, cxrVRTrackingState *trackingState)¶
-
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.
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.
-
uint32_t requestedVersion¶
-
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.
-
float framesPerSecond¶
-
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.
-
cxrBool async¶
-
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 cxrQuaternion¶
-
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.
-
cxrVector3 position¶
-
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.
-
uint64_t flags¶
-
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].
-
cxrTrackedDevicePose pose¶
-
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.
-
cxrHmdTrackingState hmd¶
-
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 embedInfoInVideo¶
Request the server embed debug information in each frame prior to encoding.
-
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)
-
cxrDeliveryType deliveryType¶
-
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.
-
cxrTextureHandle texture¶
-
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.
-
uint32_t count¶
-
struct cxrAudioFrame¶