CloudXR SDK API¶

这是一个关于 CloudXR 函数、结构和变量的高级参考。有关如何使用的更深入详细信息，请参阅关于客户端开发的章节。

API 函数¶

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

初始化 CloudXR 客户端并创建 Receiver 句柄，供所有其他 API 调用使用。

注意

返回的 cxrReceiverHandle 必须作为第一个参数传递给所有其他 CloudXR 客户端 API 调用。

参数

description – [in] 已填写的客户端接收器描述符结构 (参见 cxrReceiverDesc)。
receiver – [out] 指向返回给客户端的不透明句柄的指针，该句柄表示 Receiver 接口。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Invalid_API_Version

请求的客户端库版本无效

返回 cxrError_Invalid_Number_Of_Streams

对于请求的模式，请求的流数量无效

返回 cxrError_Invalid_Device_Descriptor

提供的设备描述符无效

返回 cxrError_Invalid_Graphics_Context

图形上下文对于操作系统/平台无效

返回 cxrError_Decoder_Setup_Failed

无法实例化平台特定的解码器

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

建立与 CloudXR 服务器的连接。

参数

receiver – [in] 从 cxrCreateReceiver() 获取的 cxrReceiverHandle 句柄。
serverAddr – [in] CloudXR 服务器的 IP 地址。
description – [in] 控制连接行为的可选设置（参见 cxrConnectionDesc）。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Not_Connected

接收器已启动异步连接，但尚未完成

返回 cxrError_Module_Load_Failed

无法加载流媒体库

返回 cxrError_Client_Setup_Failed

无法初始化流媒体库

返回 cxrError_Client_Version_Old

客户端版本对于服务器而言过旧

返回 cxrError_Client_Unauthorized

客户端授权标头被拒绝

返回 cxrError_Server_Handshake_Failed

客户端无法完成与服务器的握手（这可能是由于地址不正确、RTSP 端口被阻止或网络暂时中断）

返回 cxrError_Server_Version_Old

服务器版本对于客户端而言过旧

返回 cxrError_Server_Feature_Disabled_*

服务器禁用了请求的功能（HEVC、VVSync、姿势预测、发送音频或接收音频）

void cxrDestroyReceiver(cxrReceiverHandle receiver)¶

终止流会话并释放关联的 CloudXR 资源。

注意

Receiver 句柄在此调用返回后无效。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄

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

从网络流中获取下一个可用的解码视频帧。

此调用尝试同步获取 streamMask 中所有流的下一个可用解码视频帧。可以使用不同的掩码重复调用它，以便在没有并发锁定的情况下获取帧。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
framesLatched – [inout] 指向 cxrFramesLatched 结构的指针，其生命周期到 cxrReleaseFrame 为止。
frameMask – [in] 位字段掩码，对于通用帧设置为 1<<[帧号]，或使用特殊值，如 cxrFrameMask_All。
timeoutMs – [in] 等待帧的最长时间（以毫秒为单位），超过此时间后将返回错误。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Not_Connected

接收器尚未连接

返回 cxrError_Not_Streaming

服务器尚未开始流式传输

返回 cxrError_Frames_Not_Released

存在先前已闩锁但尚未释放的帧

返回 cxrError_Frames_Not_Ready

在请求的超时时间内无法闩锁帧

返回 cxrError_Frame_Not_Latched

存在平台特定的解码器问题

返回 cxrError_Decoder_No_Texture

解码器无法获取用于解码的纹理

返回 cxrError_Decoder_Frame_Not_Ready

解码帧尚未准备好被闩锁

cxrError cxrBlitFrame(cxrReceiverHandle receiver, cxrFramesLatched *framesLatched, uint32_t frameMask)¶

仅限安卓 将掩码设置的已闩锁视频帧渲染到当前绑定的目标表面。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
framesLatched – [inout] 指向 cxrFramesLatched 结构的指针，其生命周期到 cxrReleaseFrame 为止。
frameMask – [in] 位字段掩码，对于通用帧设置为 1<<[帧号]，或使用特殊值，如 cxrFrameMask_Mono_With_Alpha。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Invalid_Number_Of_Streams

闩锁帧计数或帧掩码包含无效值

cxrError cxrReleaseFrame(cxrReceiverHandle receiver, cxrFramesLatched *framesLatched)¶

从 cxrLatchFrame 释放先前闩锁的一组视频帧。

注意

cxrFramesLatched 数据在此调用返回后无效。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
framesLatched – [inout] 指向由 cxrLatchFrame 填充的 cxrFramesLatched 结构的指针。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Frames_Not_Latched

没有要释放的已闩锁帧

cxrError cxrAddController(cxrReceiverHandle receiver, const cxrControllerDesc *desc, cxrControllerHandle *outHandle)¶

添加控制器。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
desc – [in] 用于标识/描述此控制器及其生成的输入的结构。
outHandle – [inout] 指向 cxrControllerHandle 的指针，该指针接收新添加控制器的句柄。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Controller_Id_In_Use

控制器描述中的 id 字段已用于另一个控制器

返回 cxrError_Role_Too_Long

描述的角色长于 CXR_MAX_CONTROLLER_ROLE

返回 cxrError_Name_Too_Long

描述的名称长于 CXR_MAX_CONTROLLER_NAME，或者输入路径长于 CXR_MAX_INPUT_PATH_LENGTH

返回 cxrError_Too_Many_Inputs

描述的输入计数大于 CXR_MAX_CONTROLLER_INPUT_COUNT

cxrError cxrSendControllerPoses(cxrReceiverHandle receiver, uint32_t poseCount, const cxrControllerHandle *controllerHandles, const cxrControllerTrackingState *const *states)¶

发送一个或多个控制器的多个姿势。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
poseCount – [in] 要发送的姿势数量。
controllerHandles – [in] 包含 poseCount 个控制器句柄的数组。
states – [in] 包含 poseCount 个控制器跟踪状态的数组。

返回 cxrError_Required_Parameter

缺少必需的参数之一

