EN

# 三、功能介绍

# 3.1 UnityXR

奇遇UnityXR SDK基于UnityXR Plug-in Framework（https://docs.unity3d.com/Manual/XR.html (opens new window)）开发，目前支持以下UnityXR子系统，具体接口说明参见UnityXR说明文档：

Subsystem Reference
XRDisplaySubsystem https://docs.unity3d.com/Manual/xrsdk-display.html (opens new window)
XRInputSubsystem https://docs.unity3d.com/Manual/xrsdk-input.html (opens new window)
XRSettings https://docs.unity3d.com/ScriptReference/XR.XRSettings.html (opens new window)
XRNodeState https://docs.unity3d.com/ScriptReference/XR.XRNodeState.html (opens new window)

# 3.2 XRRig

本指南介绍了UnityXR为开发者提供的统一XR Rig prefab及功能。

# 3.2.1 Tracking Origin Mode

用于设置追踪原地的模式。

  • Device：以头显位置和方向作为参考进行追踪，Recenter会复原虚拟相机的位置。

  • Floor：以头显检测到的地面为参考面进行追踪，Recenter不会改变虚拟相机的高度。

注：对于多场景应用中，XRRig的使用注意，参见6.1 XRRig的使用注意 (opens new window) 。

# 3.3 QiyuManager

本指南介绍了奇遇为开发者提供的一些常用功能，在工程中找到 Packages/QIYU XR Plugin/Assets/QiyuManager.prefab，将QiyuManager.prefab拖进场景。

# 3.3.1 Foveation Level

Foveation Level等级越高帧率越高，但是像素损失越多，会影响边缘区域清晰度，请根据渲染需要选择合适的等级。详细说明参见3.6.1注视点渲染。

# 3.3.2 Eye Resolution Scale Factor

设置RenderTexture缩放系数，默认为0.7（推荐），开发者可根据场景需要调整。系数越小，画面清晰度越低，但帧率会提升，功耗降低；系数越大，画面清晰度提升，但是帧率会降低，功耗和内存会增加。建议最大值不要超过1。

  • 已知问题：

  1. 使用Unity专业版，如果取消了ShowSplashScreen，且“VirtualRealitySplashImage”为空，在 应用初始化阶段设置eyeTextureResolutionScale会失效，请在程序启动1s后再设置。（此问题为Unity bug）

  2. URP工程，设置eyeTextureResolutionScale=1.0会失效，请设置非1值。

# 3.3.3 使用3Dof模式

  • HMD 3Dof：MainCamera的Tracked Pose Driver组件的Tracking Type改为Rotation Only。
  • Controller 3Dof：调用接口Utils.SetTrackingPosition(false)。

注：UnityXR提供的“Tracked Pose Driver”没有模拟头部转动的“脖子模型”和模拟手柄运动的“手臂模型”，故3Dof的效果不是很自然。推荐使用奇遇提供的3Dof接口，加入了“脖子模型”和“手臂模型”，可以更加自然的模拟身体运动。接口参见4.4 奇遇3Dof模式 (opens new window)。

# 3.4 输入

本指南描述了SDK支持的输入交互功能。

# 3.4.1 通用输入接口

UnityEngine.XR.InputDevices封装了所有的设备输入接口，目前包括手柄控制器的输入、震动等接口。开发者可查阅XR Interaction Toolkit教程 (opens new window)接入输入功能。

注：为了达到更自然的手柄交互体验，从v1.4.0开始，deviceRotation值做了调整，将手柄握持杆斜向上35°的姿态作为初始值，如下图所示。如果在游戏中调整过手柄角度，在升级SDK后，需要将模型角度水平向上旋转35°，达到自然的握持姿势。

# 3.4.2 奇遇追光手柄控制器

如果开发者需要在场景中使用奇遇手柄模型，可将需要的手柄模型拖进XRcontroller指定Model Prefab位置。

注：

  • 如果设备是奇遇Dream、奇遇Dream Pro，Model Prefab中使用Controller_Dream目录下的手柄模型。
  • 如果应用需要使用奇遇手柄模型，且在奇遇多设备平台上线，需要根据设备接口识别设备类型，在Model Prefab中动态填入对应的手柄模型。可参考下面Demo 脚本。
  • 如果应用需要使用奇遇手柄图片，可从此处 (opens new window)下载资源。

Demo：

QiyuXRController脚本可以替换默认的XRController实现模型自动切换功能（开发者也可以根据设备类型自行开发），使用前需要拖拽两个模型prefab到脚本对应位置。

