团 体 标 准
T/TAF 264—2025
基于双目视差支持裸眼 3D 功能的移动通信终端应用程序接口(API)规范
Technical specification for interface of communication terminal
application supporting glasses-free 3D functionality based on binocular
disparity
2025-02-10 发布 2025-02-10 实施
电信终端产业协会 发布
前 言
本文件按照 GB/T 1.1—2020《标准化工作导则 第 1 部分：标准化文件的结构和起草规则》的规定起草。
请注意本文件中的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由电信终端产业协会提出并归口。
本文件起草单位：中国信息通信研究院、中国移动通信集团终端有限公司、华为技术有限公司、中兴通讯股份有限公司、宇龙计算机通信科技(深圳)有限公司、紫光展锐(上海)科技有限公司、北京凌宇智控科技有限公司、咪咕文化科技有限公司。
本文件主要起草人：崔芳、路鹏、段亚锋、段汶欣、陈公达、吴昊、顾秋辰、张佳宁、张丽强、王晓阳、马波、刘良国、张鹏、陈文斌、傅蓉蓉、董千洲、范洪源、曾路、邓雅丽、翁学义、李丛蓉等。
引 言
随着移动通信技术的飞速发展和硬件性能的不断提升，基于双目视差的裸眼 3D 显示技术正逐步成为提升用户体验的重要手段。这种技术无需佩戴额外设备即可实现立体显示，已经在市场上得到了广泛应用， 特别是在移动通信终端中， 能够为用户提供更加直观和沉浸式的 3D 视觉效果。
在当前人们对裸眼 3D 应用场景需求日益增长的背景下，从娱乐、游戏到教育、文旅，基于双目视差的裸眼 3D 显示技术展现出广阔的应用前景。然而，尽管技术和硬件日益成熟，不同厂商提供的 SDK 在接口设计、算法实现和显示效果上仍存在显著差异。这种不统一给开发者带来了巨大的挑战，例如，开发者需要针对不同厂商的设备进行定制开发，增加了开发成本和时间。同时，算法实现的差异导致各设备的裸眼 3D 显示效果参差不齐， 影响了用户体验的一致性。
本文件的制定，旨在引导基于双目视差支持裸眼 3D 功能移动通信终端，制定一套通用的接口规范， 推动行业的健康发展。
基于双目视差支持裸眼 3D 功能的移动通信终端应用程序接口(API)
规范
1 范围
本文件规定了基于双目视差的非全息裸眼 3D 显示技术应用层和运行库层的接口规范，包含应用运行流程， 事件处理、应用渲染处理、应用交互处理的接口定义 。
本文件适用于双目视差的裸眼 3D 终端产品，供移动通信终端制造商和应用开发者进行软件开发时使用。
2 规范性引用文件
本文件没有规范性引用文件。
3 术语和定义
下列术语和定义适用于本文件。
3.1
裸眼 3D 通用标准 general standard for glasses-free 3D
一种无需特殊眼镜或其他辅助设备即可观看 3D 效果的从内容采集、编码、存储、传输到终端播放的移动通信终端通用标准方案。
4 缩略语
下列缩略语适用于本文件。
DOF： 空间自由度(Inter Pupillary Distance )
GSGF3D： 裸眼 3D 通用标准(General Standard for Glasses-Free 3D)
IPD： 双眼瞳距(Inter Pupillary Distance )
SDK： 软件开发工具包(Software Development Kit )
5 通用架构
5.1 概述
裸眼 3D 显示技术的通用架构， 主要包含应用层， API 层， 运行库层， 详见图 1。
图 1 通用架构图
5.2 应用层
裸眼 3D 应用层是指通过 3D 内容开发引擎或原生代码(Native)等平台创建的 3D 应用软件。其中裸眼 3D SDK 是针对不同应用开发平台的软件开发工具包(SDK) 。这些 SDK 帮助开发者在各个开发平台上创建支持裸眼 3D 显示的应用内容。
5.3 API 层
裸眼 3D API 层定义了裸眼 3D 显示等功能的标准 API。无论开发者使用何种 SDK，最终都通过调用这些标准化的 API 来实现裸眼 3D 显示等功能， 确保了不同设备和平台之间的兼容性。
5.4 运行库层
裸眼 3D 运行库层是整个系统的运行时， 负责最终的 3D 显示效果， 包括以下几个主要功能模块：
a) 设备函数： 处理与硬件设备相关的功能调用;
b) 空间交互函数： 管理与 3D 空间中的交互， 如手势、触控等;
c) 特性函数： 管理裸眼 3D 显示的特性， 如视差调节、深度控制等;
d) 渲染函数： 负责 3D 图像的最终渲染， 生成立体图像。
这些功能模块涉及到的算法主要包括通用算法，如眼球追踪算法、外接设备交互(如笔控、指环等) 和原生屏和膜厂商实现的合图算法。通用算法支持了 3D 显示中的互动和动态调整功能。原生屏和膜厂商实现的合图算法用于处理设备本身的特定 3D 显示需求。
通用架构图展示了从 3D 应用开发及 SDK 使用、API 标准化、到最终 3D 显示运行的完整流程。
6 API 说明
6.1 概述
通过定义统一的 API，可以使开发者以一致的方式接入不同厂商的裸眼 3D 终端，不再需要为每个厂商的设备和不同平台单独编写和调整代码， 大大缩短了适配时间、降低了开发难度;也能
在不同的平台(如 Android 、 iOS) 和设备上以一致的方式实现裸眼 3D 功能， 这种跨平台的兼容性也给开发者提供了更大的灵活性和选择空间。
6.2 应用运行流程
GSGF3D 应用程序从创建实例开始，应用的后续操作都将依据该实例进行。首先该实例进行参数配置并确认输入输出、图形及显示系统正常工作。随后创建渲染器及目标纹理并开始渲染， 在渲染循环中， GSGF3D 应用程序获取该实例的事件、位姿、输入数据， 并获取目标纹理的图形缓冲进行视图渲染， 最后提交渲染帧到该实例进行后续的图形算法处理并输出到显示屏。应用运行主线流程见图 2。
图 2 应用运行流程图
6.3 GSGF3D 应用生命周期处理
6.3.1 Instance 的创建
6.3.1.1 概述
Instance 作为 GSGF3D 应用的上下文环境， 存在于整个 GSGF3D 应用的生命周期中。
6.3.1.2 [结构体] GS3D_ApplicationType
6.3.1.3 [结构体] GS3D_ InstanceCreate Info
6.3.1.4 [函数] GS3D_Create Instance (创建 Instance)
6.3.2 终止及销毁 Instance
6.3.2.1 概述
GSGF3D 提供 GS3D_DestroyInstance 函数进行 Instance 实例的终止及销毁。
6.3.2.2 [函数] GS3D_Destroy Instance (销毁 Instance)
6.3.3 获取 Instance 的属性
6.3.3.1 概述
在 成 功 创 建 并 初 始 Instance 之 后 ， GSGF3D 应 用 程 序 可 经 由 Instance 句 柄 调 用GS3D_GetInstanceProperties 函数获取 Instance 属性信息， 包括 Instance 实现的 GSGF3D 版本号、 Instance 自身版本号、以及 Instance 实现者名称。
6.3.3.2 [结构体] GS3D_ InstanceProperties (Instance 属性信息)
6.3.3.3 [函数] GS3D_Get InstanceProperties (获取 Instance 属性)
6.4 GSGF3D 事件处理
6.4.1 概述
GS3D_Event 为事件结构体， 从事件轮询函数 GS3D_PollEvent 获取事件指针后， 需要根据该事件类型 GS3D_EventType， 进而获取存于 GS3D_EventData 中的事件成员数据。
6.4.2 事件结构信息
6.4.3 [结构体] GS3D_Event (事件信息)
事件结构指针需要根据事件类型 GS3D_EventType 转为对应的事件结构指针，以下说明各事件
类型的分类及其对应事件结构体。
6.5 GSGF3D 应用渲染
6.5.1 概述
GSGF3D 应用程序必须先完成渲染器的实例创建及初始， 才可以提供 GSGF3D 应用程序后续渲染循环所需求的功能。在 GSGF3D 应用程序不再使用此渲染器时， 应用程序必须停止 GSGF3D 渲染器并销毁实例， 将资源返回系统， 此流程即是 GSGF3D 渲染器的生命周期。
6.5.2 创建及初始化渲染器实例
6.5.2.1 [枚举] GS3D_Graphics_Type (图形 API 类型)
图形 API 类型定义见表 1。
表 1 图形 API 类型
6.5.2.2 [结构体] GS3D_RendererHandleCreate Info (渲染器初始信息)
6.5.2.3 [函数] GS3D_CreateRendererHandle (创建渲染器)
6.5.3 销毁渲染器实例
6.5.3.1 [函数] GS3D_DestroyRendererHandle (销毁渲染器)
6.5.4 视图集配置
6.5.4.1 [结构体] GS3D_ViewSetConfiguration Info (视图集配置)
6.5.4.2 [函数] GS3D_CheckViewSetConfiguration (查询视图集配置)
6.5.5 渲染循环的开始与停止
6.5.5.1 [枚举] GS3D_ColorSpaceType (颜色空间)颜色空间定义见表 2。
表 2 颜色空间
6.5.5.2 [结构体] GS3D_Render_Pipeline_ Info (渲染循环管线信息结构体)
6.5.5.3 [函数] GS3D_BeginRenderSession (开始渲染循环)
6.5.5.4 [函数] GS3D_EndRenderSession (停止渲染循环)
6.5.6 帧同步与视图位姿
6.5.6.1 [函数] GS3D_WaitRenderSession (等待调节帧渲染时机)
6.5.6.2 [结构体] GS3D_Fovf (视场角)
6.5.6.3 [结构体] GS3D_ViewSpaceState Info (视图姿态)
6.5.6.4 [函数] GS3D_CheckViewSpaceState (获取视图于指定时间的姿态)
6.5.7 更新视图合成信息
6.5.7.1 [枚举] GS3D_Input_View_Type (输入视图类型)输入视图类型定义见表 3。
表 3 输入视图类型
6.5.7.2 [枚举] GS3D_Display_View_Type (输出显示视图类型)输出显示视图类型) 定义见表 4。
表 4 输出显示视图类型
6.5.7.3 [枚举] GS3D_Output_Scale_Type (输出屏幕比例)
输出屏幕比例定义见表 5。
表 5 输出屏幕比例
6.5.7.4 [枚举] GS3D_Display_Orientation_Type (屏幕方向)屏幕方向定义见表 6。
表 6 屏幕方向
6.5.7.5 [结构体] GS3D_ViewComposition Info (渲染帧提交信息)
6.5.7.6 [函数] GS3D_UpdateViewComposition Info (更新视图合成信息)
6.5.7.7 [枚举] GS3D_Input_Texture_Type (输入纹理类型)
输入纹理类型定义见表 7。
表 7 输入纹理类型
6.5.7.8 [枚举] GS3D_Eye_View_Type (视图类型)视图类型定义见表 8。
表 8 视图类型
6.5.7.9 [结构体] GS3D_TextureSubImageInfo (纹理信息结构体)
6.5.7.10 [结构体] GS3D_CompositionLayerView Info (合成层视图信息结构体)
6.5.7.11 [结构体] GS3D_CompositionSubmit Info (提交的合成数据信息结构体)
6.5.7.12 [函数] GS3D_SubmitComposition (提交渲染帧)
6.6 GSGF3D 应用交互
6.6.1 输入设备类型
6.6.1.1 概述
GSGF3D 应用根据主要交互行为来区分设备类型，且设备根据自身的设计及特性，也可以在设备上接入数目及类型不等的输入部件。
6.6.1.2 [枚举] GS3D_ Input_DeviceType (交互设备类型)
交互设备类型定义见表 9。
表 9 交互设备类型
6.6.1.3 [枚举] GS3D_ Input Id (摇杆控制器按键)摇杆控制器按键定义见表 10。
表 10 摇杆控制器按键
6.6.1.4 [函数] GS3D_CheckSupportedDevices (获取支持的设备类型)
6.6.2 设备连线状态
6.6.2.1 概述
在 GSGF3D 应用程序开始使用 GSGF3D 设备之前， GSGF3D 设备必须先进行连线并完成初始化，此段流程由 GSGF3D 设备插件与 GSGF3D Instance 交互进行， 并在 GSGF3D Instance 完成设备初始化后发送 GS3D_EventType_DeviceState_Connected 事件通知 GSGF3D 应用程序，随后 GSGF3D 应用程序始能对于该连线设备进行其设备函数操作。
6.6.2.2 [函数] GS3D_CheckDeviceConnected (获取设备连线状态)
6.6.3 输入部件
6.6.3.1 概述
输入部件是 GSGF3D 设备在硬件设计上提供用户输入的交互人机界面， GSGF3D 应用程序根据自身的设计需求使用相应的输入部件， 提供用户与内容进行交互。同样地， GSGF3D 设备所具备的输入部件配置将会影响应用内容的操作行为。
为使 GSGF3D 应用程序明确获知 GSGF3D 设备的输入部件能力及配置，GSGF3D 提供以下输入部件定义及函数， GSGF3D 应用程序可根据设备不同的输入部件能力，设计相对应的内容交互方式，提高 GSGF3D 应用在不同输入设备上的泛用性。
6.6.3.2 [枚举] GS3D_ Input Id_ InputType (输入部件 Id 支持的输入类型)
输入部件 Id 支持的输入类型定义见表 11。
表 11 输入部件 Id 支持的输入类型
6.6.3.3 [函数] GS3D_Check Input IdConfiguration (获取输入部件具备的输入类型配置)
6.6.4 获取输入状态数据
6.6.4.1 概述
在 GS3D Instance 完成输入部件的配对之后，Instance 便可允许 GS3D 设备的输入部件数据传递至
GS3D 应用程序中。GS3D 应用程序获取 GS3D 设备输入部件状态数据的方式有以下两种：
GS3D 提供三类函数获取点击状态、触摸状态、及类比数据。
——调用 GS3D_CheckInputClickStates 获取指定输入部件下的所有点击状态。
——调用 GS3D_CheckInputTouchStates 获取指定输入部件下的所有触摸状态。
——调用 GS3D_CheckInputAnalogState 获取指定输入部件的类比数据。
6.6.4.2 [函数] GS3D_Check InputClickStates
6.6.4.3 [函数] GS3D_Check InputTouchStates (获取设备输入部件触摸状态)
6.6.4.4 [函数] GS3D_Check InputAnalogState (获取设备输入部件类比数据)
6.6.5 输出震动反馈
6.6.5.1 概述
振动反馈是一种利用触觉体验与用户进行交互的方法， 通常用于手柄设备。要实现振动反馈， GSGF3D 设备在硬件设计上必须配置振动模组，使 GSGF3D 应用程序在内容的运用上，可以在适当时机能够驱动 GSGF3D 设备输出振动反馈，用来强化 GSGF3D 内容的交互体验。
6.6.5.2 [结构体] GS3D_HapticVibration Info (振动反馈)
6.6.5.3 [函数] GS3D_CheckTriggerVibration (触发设备振动反馈)
6.6.6 设备空间追踪
6.6.6.1 概述
定义设备在虚拟环境中的空间追踪能力信息。
6.6.6.2 [枚举] GS3D_DegreeOfFreedomType (空间自由度跟踪能力)
空间自由度跟踪能力定义见表 12。
表 12 空间自由度跟踪能力
6.6.6.3 [枚举] GS3D_SpaceOriginType (空间原点类型)空间原点类型定义见表 13。
表 13 空间原点类型
6.6.6.4 [结构体] GS3D_Posef (位姿结构体)
6.6.6.5 [结构体] GS3D_Velocityf (速度信息结构体)
6.6.6.6 [结构体] GS3D_SpacePoseState (空间信息结构体)
6.6.6.7 [结构体] GS3D_EyeSpaceState (眼追信息结构体)
6.6.6.8 [函数] GS3D_CheckDegreeOfFreedom (获取设备空间自由度跟踪能力)
6.6.6.9 [函数] GS3D_SetSpaceOrigin (设置 3D 应用之空间原点位置类型)
6.6.6.10 [函数] GS3D_SetEnableSpaceImu (开启终端设备 IMU 解算)
6.6.6.11 [函数] GS3D_CheckSpacePoseState (获取设备于指定时间之位姿及速度数据)
6.6.6.12 [函数] GS3D_CheckEyePoseState (获取眼球的坐标信息)
附 录 A (资料性)
接口使用说明
A.1 GSGF3D 应用生命周期处理接口使用说明
A.1.1 [函数名] GS3D_Create Instance
说明如下：
a) [参数检验]
• createInfo 必须是指向 GS3D_InstanceCreateInfo 的有效指针。
• instance 必须是指向 GS3D_Instance 句柄的有效指针。
b) [函数实现]
• Instance 根据 createInfo 输入的初始信息完成 Instance 初始化， 并输出有效的instance 句柄。若创建失败则输出 GS3D_NULL_HANDLE。
c) [返回值]成功
• GS3D_Result_Success Instance 创建成功。
失败
• GS3D_Error_Operation_Failed Instance 创建失败。
• GS3D_Error_ApplicationType_Unsupported 设备未支持该应用类型。
• GS3D_Error_Argument_Invalid createInfo 为 nullptr 或检验为无效的输入参数。或 instance 为 nullptr。
• GS3D_Error_Out_Of_Memory 内存溢出。
A.1.2 [函数名] GS3D_Destroy Instance
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
b) [函数实现]
• Instance 根据输入的 instance 句柄终止并销毁 Instance。
c) [返回值]成功
• GS3D_Result_Success Instance 销毁成功。
失败
• GS3D_Error_Operation_Failed Instance 销毁失败。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Call_Flow_Invalid 调用此函数前未先行调用GS3D_CreateInstance。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态 。
A.1.3 [函数名] GS3D_Get InstanceProperties
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• instanceProperties 必须是指向 GS3D_InstanceProperties 结构的有效指针。
b) [函数实现]
• Instance 将自身属性信息填入 instanceProperties 中输出。
c) [返回值]
成功
• GS3D_Result_Success Instance 获取成功。
失败
• GS3D_Error_Operation_Failed Instance 获取失败。
• GS3D_Error_API_Unsupported Instance 未实现此 API。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
A.2 GSGF3D 事件处理接口使用说明
A.2.1 [函数名] GS3D_CreateRendererHandle
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• createInfo 必须是指向 GS3D_RendererHandleCreateInfo 结构的有效指针。
• renderer 必须是指向 GS3D_Renderer 句柄的有效指针。
b) [函数实现]
• Instance 根据 createInfo 输入的图形 API 类型及其特化信息完成渲染器初始化，并输出有效的 renderer 句柄。若创建失败则输出 GS3D_NULL_HANDLE。
c) [返回值]成功
• GS3D_Result_Success 渲染器创建成功。
失败
• GS3D_Error_Operation_Failed 渲染器创建失败。
• GS3D_Error_Function_Unsupported graphicsType 定义于 GS3D_Graphics_Type 中，但Instance 不支持该图形 API。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid createInfo 为 nullptr 或检验为无效的输入参数。或renderer 为 nullptr。
• GS3D_Error_Out_Of_Memory 内存溢出。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.3 GSGF3D 应用渲染接口使用说明
A.3.1 [函数名] GS3D_DestroyRendererHandle
说明如下：
a) [参数检验]
• renderer 必须是有效的 GS3D_Renderer 句柄。
b) [函数实现]
• Instance 根据输入的 renderer 句柄终止并销毁渲染器。
c) [返回值]成功
• GS3D_Result_Success 渲染器销毁成功。
失败
• GS3D_Error_Operation_Failed 渲染器销毁失败。
• GS3D_Error_Handle_Invalid renderer 为无效句柄。
• GS3D_Error_Call_Flow_Invalid 调用此函数前未先行调用 GS3D_CreateRenderer。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.3.2 [函数名] GS3D_CheckViewSetConfiguration
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• configurations 必须是指向 GS3D_ViewSetConfigurationInfo 的有效指针。
b) [函数实现]
• 获取视图集配置输出。
c) [返回值]成功
• GS3D_Result_Success 视图集数目获取成功。
失败
• GS3D_Error_Handle_Invalid tuntime 为无效句柄。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.3 [函数名] GS3D_BeginRenderSession
说明如下：
a) [参数检验]
• rendererHandle 必须是有效的 GS3D_Renderer 句柄。
• beginInfo 必须是指向 GS3D_Render_Pipeline_Info 结构的有效指针。
• session 必须是指向 GS3D_RenderSession 数值的有效指针。
b) [函数实现]
• 渲染器 renderer 根据 beginInfo 资讯开始渲染循环， 并将句柄填入 session 输出。
c) [返回值]成功
• GS3D_Result_Success 渲染循环起始成功。
失败
• GS3D_Error_Operation_Failed 渲染循环起始失败。
• GS3D_Error_Handle_Invalid renderer 为无效句柄。
• GS3D_Error_Argument_Invalid startInfo 为 nullptr 或检验为无效的输入参数。或session 为 nullptr。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.4 [函数名] GS3D_EndRenderSession
说明如下：
a) [参数检验]
• sessionHandle 必须是有效的 GS3D_RenderSession 句柄。
b) [函数实现]
• 渲染器停止渲染循环 session。
c) [返回值]成功
• GS3D_Result_Success 渲染循环停止成功。
失败
• GS3D_Error_Operation_Failed 渲染循环停止失败。
• GS3D_Error_Handle_Invalid session 为无效句柄。
• GS3D_Error_Call_Flow_Invalid 调 用 此 函 数 前 未 先 行 调 用GS3D_StartRenderSession。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.5 [函数名] GS3D_WaitRenderSession
说明如下：
a) [参数检验]
• sessionHandle 必须是有效的 GS3D_RenderSessionHandle 句柄。
• predictedTime 必须是指向 GS3D_Time 数值的有效指针。
b) [函数实现]
• GS3D Instance 根据显示频率调节帧渲染时机返回函数，并于 predictedTime 输出渲染帧的预测显示时间。
c) [返回值]成功
• GS3D_Result_Success 调节成功。
失败
• GS3D_Error_Operation_Failed 调节失败。
• GS3D_Error_Handle_Invalid session 为无效句柄。
• GS3D_Error_Argument_Invalid predictedDisplayTime 为 nullptr。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.6 [函数名] GS3D_CheckViewSpaceState
说明如下：
a) [参数检验]
• sessionHandle 必须是有效的 GS3D_RenderSession 句柄。
• specifiedTime 必须是有效的时间戳数值。
• viewSpaceState 必须是指向 GS3D_ViewSpaceStateInfo 结构的有效指针。
b) [函数实现]
• Instance 根据 specifiedTime 获取 GSGF3D 显示设备的姿态。
c) [返回值]成功
• GS3D_Result_Success 视图姿态获取成功。
失败
• GS3D_Error_Operation_Failed 视图姿态获取失败。
• GS3D_Error_Handle_Invalid session 为无效句柄。
• GS3D_Error_Argument_Invalid specifiedTime 为无效时间戳。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.7 [函数名] GS3D_UpdateViewComposition Info
说明如下：
a) [参数检验]
• sessionHandle 必须是有效的 GS3D_RenderSessionHandle 句柄。
• viewCompositionInfo 必须是指向 GS3D_ViewCompositionInfo 结构的有效指针。
b) [函数实现]
• 根据当前屏幕及输出信息实时更新。
c) [返回值]成功
• GS3D_Result_Success 帧提交成功。
失败
• GS3D_Error_Operation_Failed 帧提交失败。
• GS3D_Error_Handle_Invalid session 为无效句柄。
• GS3D_Error_Argument_Invalid submitInfo 为 nullptr 或检验为无效的输入参数。
• GS3D_Error_Call_Flow_Invalid 调用此函数前未先行调用 GS3D_WaitFrame。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.3.8 [函数名] GS3D_SubmitComposition
说明如下：
a) [参数检验]
• sessionHandle 必须是有效的 GS3D_RenderSessionHandle 句柄。
• submitInfo 必须是指向 GS3D_CompositionSubmitInfo 结构的有效指针。
b) [函数实现]
• Instance 根据 submitInfo 的合成层信息进行合成并进行 GS3D 渲染后处理，并输出最后合成帧给显示设备。
c) [返回值]成功
• GS3D_Result_Success 帧提交成功。
失败
• GS3D_Error_Operation_Failed 帧提交失败。
• GS3D_Error_Handle_Invalid session 为无效句柄。
• GS3D_Error_Argument_Invalid submitInfo 为 nullptr 或检验为无效的输入参数。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
• GS3D_Error_Renderer_Unavailable 渲染器未处于正确工作状态。
A.4 GSGF3D 应用交互接口使用说明
A.4.1 [函数名] GS3D_CheckSupportedDevices
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceTypeFlags 必须是指向 GS3D_Flags64 数值的有效指针。
b) [函数实现]
• Instance 需要根据本身能力枚举当前运行平台所支持的所有设备， 将所支持设备类型 对 应 的 GS3D_Input_DeviceType 数 值 进 行 OR 运 算 后 的 位 掩 码 填 入deviceTypeFlags 中输出。
c) [返回值]成功
• GS3D_Result_Success 设备类型获取成功。
失败
• GS3D_Error_Operation_Failed 设备类型获取失败。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.2 [函数名] 设备连线事件
说明如下：
a) [功能实现]
• GS3D_EventType_DeviceState_Connected 设备连接，GSGF3D Instance 完成设备初始化后发送 GS3D_EventType_DeviceState_Connected 事件进事件队列。
• GS3D_EventType_DeviceState_Disconnected 设备断开，GSGF3D Instance 完成资源释放后发送 GS3D_EventType_DeviceState_Disconnected 事件进事件队列。
A.4.3 [函数名] GS3D_CheckDeviceConnected
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• connected 必须是指向 GS3D_Bool32 数值的有效指针。
b) [函数实现]
• Instance 须根据当前 deviceType 的连线状态输出 connected (GS3D_TRUE 表示已连线， GS3D_FALSE 表示未连线)。
c) [返回值]成功
• GS3D_Result_Success 设备连线状态获取成功。
失败
• GS3D_Error_Operation_Failed 设备连线状态获取失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。或 connected 为 nullptr。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.4 [函数名] GS3D_Check Input IdConfiguration
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• inputId 必须是有效的输入部件标识号。
• configuration 必须是指向 GS3D_Flags64 数值的有效指针。
b) [函数实现]
• Instance 根据设备部件配置，获取 deviceType 设备的 inputId 部件具备何种输入类型能力，并将对应类型的 GS3D_InputId_InputType 进行 OR 运算后的位掩码填入configuration 中输出。
c) [返回值]成功
• GS3D_Result_Success 输入部件配置获取成功。
失败
• GS3D_Error_Operation_Failed 输入部件配置获取失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Device_Disconnected deviceType 尚未连线。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.5 [函数名] GS3D_Check InputClickStates
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• clicks 必须是指向 GS3D_Flags64 数值的有效指针。
b) [函数实现]
• Instance 获取 deviceType 设备输入类型下的所有 InputId 输入部件的点击状态信息，以 InputId 为位掩码存储点击状态信息
c) [返回值]成功
• GS3D_Result_Success 点击状态获取成功。
失败
• GS3D_Error_Operation_Failed 点击状态获取失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.6 [函数名] GS3D_Check InputTouchStates
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• touchs 必须是指向 GS3D_Flags64 数值的有效指针。
b) [函数实现]
• Instance 获取 deviceType 设备输入类型下的所有 inputId 输入部件的触摸状态填入touchs 中输出， 以 InputId 为位掩码存储触摸状态信息
c) [返回值]成功
• GS3D_Result_Success 触摸状态获取成功。
失败
• GS3D_Error_Operation_Failed 触摸状态获取失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Device_Disconnected deviceType 尚未连线。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.7 [函数名] GS3D_Check InputAnalogState
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• inputId 必须是有效的输入部件 Id。
• analog 必须是指向 GS3D_Vector2f 结构的有效指针。
b) [函数实现]
• Instance 获取 deviceType 设备的 inputId 输入部件的类比数据填入 analog 中输出。
• analog 数据必须从原类比数据等比转换为函数备注 2 要求的归一化数据范围。
c) [返回值]成功
• GS3D_Result_Success 类比数据获取成功。
失败
• GS3D_Error_Operation_Failed 类比数据获取失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Device_Disconnected deviceType 尚未连线。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.8 [函数名] GS3D_CheckTriggerVibration
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• haptics 必须是指向 GS3D_HapticVibrationInfo 结构的有效指针。
b) [函数实现]
• Instance 根据输入的haptics 要求，触发 deviceType 设备进行对应的振动反馈。
c) [返回值]成功
• GS3D_Result_Success 触发振动成功。
失败
• GS3D_Error_Operation_Failed 触发振动失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但Instance 不支持该设备，或该设备不支持振动功能。
• GS3D_Error_Device_Disconnected deviceType 尚未连线。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。或manual 为 GS3D_TRUE 时，haptics 为 nullptr。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.9 [函数名] GS3D_CheckDegreeOfFreedom
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须是有效的 GS3D_Input_DeviceType 类型。
• dof 必须是指向 GS3D_DegreeOfFreedom 结构的有效指针。
b) [函数实现]
• Instance 根据设备信息， 返回空间追踪的能力。
c) [返回值]成功
• GS3D_Result_Success 返回成功。
失败
• GS3D_Error_Operation_Failed 函数调用失败。
• GS3D_Error_Function_Unsupported deviceType 定义于 GS3D_Input_DeviceType 中，但 Instance 不支持该设备。
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid deviceType 未定义于 GS3D_Input_DeviceType 中。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.10 [函数名] GS3D_SetSpaceOrigin
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• space 必须是有效的 GS3D_SpaceOriginType 类型。
b) [函数实现]
• Runtime 根据 space 类型设置相应的原点坐标。
c) [返回值]成功
• GS3D_Result_Success 返回成功。
失败
• GS3D_Error_Operation_Failed 函数调用失败。
• GS3D_Error_Function_Unsupported 不支持该功能
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid 无效参数。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.11 [函数名] GS3D_SetEnableSpace Imu
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• spaceImu 是否开启。
b) [函数实现]
• Runtime 根据设置状态， 相应的打开或者关闭 imu 的空间位姿解算。
c) [返回值]成功
• GS3D_Result_Success 返回成功。
失败
• GS3D_Error_Operation_Failed 函数调用失败。
• GS3D_Error_Function_Unsupported 不支持该功能
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid 无效参数。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
A.4.12 [函数名] GS3D_CheckSpacePoseState
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须为有效设备类型。
• specifiedTime 值为 0 时， 则为当前时间
• poseState 须输出有效的位姿信息
b) [函数实现]
• Runtime 需要按照参数提供有效的位姿数据。
c) [返回值]成功
• GS3D_Result_Success 返回成功。
失败
• GS3D_Error_Operation_Failed 函数调用失败。
• GS3D_Error_Function_Unsupported 不支持该功能
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid 无效参数。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。 A.4.13 [函数名] GS3D_CheckEyePoseState
说明如下：
a) [参数检验]
• instance 必须是有效的 GS3D_Instance 句柄。
• deviceType 必须为有效设备类型。
• poseState 须输出有效的眼睛的位置信息
b) [函数实现]
• Runtime 按需要返回有效的眼追数据。
c) [返回值]成功
• GS3D_Result_Success 返回成功。
失败
• GS3D_Error_Operation_Failed 函数调用失败。
• GS3D_Error_Function_Unsupported 不支持该功能
• GS3D_Error_Handle_Invalid instance 为无效句柄。
• GS3D_Error_Argument_Invalid 无效参数。
• GS3D_Error_Instance_Unavailable Instance 未处于正确工作状态。
评论