cxrError cxrFireControllerEvents(cxrReceiverHandle receiver, cxrControllerHandle controller, const cxrControllerEvent *events, uint32_t eventCount)¶

发送控制器的事件。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
controller – [in] 控制器的句柄。
events – [in] 包含 eventCount 个控制器事件的数组。
eventCount – [in] 要发送的事件数量。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Data_Too_Large

操作中的 blob 值超过 CXR_MAX_BLOB_BYTES_PER_INPUT 字节

cxrError cxrRemoveController(cxrReceiverHandle receiver, cxrControllerHandle handle)¶

移除控制器。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
handle – [in] 要移除的控制器的句柄。

返回 cxrError_Required_Parameter

缺少必需的参数之一

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

向服务器提供估计的世界照明属性。

这用于将 ARCore 或 ARKit 照明估计值发送到服务器，以便实时集成到 3D 渲染场景照明中。它支持主光源以及环境球谐函数。在服务器端，应用程序可以使用以下方法查询此数据

   IVRSystem::GetArrayTrackedDeviceProperty(cxrTrackedDeviceProperty)

返回 cxrError_Required_Parameter: 缺少必需的参数之一
返回 cxrError_Not_Connected: 接收器尚未连接

cxrError cxrSendInputEvent(cxrReceiverHandle receiver, const cxrInputEvent *inputEvent)¶

将非 VR 控制器输入事件发送到服务器以进行应用程序特定的处理。

返回 cxrError_Required_Parameter: 缺少必需的参数之一
返回 cxrError_Not_Connected: 接收器尚未连接

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

向跟踪时间线添加事件。

此函数允许将自定义事件插入到 CloudXR 的跟踪时间线中。请注意，要记录事件，必须调用此函数两次。

记录事件的示例：void foo() { cxrTraceEvent(“ButtonPressed”, 0x23, cxrTrue); … 在此处执行一些工作 … cxrTraceEvent(“ButtonPressed”, 0x23, cxrFalse); }

参数

name – [in] 要添加到时间线的事件名称
eventId – [in] 可用于在时间线中标识事件的自定义 Id 值
begin – [in] true 表示事件的开始，false 表示事件的结束。

cxrError cxrSendAudio(cxrReceiverHandle receiver, const cxrAudioFrame *audioFrame)¶

将客户端输入音频（即麦克风）发送到服务器。

注意

要使用此 API，请设置 sendAudio 布尔值（参见 cxrDeviceDesc）。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
audioFrame – [in] 包含要发送的音频数据的已填写结构（参见 cxrAudioFrame）。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Not_Connected

接收器尚未连接

返回 cxrError_Data_Too_Large

音频帧数据大于 64kb 的最大大小

cxrError cxrSetAuthorizationHeader(cxrReceiverHandle receiver, const char *header)¶

设置由服务器验证的授权标头。

此 API 允许客户端通过标头指定凭据，该标头在通过 HTTPS 连接到服务器之前交换。如果使用，则必须在 cxrCreateReceiver 之后和 cxrConnect 之前调用此 API。

注意

为了发送凭据，客户端操作系统必须信任服务器证书。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
header – [in] 在 cxrConnect() 期间发送到服务器的授权标头的值。

返回 cxrError_Required_Parameter

缺少必需的参数之一

cxrError cxrSendPose(cxrReceiverHandle receiver, const cxrVRTrackingState *trackingState)¶

显式推送 XR 跟踪状态。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
trackingState – [in] 包含要发送的跟踪状态的已填写结构（参见 cxrVRTrackingState）。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Not_Connected

接收器尚未连接

返回 cxrError_Pose_Callback_Provided

接收器配置为通过回调轮询姿势，而不是让客户端发送姿势

cxrError cxrGetConnectionStats(cxrReceiverHandle receiver, cxrConnectionStats *stats)¶

获取会话生命周期内的连接统计信息。

注意

为了获得最佳结果，建议每秒轮询此 API 的频率不超过一次。

参数

receiver – [in] 来自 cxrCreateReceiver() 的 cxrReceiverHandle 句柄
stats – [out] 用于填充当前连接统计信息的结构（参见 cxrConnectionStats）。

返回 cxrError_Required_Parameter

缺少必需的参数之一

返回 cxrError_Not_Connected

接收器尚未连接

API 结构¶

enum cxrConnectionQuality¶

值

enumerator cxrConnectionQuality_Unstable = 0¶: 估计质量时的初始值。此后，预计会断开连接。详细信息请参见 cxrConnectionQualityReason。

enumerator cxrConnectionQuality_Bad = 1¶: 预计比特率非常低和/或延迟很高。详细信息请参见 cxrConnectionQualityReason。

enumerator cxrConnectionQuality_Poor = 2¶: 预计比特率低和/或延迟高。详细信息请参见 cxrConnectionQualityReason。

enumerator cxrConnectionQuality_Fair = 3¶: 预计会频繁影响比特率或延迟。详细信息请参见 cxrConnectionQualityReason。

enumerator cxrConnectionQuality_Good = 4¶: 预计偶尔会影响比特率或延迟。

enumerator cxrConnectionQuality_Excellent = 5¶: 预计很少影响比特率或延迟。

enum cxrConnectionQualityReason¶

值

enumerator cxrConnectionQualityReason_EstimatingQuality = 0x0¶: 估计质量时的初始值。

enumerator cxrConnectionQualityReason_LowBandwidth = 0x1¶: 未利用带宽的百分比太低，无法维持比特率。

enumerator cxrConnectionQualityReason_HighLatency = 0x2¶: 往返时间太长，无法维持低延迟。

enumerator cxrConnectionQualityReason_HighPacketLoss = 0x4¶: 数据包丢失率太高，无法在不重新传输的情况下克服。

enum cxrTrackedDeviceProperty¶

CloudXR 特定 vr::ETrackedDeviceProperty 值的键。

值

enumerator Prop_CloudXRServerState_Int32 = 10100¶: CXR 服务器驱动程序的状态，如 cxrServerState。