# 3.4.3 VR输入法键盘

奇遇 SDK中提供了VR输入法键盘，方便开发人员将虚拟键盘放置在应用程序中。

  1. 将VRInputField Prefab 拖动到UI中。
  2. 单击控件以弹出虚拟键盘。
  3. 可参考SGKeyboard.unity 示例场景。
  1. 开发者可根据需要调节Controller参数，为了提升键盘操作的体验，推荐Device-based模式下，手柄按键阈值使用0.5。
  1. 设置左右手输入，如果只需要使用其中一个，可以将另外一个值NULL。
  1. 注意必须把ProjectSettings里的Active Input Handling设置为Both。

# 3.5 声音

本指南介绍了在Unity中创建引人入胜的VR音频体验的开发资源。

# 3.5.1 Unity AudioSource

  • 添加AudioSource组件，设置3D音效。

  • 开发者可在ProjectSettings-Audio中配置空间音频插件。

# 3.5.2 Resonance Audio插件

Resonance Audio是一个多平台的空间音频SDK，可提供高保真度、强大的空间音频技术，对于VR游戏和视频的真实体验有很大的帮助。 插件下载地址：https://resonance-audio.github.io/resonance-audio/develop/unity/getting-started

# 3.5.3 第三方音频插件

奇遇设备支持多款Unity开发者常用的第三方音频插件，比如Fmod、Wwise、Photon语音等。由于插件个别配 置项默认值不兼容，导致系统录屏功能声音异常，需要修改个别配置项，具体参见#6.8 常用音频插件 (opens new window)。

# 3.6 高级渲染功能

本指南介绍了有助于提升性能的高级渲染功能。

# 3.6.1 注视点渲染

注视点渲染（Foveation Rendering）可以优化VR场景的渲染，该技术通过为视野中心提供全分辨率（无损），降低周边视野（人眼焦点区域之外）分辨率的方式来达到优化渲染的目的。静态注视点渲染（FFR）是指将视野焦点固定在视口中心位置，实现从中心向周围逐渐降低清晰度的效果。

开启和配置"Foveated Rendering"选项如下图所示，在QiyuManager对象上QiyuManager.cs脚本中控制。

开发者也可以通过4.1章节提供的接口设置注视点渲染级别或自定义注视点渲染参数。

  • FFR已知问题：

    开启HDR的时候，设置FFR会失效。

# 3.6.2 Multi View (Single Pass)

UnityXR提供了Single Pass立体渲染技术（https://docs.unity3d.com/Manual/SinglePassStereoRendering.html），通过一个Camera实现立体渲染，可降低50%的DrawCall，对于CPU占用高的场景帧率提升明显。 开发者可通过Project Settings->XR Plug-in Management->QIYU，选择MultiView，该选项全局生效。

# 3.6.3 Vulkan 图形接口

Vulkan是一种现代图形API，在许多方面与OpenGL ES类似（OpenGL ES是奇遇3应用程序开发中使用的主要图形API），可以带来更好的CPU渲染性能，但无法提高GPU性能。 具体打开Vulkan设置的步骤如下：

  1. 打开Unity Editor > Build Settings > Player Settings > Settings for Android；
  2. 找到Other Settings，勾掉 Auto Graphic API选项，在Graphic API下方添加Vulkan；
  3. 在Graphic API下将Vulkan排到OpenGLES上面。

Vulkan已知问题

  • 在复杂场景中Vulkan帧率低于OpenGLES，我们会在后续版本中解决这个问题。
  • 如果同时选择Vulkan和multiview，请使用Unity2020.3.14及以上版本，否则画面显示异常。
  • 如果同时选择Vulkan和multiview，且开启HDR，请使用Unity2021.2.8f1及以上版本，否则画面显示异常。
  • URP工程中，如果同时选择Vulkan和multiview，多次场景跳转时会出现黑屏情况。
  • Vulkan不支持FFR功能。

# 3.7 QIYU Compositor Layers

为了提升文字、图片、视频等资源的渲染清晰度，可以将需要高清显示的图形图像区域在合成层中进行渲染。由于合成层渲染会使系统负载增加，在使用过程中不建议统一场景使用过多的Overlay或Underlay，建议小于5个。

# 3.7.1使用方法

  1. 在XR Camera上，添加QiyuOverlayManager组件。

  2. 场景中Create Empty GameObject，添加QiyuOverlay组件。