enumerator Prop_ArLightColor_Vector3¶: 客户端 API cxrSendLightProperties 发送的主光源颜色。

enumerator Prop_ArLightDirection_Vector3¶: 客户端 API cxrSendLightProperties 发送的主光源方向。

enumerator Prop_ArAmbientLightSh0_Vector3¶: 第一个球谐分量，后跟客户端 API cxrSendLightProperties 发送的总共 CXR_MAX_AMBIENT_LIGHT_SH 个分量。

enum cxrDeviceActivityLevel¶

值

enumerator cxrDeviceActivityLevel_Unknown = -1¶: 未知状态。

enumerator cxrDeviceActivityLevel_Idle = 0¶: 最近 10 秒内无活动。

enumerator cxrDeviceActivityLevel_UserInteraction = 1¶: 当前正在进行活动（移动或接近传感器）。

enumerator cxrDeviceActivityLevel_UserInteraction_Timeout = 2¶: 最近 0.5 秒内无活动。

enumerator cxrDeviceActivityLevel_Standby = 3¶: 空闲至少 5 秒（可在“设置”>“电源管理”中配置）。

enum cxrTrackingResult¶

值

enumerator cxrTrackingResult_Uninitialized = 1¶: 跟踪尚未初始化。

enumerator cxrTrackingResult_Calibrating_InProgress = 100¶: 校准正在进行中。

enumerator cxrTrackingResult_Calibrating_OutOfRange = 101¶: 设备超出校准范围。

enumerator cxrTrackingResult_Running_OK = 200¶: 跟踪运行正常。

enumerator cxrTrackingResult_Running_OutOfRange = 201¶: 设备超出跟踪范围。

enumerator cxrTrackingResult_Fallback_RotationOnly = 300¶: 跟踪被限制为仅旋转，通常是基于 IMU 的，作为后备方案。

enum cxrUniverseOrigin¶

值

enumerator cxrUniverseOrigin_Seated¶: 表示用户处于坐姿。

enumerator cxrUniverseOrigin_Standing¶: 表示用户处于站姿。

enum cxrHmdTrackingFlags¶

值

enumerator cxrHmdTrackingFlags_HasProjection = 0x00000001¶: 跟踪状态已更新投影参数。

enumerator cxrHmdTrackingFlags_HasIPD = 0x00000002¶: 跟踪状态已更新 IPD。

enumerator cxrHmdTrackingFlags_HasRefresh = 0x00000004¶: 跟踪状态已更新刷新率。

enumerator cxrHmdTrackingFlags_HasPoseID = 0x00000008¶: 跟踪状态包含 64 位姿势 ID。

enumerator cxrHmdTrackingFlags_HasScaling = 0x00000010¶: 跟踪状态包含浮点比例。

enum cxrInputValueType¶

值

enumerator cxrInputValueType_blob = 1¶: 自由格式输入数据，大小不能超过 CXR_MAX_BLOB_BYTES_PER_INPUT。

enumerator cxrInputValueType_boolean = 2¶: 布尔输入数据。

enumerator cxrInputValueType_int32 = 3¶: Int32 输入数据。

enumerator cxrInputValueType_float32 = 4¶: Float32 输入数据。

enum cxrFoveationMode¶

值

enumerator cxrFoveation_PiecewiseQuadratic = 0¶

enum cxrClientSurfaceFormat¶

值

enumerator cxrClientSurfaceFormat_RGB¶: 32bpp 打包 R8B8G8X8，sRGB 色彩空间，不传输 Alpha 通道

enumerator cxrClientSurfaceFormat_RGBA¶: 32bpp 打包 R8B8G8A8，sRGB 色彩空间

enumerator cxrClientSurfaceFormat_NV12¶: 12bpp 打包 YUV 4:2:0 平面格式，交错色度，sRGB 色彩空间

enum cxrGraphicsContextType¶

值

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¶

这些位域掩码表示由接收器或服务器处理的各种调试标志。请注意，其中许多标志可能会持续或在一定间隔内对性能产生重大影响。

值

enumerator cxrDebugFlags_LogVerbose = 0x00000001¶: 记录非常详细的输出

enumerator cxrDebugFlags_LogQuiet = 0x00000002¶: 完全不打开普通日志文件

enumerator cxrDebugFlags_LogPrivacyDisabled = 0x00000010¶: 禁用输出中的任何隐私过滤

enumerator cxrDebugFlags_TraceLocalEvents = 0x00000100¶: 记录本地事件定时的跟踪

enumerator cxrDebugFlags_TraceStreamEvents = 0x00000200¶: 记录 c/s 流事件定时的跟踪

enumerator cxrDebugFlags_TraceQosStats = 0x00000400¶: 记录 QoS 统计信息

enumerator cxrDebugFlags_DumpImages = 0x00001000¶: 从流中转储图像。

enumerator cxrDebugFlags_DumpAudio = 0x00002000¶: 从流中转储音频。

enumerator cxrDebugFlags_EmbedServerInfo = 0x00004000¶: 服务器将统计信息嵌入到帧缓冲区中以进行流式传输

enumerator cxrDebugFlags_EmbedClientInfo = 0x00008000¶: 客户端将统计信息嵌入到帧缓冲区或覆盖层中

enumerator cxrDebugFlags_CaptureServerBitstream = 0x00010000¶: 记录服务器发送的视频比特流

enumerator cxrDebugFlags_CaptureClientBitstream = 0x00020000¶: 记录客户端接收的视频比特流

enumerator cxrDebugFlags_FallbackDecoder = 0x00100000¶: 尝试为平台使用回退解码器

enumerator cxrDebugFlags_EnableAImageReaderDecoder = 0x00400000¶: [仅限安卓] 启用 AImageReader 解码器

enumerator cxrDebugFlags_OutputLinearRGBColor = 0x00800000¶: [仅限安卓] cxrBlitFrame 输出将为线性而非 sRGB

enumerator cxrDebugFlags_DisableMultistreamQoS = 0x01000000¶: QoS 将在每个流上独立计算。

enum cxrServerState¶

值

enumerator cxrServerState_NotRunning = 0¶: 初始状态，尚未运行。

enumerator cxrServerState_Connecting = 1¶: 服务器正在连接到客户端，已完成 RTSP 握手。

enumerator cxrServerState_Running = 2¶: 服务器已连接并准备好接受视频和音频输入以进行流式传输

enumerator cxrServerState_HMD_Active = 3¶: [仅限 VR] HMD 已激活

enumerator cxrServerState_HMD_Idle = 4¶: [仅限 VR] HMD 处于空闲状态

enumerator cxrServerState_Disconnected = 5¶: 服务器已与客户端断开连接。

enumerator cxrServerState_Error = 6¶: 服务器处于错误状态。

enum cxrClientState¶

值

enumerator cxrClientState_ReadyToConnect = 0¶: 初始状态，没有挂起的连接尝试。

enumerator cxrClientState_ConnectionAttemptInProgress = 1¶: 正在尝试连接到服务器。

enumerator cxrClientState_ConnectionAttemptFailed = 2¶: 连接尝试期间发生错误。

enumerator cxrClientState_StreamingSessionInProgress = 3¶: 已连接，流会话正在进行中。

enumerator cxrClientState_Disconnected = 4¶: 流会话已结束。

enumerator cxrClientState_Exiting = 5¶: 客户端正在关闭。

enum cxrNetworkInterface¶

值

enumerator cxrNetworkInterface_Unknown = 0¶: 网络接口未知。

enumerator cxrNetworkInterface_Ethernet = 1¶: 网络接口是以太网。

enumerator cxrNetworkInterface_WiFi5Ghz = 2¶: 网络接口是 5GHz Wi-Fi。

enumerator cxrNetworkInterface_WiFi24Ghz = 3¶: 网络接口是 2.4GHz Wi-Fi。

enumerator cxrNetworkInterface_MobileLTE = 4¶: 网络接口是移动 LTE。

enumerator cxrNetworkInterface_Mobile5G = 5¶: 网络接口是移动 5G。

enum cxrNetworkTopology¶

值

enumerator cxrNetworkTopology_Unknown = 0¶: 客户端-服务器连接未知。

enumerator cxrNetworkTopology_LAN = 1¶: 客户端和服务器通过局域网连接。

enumerator cxrNetworkTopology_WAN = 2¶: 客户端和服务器通过广域网连接。

enum cxrError¶

值

enumerator cxrError_Success = 0x0¶: 操作成功。

enumerator cxrError_Group_General = 0x100¶: 大多数 API 函数可能返回的错误

enumerator cxrError_Failed = 0x101¶: 操作失败。

enumerator cxrError_Timeout = 0x102¶: 操作超时。

enumerator cxrError_Not_Connected = 0x103¶: 客户端未连接。

enumerator cxrError_Not_Streaming = 0x104¶: 客户端未进行流传输。

enumerator cxrError_Not_Implemented = 0x105¶: 该方法未实现。

enumerator cxrError_Required_Parameter = 0x106¶: 缺少必需的参数。

enumerator cxrError_Module_Load_Failed = 0x107¶: 库无法加载。

enumerator cxrError_Group_Validation = 0x200¶: 验证 API 输入参数时发生的错误

enumerator cxrError_Invalid_API_Version = 0x201¶: 请求的 API 版本无效。

enumerator cxrError_Invalid_Number_Of_Streams = 0x202¶: 流的数量无效。

enumerator cxrError_Invalid_Device_Descriptor = 0x203¶: 设备描述符无效。

enumerator cxrError_Invalid_Graphics_Context = 0x204¶: 图形上下文无效。

enumerator cxrError_Invalid_Video_Format = 0x205¶: 视频格式无效。

enumerator cxrError_Invalid_Video_Width = 0x206¶: 视频宽度无效。

enumerator cxrError_Invalid_Video_Height = 0x207¶: 视频高度无效。

enumerator cxrError_Invalid_Video_Fps = 0x208¶: 视频帧率无效。

enumerator cxrError_Invalid_Video_Max_Bitrate = 0x209¶: 视频最大比特率无效。

enumerator cxrError_Invalid_Frame_Mask = 0x20A¶: 帧掩码无效。

enumerator cxrError_Group_Server = 0x400¶: 源自服务器的错误

enumerator cxrError_Server_Setup_Failed = 0x401¶: 服务器设置失败。

enumerator cxrError_Group_Server_Connection = 0x410¶: 服务器问题导致的连接错误

enumerator cxrError_Server_Version_Old = 0x411¶: 服务器版本对于客户端来说太旧。

enumerator cxrError_Server_Untrusted_Certificate = 0x412¶: 客户端不信任服务器 SSL 证书。

enumerator cxrError_Server_Initiated_Disconnect = 0x413¶: 服务器发起断开连接。

enumerator cxrError_Server_Handshake_Failed = 0x414¶: 与服务器的握手失败。

enumerator cxrError_Server_Stream_Configuration_Failed = 0x415¶: 服务器无法设置为提供请求的流。

enumerator cxrError_Server_Firewall_Configuration_Failed = 0x416¶: 服务器防火墙无法通过打洞穿透。

enumerator cxrError_Group_Server_Feature_Disabled = 0x420¶: 由于服务器禁用的功能而导致的错误

enumerator cxrError_Server_Feature_Disabled_HEVC = 0x421¶: 服务器禁用了 HEVC 功能。

enumerator cxrError_Server_Feature_Disabled_VVSync = 0x422¶: 服务器禁用了 VVSync 功能。

enumerator cxrError_Server_Feature_Disabled_Pose_Prediction = 0x423¶: 服务器禁用了姿势预测功能。

enumerator cxrError_Server_Feature_Disabled_Send_Audio = 0x424¶: 服务器禁用了发送音频功能。

enumerator cxrError_Server_Feature_Disabled_Receive_Audio = 0x425¶: 服务器禁用了接收音频功能。