# 3.7.2 选项说明

  • Overlay Type: 渲染方式Overlay或Underlay，Overlay会遮挡场景中的所有物体，Underlay可以使用Shader挖洞处理，实现在EyeBuffer后渲染。

  • Layer ID: 渲染顺序，值越小越先渲染。

    注意：场景应该遵循近处物体遮挡远处物体的规则来设置 Lay ID值，以确保正确的景深遮挡关系，否则可能会出现对焦不舒服的情况。

  • Overlay Shape

    • Quad: 矩形Mesh。
    • Cylinder: 柱状Mesh。
    • Circle: 球体Mesh。
    • Customize: 自定义类型，可以使用现有Mesh进行渲染。

  • Mesh Face: 决定渲染合成图层的正反面。

  • Is External Surface: 是否是Android OES纹理，OES纹理需要指定图像宽高，并使用SetAndroidOESTextureID(int oesID)方法设置纹理id。请参考图3.7.2.2。

  • Override Color Scale: 调整合成层颜色。
    • Color Scale: 颜色值分量缩放比例；
    • Color Offset: 颜色值分量偏移。

# 3.7.3注意事项

  1. 开启HDR，Underlay无效。
  2. 如果是URP项目，默认HDR是开启状态，如果使用Underlay，需要手动关闭。
  1. IsExternalSurface不支持Vulkan。

# 3.7.4 Sample Scene

示例场景参见5.2.4。

# 3.8 Passthrough

Passthrough为制作混合现实的内容提供了可能性。通过VR头显上的摄像头拍摄到实时的真实环境作为背景，与虚拟内容叠加、融合后，呈现出虚实结合的效果。奇遇各型号设备支持的透视效果如下：

设备型号 Passthrough
奇遇 MIX 双目彩色透视
奇遇Dream Pro 黑白透视
奇遇Dream 不支持
奇遇 3 不支持

# 3.8.1 使用方法

点击场景中的QiyuManager，在属性面板中勾选PassthroughAsBackground，加载该场景即可自动打开Passthrough作为背景，场景销毁时会自动关闭Passthrough。

注意：

  • 如需运行过程中，动态开启/关闭Passthrough背景，可调用QiyuSeethrough接口，参考4.6 Passthrough (opens new window)。
  • 开关Passthrough是个异步过程，有一定延迟，可以通QiyuXRCore.RegisterSeeThroughCallback注册回调函数控制场景物体的显示隐藏 。详细用法参照SeethroughTest场景。
  • 如您的内容是在现有功能的基础上增加MR模式、MR场景，需要上线到奇遇各型产品的应用商店中，请根据设备类型/能力区分处理各设备上的效果。比如在不支持彩色透视的设备上，不显示MR模式的按钮或者隐藏进入MR场景的入口，参考4.6 Passthrough (opens new window)调用示例。
  • 如您的内容是一款全新的MR App，为了保证用户体验，我们推荐上线到奇遇支持彩色透视设备的应用商店，此时您无需做设备类型的区分处理。
  • 如需自定义Passthrough画面（Passthrough Window、Surface Projected Passthrough、Styling Passthrough等更丰富的功能），需使用OpenXR backend SDK，请联系vrsupport@qiyi.com获取。

# 3.8.2 示例

奇遇SDK提供了一些可供开发者参考、体验的MR 示例场景，在导入QIYU UnityXR SDK之后，再导入QiyuMRSamples.unitypackage，可以看到以下场景，打包运行在奇遇VR设备上浏览MR效果：

  • MRSolarSystem
  • MRBalloon
  • MRFarmland

使用步骤：

  1. 点击下载QiyuMRSamples.unitypackage (opens new window)

  2. 下载完成后，导入工程：先导入奇遇SDK，再通过Menu-Assets-Import Package-Custom Package导入。

  3. 设置XR Rig-Tracking Origin Mode为Floor。

  4. 按照快速入门 (opens new window)提供的打包步骤，编译出包，在奇遇VR设备上运行。

同时我们提供了一个完整的Sample Project：MRDinosaur，点击下载MRDinosaur工程。 (opens new window)