enumerator cxrError_Group_Client = 0x800¶: 源自客户端的错误

enumerator cxrError_Client_Setup_Failed = 0x801¶: 客户端设置失败。

enumerator cxrError_Group_Client_Connection = 0x810¶: 客户端问题导致的连接错误

enumerator cxrError_Client_Version_Old = 0x811¶: 客户端版本对于服务器来说太旧。

enumerator cxrError_Client_Unauthorized = 0x812¶: 客户端未被授权。

enumerator cxrError_Group_Frame = 0x1000¶: 帧生命周期中的错误

enumerator cxrError_Frame_Not_Released = 0x1001¶: 帧未被释放。

enumerator cxrError_Frame_Not_Latched = 0x1002¶: 帧未被锁存。

enumerator cxrError_Frame_Not_Ready = 0x1003¶: 帧未就绪。

enumerator cxrError_Group_Decoder = 0x2000¶: 解码器生命周期中的错误

enumerator cxrError_Decoder_Setup_Failed = 0x2001¶: 解码器设置失败。

enumerator cxrError_Decoder_No_Texture = 0x2002¶: 解码器无法获取纹理。

enumerator cxrError_Decoder_Frame_Not_Ready = 0x2003¶: 解码器尚未准备好帧。

enumerator cxrError_Group_Input = 0x4000¶: 向服务器发送姿势或输入时发生的错误

enumerator cxrError_Pose_Callback_Provided = 0x4001¶: 由于提供了回调，姿势无法发送。

enumerator cxrError_Name_Too_Long = 0x4002¶: 名称字符串超出最大大小。

enumerator cxrError_Too_Many_Inputs = 0x4003¶: 为单个控制器提供了太多输入。

enumerator cxrError_Controller_Id_In_Use = 0x4004¶: 控制器 ID 已被使用。

enumerator cxrError_Role_Too_Long = 0x4005¶: 控制器角色过长。

enumerator cxrError_Group_Data = 0x8000¶: 向服务器发送其他形式数据时发生的错误

enumerator cxrError_Data_Too_Large = 0x8001¶: 数据太大，无法发送。

enum cxrLogLevel¶

此枚举尝试以类似于各种平台（最初是 Android，但也受 iOS 和其他平台影响）的方式定义日志记录详细程度。

值

enumerator cxrLL_Verbose = 0¶

enumerator cxrLL_Debug = 1¶

enumerator cxrLL_Info = 2¶

enumerator cxrLL_Warning = 3¶

enumerator cxrLL_Error = 4¶

enumerator cxrLL_Critical = 5¶

enumerator cxrLL_Silence = 6¶: Silence 级别意味着完全不记录日志，不创建日志文件，我们只打印一行来注明此模式。

enum cxrMessageCategory¶

值

enumerator cxrMC_Correctness = 0¶

enumerator cxrMC_Performance = 1¶

typedef struct cxrReceiver *cxrReceiverHandle¶

CloudXR SDK 客户端接口。

*Receiver* 是 CloudXR SDK 客户端连接到服务器、描述客户端设备属性、发送位置和输入更新、流式传输实时视频/音频以及获取视频帧以在本地渲染的主要接口句柄。

typedef uint8_t cxrBool¶

typedef void *cxrControllerHandle¶

typedef void *cxrTextureHandle¶

typedef void (*cxrMessageCallbackFunc)(void *context, cxrLogLevel level, cxrMessageCategory category, void *extra, const char *tag, const char *const messageText)¶: 这是通用消息/日志回调函数的定义，在此声明以使其客户端和服务器实现具有相同的结构。

const uint32_t cxrFrameMask_Mono = 0x01¶: 映射到单声道模式的索引/流 0。

const uint32_t cxrFrameMask_Left = 0x01¶: 映射到立体声模式的索引/流 0。

const uint32_t cxrFrameMask_Right = 0x02¶: 映射到立体声模式的索引/流 1。

const uint32_t cxrFrameMask_Mono_With_Alpha = 0x01 | 0x02¶: 映射到带 Alpha 通道的单声道模式的索引/流 0。

const uint32_t cxrFrameMask_Left_With_Alpha = 0x01 | 0x02¶: 映射到带 Alpha 通道的立体声模式的索引/流 0。

const uint32_t cxrFrameMask_Right_With_Alpha = 0x04 | 0x08¶: 映射到带 Alpha 通道的立体声模式的索引/流 1。

const uint32_t cxrFrameMask_All = 0xFFFFFFFF¶: 请求系统映射到所有可用帧。

const unsigned int CXR_MAX_AMBIENT_LIGHT_SH = 9¶: 环境光照信息的球谐分量的最大数量。

const int CXR_NUM_CONTROLLERS = 2¶: 可以与 HMD 跟踪状态一起发送的控制器跟踪状态的数量。

const uint32_t CXR_AUDIO_CHANNEL_COUNT = 2¶: 音频目前始终为立体声。

const uint32_t CXR_AUDIO_SAMPLE_SIZE = sizeof(int16_t)¶: 音频目前是带符号的 16 位采样（小端序）

const uint32_t CXR_AUDIO_SAMPLING_RATE = 48000¶: 音频目前始终为 48khz。

const uint32_t CXR_AUDIO_FRAME_LENGTH_MS = 5¶: 发送的音频具有 5 毫秒的默认帧长。接收的音频具有 5 或 10 毫秒的帧长，具体取决于配置。

const uint32_t CXR_AUDIO_BYTES_PER_MS = CXR_AUDIO_CHANNEL_COUNT * CXR_AUDIO_SAMPLE_SIZE * CXR_AUDIO_SAMPLING_RATE / 1000¶: 每毫秒音频的总字节数。

const char *const cxrUserDataFileName = "CloudXR User Data"¶

const char *const cxrUserDataMutexName = "CloudXR User Data Mutex"¶

const uint32_t cxrUserDataMaxSize = 8 * 1024¶

const char *cxrErrorString(cxrError E)¶

static inline char cxrLLToChar(cxrLogLevel ll)¶: 此助手函数将 cxrLogLevel 枚举值转换为单个 ASCII 字符，以便轻松显示给定消息的优先级。

cxrFalse 0¶

cxrTrue 1¶

CXR_MAX_NUM_VIDEO_STREAMS 4¶: 支持的最大视频流数量。

CXR_MAX_VIDEO_STREAM_WIDTH 4096¶

CXR_MAX_VIDEO_STREAM_HEIGHT 4096¶

CXR_MAX_VIDEO_STREAM_FPS 144.0f¶

CXR_DEFAULT_VIDEO_STREAM_FPS 90.0f¶

CXR_MAX_VIDEO_STREAM_BITRATE 100000¶

CXR_DEFAULT_VIDEO_STREAM_BITRATE 50000¶

CXR_NUM_VIDEO_STREAMS_XR 2¶: 在 Receiver_XR 模式下，流的数量始终为 2。

CXR_MAX_PATH 4096¶: 路径输入的最大长度。

CXR_MAX_CONTROLLER_ROLE 63¶: 控制器角色的最大长度。

CXR_MAX_CONTROLLER_NAME 127¶: 控制器名称的最大长度。

CXR_MAX_CONTROLLER_INPUT_COUNT 128¶: 控制器输入路径的最大数量。

CXR_MAX_INPUT_PATH_LENGTH 127¶: 控制器输入路径的最大长度。

CXR_MAX_BLOB_BYTES_PER_INPUT 1024¶: 可以作为 blob 输入发送的最大字节数。

CLOUDXR_LOG_MAX_DEFAULT -1¶: 日志系统使用其默认设置来设置最大大小、期限和类似属性的常量。

MAX_LOG_LINE_LEN 4096¶: 给定日志消息 C 字符串的最大大小。

MAX_TAG_LEN 256¶: 给定日志标签 C 字符串的最大大小。

struct cxrClientCallbacks¶

#include <CloudXRClient.h>

接收器与客户端代码交互的回调函数。

这些函数用于向客户端请求某些内容或向客户端提供数据或通知。

公共成员

void (*GetTrackingState)(void *context, cxrVRTrackingState *trackingState)¶: 返回 HMD 和控制器状态和姿势。由接收器以固定的频率调用，频率由 cxrDeviceDesc::posePollFreq 指定。必须实现此回调，服务器才能渲染客户端设备和控制器位置和方向的变化。

void (*TriggerHaptic)(void *context, const cxrHapticFeedback *haptic)¶: 通知客户端应触发控制器振动。

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

通知客户端播放传递的音频缓冲区。

返回: cxrTrue 如果数据已消耗/播放，cxrFalse 如果无法播放或以其他方式丢弃

void (*ReceiveUserData)(void *context, const void *data, uint32_t size)¶: 预留供未来使用

void (*UpdateClientState)(void *context, cxrClientState state, cxrError error)¶: 通知客户端底层状态更改以及发生更改的原因，包括异常和预期情况。如果您调用 cxrConnect() 并在 cxrConnectionDesc 中设置了 async 标志，则必须实现此回调，以便在后台线程中收到连接状态更改的通知。

cxrMessageCallbackFunc LogMessage¶: 通过客户端已实现的任何日志工具，通知客户端要记录的消息字符串。LogMessage 的 typedef 在 CloudXRCommon.h 中：void (*func)(void* context, cxrLogLevel level, cxrMessageCategory category, void* extra, const char* tag, const char* const messageText);

void *clientContext¶: 这是一个可选的应用程序特定的指针，作为第一个参数 (void* context) 发送回客户端的所有回调函数中。它通常是指向访问/实现在回调内部的功能所必需的核心对象/结构的指针。

struct cxrReceiverDesc¶

#include <CloudXRClient.h>

此结构包含客户端设备的详细信息和整体会话特征。它被传递给 cxrCreateReceiver 以构造 cxrReceiverHandle 实例并连接到服务器进行流式传输。

公共成员

uint32_t requestedVersion¶: 必须设置为 CLOUDXR_VERSION_DWORD。

cxrDeviceDesc deviceDesc¶: 描述客户端设备硬件。

cxrClientCallbacks clientCallbacks¶: 指向客户端回调函数的指针（对于不支持的回调，则为 NULL）

const cxrGraphicsContext *shareContext¶: 要与 CloudXR 共享的 API 特定的客户端图形上下文。

注意

在某些图形 API（例如 DirectX）上，共享上下文可能为 NULL。但是，在 Android 设备上的 OpenGL ES 上，共享上下文不能为 NULL。

uint32_t debugFlags¶: 辅助调试的功能（请参阅 cxrDebugFlags）

int32_t logMaxSizeKB¶: 客户端日志的最大大小（KB）。-1 表示默认值，0 表示禁用大小限制。

int32_t logMaxAgeDays¶: 删除早于此日期的日志和诊断文件。-1 表示默认值，0 表示禁用。

char appOutputPath[CXR_MAX_PATH]¶: 库可以在其中输出日志、捕获、跟踪等的客户端子目录。

struct cxrConnectionStats¶

#include <CloudXRClient.h>

此结构体被传递到 cxrGetConnectionStats。统计信息分为三个类别

帧统计信息与视频帧从服务器移动到客户端的时序有关，并以 frame 为前缀。

网络统计信息与服务器和客户端之间连接的性能有关，并以 bandwidth、roundTrip、jitter 和 totalPackets 为前缀。

质量统计信息与连接的整体健康状况有关，并以 quality 为前缀。

公共成员

float framesPerSecond¶: 每秒帧数。

float frameDeliveryTimeMs¶: 帧到达客户端的平均时间（对于 XR 流式传输，这包括姿势延迟）

float frameQueueTimeMs¶: 帧在客户端排队的平均时间。

float frameLatchTimeMs¶: 客户端应用程序等待帧被锁定的时间。

uint32_t bandwidthAvailableKbps¶: 从服务器到客户端的估计可用带宽。