# 3.8.3 已知问题

  1. Passthrough不支持开启HDR。
  2. Passthrough不支持Vulkan。
  3. Dream Pro开发机，需在开发MR应用之前，手动安装2个服务 ，重启设备。点击下载服务安装包。 (opens new window)
  4. 性能说明，开启Passthrough背景后，由于增加了渲染层，会使CPU占用增长12%，GPU占用增长9%，内存占用增长100M左右，请开发者尽量优化场景模型的复杂度，降低GPU占用，确保运行时的帧率。可通过奇遇提供的性能工具查看、分析和优化应用性能数据，参见：奇遇性能分析工具PC版。 (opens new window)
  5. 由于Passthrough渲染层对于Alpha通道处理的特殊性，如果场景中半透明材质无法正常显示，需修改工程中使用的shader，确保Alpha通道的正确显示。

如果shader里ColorMask是 RGB，请修改为RGBA。例如：

请修改为：

如果shader最后输出想要显示纹理的alpha，请确保finalRGBA的alpha正确。例如：

请修改为：

# 3.9 菜单功能

本指南介绍了奇遇提供的简化开发者部分工作的功能。提供入口Menu-QIYU。

# 3.9.1 Modify Player Setting

一键自动修改工程配置至推荐配置，详细介绍参见快速入门步骤8 (opens new window)。

# 3.9.2 Create/Delete Manifest

如果开发者需要在Manifest文件中加入额外的内容（比如权限），可通过“Menu-QIYU-Tools-Create Manifest”一键自动生成Manifest文件。详细介绍参见快速入门步骤9 (opens new window)。

# 4.0 Quick Preview

# 4.0.1 QIYU Quick Scene Preview

为了提升开发效率，场景快速预览功能帮助开发者可以快速在设备里查看效果，打包使用AssetBundle方式进行场景打包，如果预览过程中修改代码，需要卸载应用后重新安装。

功能说明

  • Scene Select: 选择需要打包的场景。
  • Clean Cache Bundles: 删除与项目Assets同级目录下的QiyuAssetBundles目录。
  • Debug Mode: 是否开启Debug。
  • Build Scene: 打包场景为AssetBundles，如果VR设备中已经安装了apk，只拷贝最新的AssetBundles到设备中；如果未安装apk将同时在设备上安装应用并启动；如果应用正在运行中进行该操作，应用将重新加载最新资源。
  • Build Scene And Restart: 拷贝AssetBundles到设备，并重新启动应用。
  • Start or restart App: 启动或者重启应用。
  • Uninstall App: 卸载应用。

# 4.0.2 PC Direct Preview

为了提升开发效率，避免开发过程中频繁打包耗时，PC Direct Preview功能可以帮助开发者在Unity Editor中运行场景，同时在头显中可看到实时的画面。

  • 支持的电脑配置：

    • 操作系統：Windows10及以上

    • 显卡：NVIDIA GeForce GTX 1060 / AMD 5700

    • CPU：Intel Core i7-6700 / AMD FX 8320及以上

    • 内存：8G及以上

  • 使用方法：

    1. 通过USB方式连接电脑和头显。
    2. 安装QiyuPreviewAgent.apk到头显，点击下载 (opens new window)安装包。
    3. Unity Editor里点击Play，运行当前场景。
    4. Unity菜单栏，点击QIYU-Direct Previews，打开配置面板，可根据需要调节各设置项，参考下面的说明。
    5. 点击“Connect Qiyu Device”按钮，连接奇遇设备，并自启动PreviewAgent应用。
    6. 在头显中看到当前场景效果，PC中同步显示。
  • 设置项说明
    1. Connect Type: 目前支持USB连接
    2. IP Port：电脑和一体机数据转发端口，如非必要，不需要修改该配置项
    3. Render Frame：电脑向一体机发送数据的频率，控制一体机的显示帧率，故电脑的渲染帧率和一体机的显示帧率并不是一致的。
    4. Render Resolution：渲染分辨率，引擎渲染以及一体机显示所用Eyebuffer的单眼大小。渲染分辨率越 大，显示效果越清晰，同时帧率也会越低。请开发者平衡好帧率和清晰度的权重，选择合适的渲染分辨率。
  • 已知问题：
    1. 部分显卡（ A卡5600以下 ，N卡1060以下），以及部分CPU型号（低于Intel i7-6700或同等级AMD cpu）可能会有较大的延迟。
    2. 使用Unity2019，Unity2020，跳转ActionBasedController场景，会出现定屏现象，头手6dof无法追踪。

接口说明

  • 全国客户服务热线
  • 400-662-7152
  • 关注奇遇
Copyright © 2022 梦想绽放科技 All Rights Reserved. 京ICP备11032965号