uint32_t bandwidthUtilizationKbps¶: 从服务器到客户端的平均视频流速率。

uint32_t bandwidthUtilizationPercent¶: 从服务器到客户端的估计带宽利用率百分比。

uint32_t roundTripDelayMs¶: 服务器和客户端之间估计的网络往返延迟，以毫秒为单位。

uint32_t jitterUs¶: 从服务器到客户端的估计抖动，以微秒为单位。

uint32_t totalPacketsReceived¶: 客户端上接收到的视频数据包的累积数量。

uint32_t totalPacketsLost¶: 从服务器到客户端传输过程中丢失的视频数据包的累积数量。

uint32_t totalPacketsDropped¶: 在客户端上未显示而被丢弃的视频数据包的累积数量。

cxrConnectionQuality quality¶: 连接质量，为 cxrConnectionQuality 中的五个值之一。

注意

如果质量为 cxrConnectionQuality_Fair，则 qualityReasons 标志将被填充。

uint32_t qualityReasons¶: 连接质量的原因，为一个或多个 cxrConnectionQualityReason 标志。

struct cxrConnectionDesc¶

公共成员

cxrBool async¶: 调用 cxrConnect 将会产生一个后台线程来尝试连接，并立即将控制权返回给调用线程，而不会阻塞直到连接建立或失败。

cxrBool useL4S¶: 在可用的网络上，启用 L4S 拥塞处理。

cxrNetworkInterface clientNetwork¶: 客户端用于连接到服务器的网络适配器类型。

cxrNetworkTopology topology¶: 客户端和服务器之间连接的拓扑。

struct cxrMatrix34¶

#include <CloudXRCommon.h>

CloudXR 使用右手坐标系，其中：+y 轴向上，+x 轴向右，-z 轴向前。距离单位为米。

公共成员

float m[3][4]¶: 矩阵分量。

struct cxrVector2¶

公共成员

float v[2]¶: 向量的 x, y 值。

struct cxrVector3¶

公共成员

float v[3]¶: 向量的 x, y, z 值。

struct cxrQuaternion¶

公共成员

float w¶: w 值。

float x¶: x 值。

float y¶: y 值。

float z¶: z 值。

struct cxrLightProperties¶

公共成员

cxrVector3 primaryLightColor¶: 主光源颜色。

cxrVector3 primaryLightDirection¶: 主光源方向。

cxrVector3 ambientLightSh[CXR_MAX_AMBIENT_LIGHT_SH]¶: 环境光球谐分量，最多到 CXR_MAX_AMBIENT_LIGHT_SH。

struct cxrChaperone¶

公共成员

cxrUniverseOrigin universe¶: 用户是坐姿还是站姿。

cxrMatrix34 origin¶: 监护边界的原点。

cxrVector2 playArea¶: 监护边界的范围。

struct cxrTrackedDevicePose¶

公共成员

cxrVector3 position¶: 设备 3D 位置。

cxrQuaternion rotation¶: 表示方向的归一化四元数。

cxrVector3 velocity¶: 设备在跟踪器空间中的速度，单位为米/秒。

cxrVector3 angularVelocity¶: 设备角速度，单位为弧度/秒。

cxrVector3 acceleration¶: 设备在跟踪器空间中的加速度，单位为米/秒平方。

cxrVector3 angularAcceleration¶: 设备角加速度，单位为弧度/秒平方。

cxrTrackingResult trackingResult¶: 设备的跟踪结果。

cxrBool poseIsValid¶: 此姿势是否有效。

cxrBool deviceIsConnected¶: 设备是否物理连接。

struct cxrHmdTrackingState¶

公共成员

uint64_t clientTimeNS¶: 此事件发生时的客户端时间。客户端时钟必须单调递增，但没有纪元约束。

uint64_t flags¶: 来自 cxrHmdTrackingFlags 的值的按位掩码

float proj[2][4]¶: 如果设置了 cxrHmdTrackingFlags_HasProjection，则允许您以每个姿势的粒度更新设备描述中指定的投影参数。

float ipd¶: 如果设置了 cxrHmdTrackingFlags_HasIPD，则允许您以每个姿势的粒度更新设备描述中指定的头戴式显示器瞳距参数。

float displayRefresh¶: 如果设置了 cxrHmdTrackingFlags_HasRefresh，则覆盖设备描述中指定的头戴式显示器目标刷新率/fps（最高可达每个姿势的粒度）。

uint64_t poseID¶: 如果设置了 cxrHmdTrackingFlags_HasPoseID，则包含与此姿势关联的用户指定的 64 位值。相同的值将在此姿势关联的 cxrFramesLatched 结构的 poseID 中传递给客户端。

float scaling¶: 如果设置了 cxrHmdTrackingFlags_HasScaling，则允许您指定全轴缩放比例，默认为 1.0。

cxrTrackedDevicePose pose¶: 头戴式显示器的 3D 姿势。

cxrDeviceActivityLevel activityLevel¶: 头戴式显示器的活动级别。

struct cxrBlob¶

公共成员

uint64_t size¶: Blob 数据大小（以字节为单位），不能超过 CXR_MAX_BLOB_BYTES_PER_INPUT。

void *ptr¶: Blob 数据内容，在调用 cxrFireControllerEvents 时复制。

struct cxrControllerInputValue¶

公共成员

cxrInputValueType valueType¶: 此输入事件的值类型，根据此类型应设置以下属性之一。

cxrBlob vBlob¶: 此输入事件的 Blob 数据。

cxrBool vBool¶: 此输入事件的布尔数据。

uint32_t vI32¶: 此输入事件的 Int32 数据。

float vF32¶: 此输入事件的 Float32 数据。

struct cxrControllerEvent¶

公共成员

uint64_t clientTimeNS¶: 此事件发生的时间 - 未指定纪元，但持续时间必须反映纳秒级的实际时间。

uint16_t clientInputIndex¶: 此输入事件在提供给 cxrAddController() 的相应控制器描述中的索引。

cxrControllerInputValue inputValue¶: 输入事件的值。

struct cxrControllerDesc¶

公共成员

uint64_t id¶: 此控制器的唯一 ID。此 ID 应在断开连接/重新连接后保持不变。目前，通用手部控制器的左手 ID 预计为 0，右手 ID 预计为 1。

const char *role¶: 控制器的唯一角色。目前，这用于指示手持方向，通过 URI “cxr://input/hand/left” 和 “cxr://input/hand/right”。

const char *controllerName¶: 控制器的识别产品名称。这用于确定控制器的服务器渲染，并可能用于其他功能。

uint32_t inputCount¶: 此控制器支持的输入路径的数量。

const char **inputPaths¶: 包含 inputCount 个元素的输入路径数组。

const cxrInputValueType *inputValueTypes¶: 包含 inputCount 个元素且与 inputPaths 相对应的输入类型数组。

struct cxrControllerTrackingState¶

公共成员

uint64_t clientTimeNS¶: 此事件发生的时间 - 未指定纪元，但持续时间必须反映纳秒级的实际时间。

cxrTrackedDevicePose pose¶: 控制器的 3D 姿势。

struct cxrVRTrackingState¶

#include <CloudXRCommon.h>

这用于发送 hmd 跟踪状态，也可能用于左/右控制器姿势。任何其他控制器/姿势可以使用 cxrSendControllerPoses 发送

公共成员

cxrHmdTrackingState hmd¶: 头戴式显示器的跟踪状态。

cxrControllerTrackingState controller[CXR_NUM_CONTROLLERS]¶: 左/右手控制器的跟踪状态，索引 0 定义为左手。

float poseTimeOffset¶: 姿势时间偏移量，单位为秒，表示相对于姿势实际时间的偏移量，会影响姿势外推的程度。默认为 0。

struct cxrClientVideoStreamDesc¶

公共成员

uint32_t width¶: 请求的渲染宽度，通常为显示宽度。

uint32_t height¶: 请求的渲染高度，通常为显示高度。

注意

宽度和高度应为偶数值，理想情况下应为 32 的倍数。

float fps¶: 设备显示刷新率，客户端需要服务器以该速率提供流。

uint32_t maxBitrate¶: 所有视频流量的比特率上限为此值。值为 0 表示无限制。

struct cxrDeviceDesc¶

公共成员

float maxResFactor¶: 服务器上建议的最大过采样尺寸。服务器会将更大的分辨率向下采样到此值。有效范围为 0.5-2.0，常用值为 1.2。

float ipd¶: 瞳孔间距。

float proj[2][4]¶: 每个眼睛的原始投影范围：从中心视轴的半角正切值。0|1 表示左|右眼，然后 0-3 表示左、右、上、下边缘。

float predOffset¶: 时间偏移量（秒），用于调整服务器时间预测模型，以考虑设备特定的延迟，从而将流渲染到屏幕上。

float maxClientQueueSize¶: 客户端上解码帧 FIFO 队列的最大大小（单位为帧）。

cxrBool stereoDisplay¶: 此设备可以显示立体输出，因此服务器需要以立体方式渲染。

cxrBool receiveAudio¶: 此设备可以接收和播放来自服务器的音频（例如，游戏/应用程序声音）。

cxrBool sendAudio¶: 此设备可以将捕获的音频发送到服务器（例如，麦克风）。

cxrBool embedInfoInVideo¶: 请求服务器在编码前将调试信息嵌入到每个帧中。

cxrBool disablePosePrediction¶: 使用客户端提供的原始姿势，不进行任何姿势外推。

cxrBool angularVelocityInDeviceSpace¶: 如果角速度在设备空间中，则为 True；如果在世界空间中，则为 False。

cxrBool disableVVSync¶: 禁用 VVSync，而是根据客户端 fps 以固定帧率运行服务器。

uint32_t foveatedScaleFactor¶: 请求服务器以显示分辨率的百分比进行注视点渲染帧。值范围为 [25-100]，零表示禁用。50 对于大多数用途来说是合理的。

uint32_t posePollFreq¶: 轮询姿势更新的频率。设置为 0 表示默认值，或设置为每秒轮询速率以调用轮询。默认值为 250，最大值为 1000。建议至少为显示刷新率的 2 倍。

uint32_t foveationModeCaps¶: 支持的注视点渲染模式的位掩码（每个 cxrFoveationMode 枚举值 1 位）。

cxrChaperone chaperone¶: 等效于 SteamVR 的 chaperone 或“游玩空间”。

struct cxrHapticFeedback¶

struct cxrGraphicsContext¶

struct cxrVideoFrame¶

公共成员

cxrTextureHandle texture¶: 此帧的纹理句柄可以在需要时转换为平台纹理。

uint32_t width¶: 帧的宽度，以纹素为单位。

uint32_t height¶: 帧的高度，以纹素为单位。

uint32_t pitch¶: 帧的宽度，以字节为单位。

uint32_t widthFinal¶: 帧的最终宽度，在内部变换（例如，反注视点渲染）之后。

uint32_t heightFinal¶: 帧的最终高度，在内部变换（例如，反注视点渲染）之后。

uint32_t streamIdx¶: 此帧来自的视频流的索引。

uint64_t timeStamp¶: 帧在服务器上捕获时的时间戳。

struct cxrFramesLatched¶

#include <CloudXRCommon.h>

此结构体被传递到 cxrLatchFrame() 中，如果锁定成功，它将包含锁定帧的数据。结构体的数据在使用完毕后必须通过传递给 cxrReleaseFrame() 来释放。

公共成员

uint32_t count¶: 锁定/获取的帧数。

cxrVideoFrame frames[CXR_MAX_NUM_VIDEO_STREAMS]¶: 每个锁定帧的视频帧数据。

cxrMatrix34 poseMatrix¶: 该时刻的设备位置。

uint64_t poseID¶: 用户指定的 64 位值，该值在 cxrHmdTrackingState 结构体中传递，并且与用于渲染此帧的头戴式显示器姿势相关联。

struct cxrAudioFrame¶