OPPO AR开发者帮助文档

其中内容较多，可合理运用页内搜索及目录索引功能，版本号：V0.7.1

当前版本号信息 V0.7.1

SDK版本号信息 V0.7.1

版本的新增/修改内容无

各个关键应用的版本号

OPPOXR软件版本号 OPPO_XR_202108021519

手机系统OTA Version PDEM10_11.D.01_001_202108022150

手机刷机版本 MSM_Gabor25_release0.7_202108021827

GTouch软件版本号 GTouch_21.32.1

AR相机软件版本号 2.5.22_21-7-22-15-27

ARLauncher软件版本号 1.1.32

AR动物园软件版本号 38

升级指导书 OTA升级 (V0.6.5~V0.7.1)操作手册 点击下载

SDK兼容表

手机系统 OTA Version \ UnitySDK版本号	SDK0.7.1	SDK0.6.5	SDK0.5.4	SDK0.4.8
PDEM10_11.D.01_001_202108022150	支持	支持	支持	不支持

当前版本相关软件包

UnitySDK软件包 点击下载

API指南 点击下载

OTA升级包 点击下载

开发设备：OPPO ARGlass 2021

全新分体式设计

Birdbath光学技术

毫秒级手部追踪，21个单手关键点

开发机介绍

设备功能	设备参数
开发设备提供：	OPPO AR Glass 2021
	OPPO Find X2
光学显示：	BB光学双1080P OLED
空间计算：	六自由度空间定位
	平面识别
	图片识别
交互方式：	三自由度控制器
	手势
	肢体识别
音频：	麦克风
	扬声器
计算单元：	OPPO Find X2 高通865平台
传感器：	六轴传感器
	环境光传感器
	距离传感器
	TOF摄像头
	RGB摄像头
SDK支持：	Unity（推荐版本2019.4.10.lts ）
数据接口(手机)：	网络
	蓝牙

一、设置开发环境

硬件要求：

电脑、安卓手机、ARGlass。

最低系统要求：

2.0+ GHz 处理器、2 GB 系统 RAM

软件需求：

l 操作系统：Window10(仅 64 位)

l 安装工具：

安装最新版 Unity 引擎，开发工具建议使用 Visual Studio 2019（或更高版本），导入扩展现实开发工具包（XRSDK）

1、安装 Unity 编辑器

Unity 编辑器版本（免费或专业）均支持 Windows 和 Android 开发。如果您刚刚开始使用 Unity 开发人员，我们建议您花时间学习 Unity 的文档和教程的基础知识。

所支持的最低统一版本 ARGlass 的应用开发是 2019.4.x。我们建议使用以下版本之一：2019.4 LTS。

我们在下面压缩了 Unity 的安装步骤。但是，有关 Unity 安装过程的详细信息，请转到 Unity 文档中的安装Unity 。

安装 Unity：

1. 转到 Unity下载页面，单击 Download Unity Hub，然后安装它。

2. 在安装选项卡上，单击添加，从列表中选择 Unity 版本，然后单击完成。

Unity Hub 是一个安装助手，可简化安装过程。除了 Unity，要构建和运行 Android 应用程序，您还必须安装 Android Build 支持模块，Android 软件开发工具包（SDK）和本机开发工具包（NDK）以及 OpenJDK。使用 Unity 2019.x 和更高版本，可以在Unity 安装期间安装必要的 Android 工具。

1. 转到 Unity下载页面，单击 Download Unity Hub，然后安装它。

2. 在安装选项卡上，单击添加，然后从列表中选择 Unity 版本。

3. 在“将模块添加到安装窗口”中，选择“ Android 构建支持”并将其展开，然后选择“ Android SDK 和 NDK 工具”和“ OpenJDK”，然后单击“完成”。这仅适用于 Unity 版本 2019.x 及更高版本。

如果您已经安装了不支持 Android 的 Unity，仍然可以将 Unity 中的 Android 工具添加到任何现有的 Unity 2019.x 版本中。

1. 打开 Unity Hub，然后单击“安装”选项卡。

2. 单击 Unity 2019.x 版本旁边的三个点，然后单击添加模块。

3. 在“添加模块”窗口中，选择“ Android 构建支持”并将其展开，然后选择“ Android SDK＆NDK 工具”和“ OpenJDK”，然后单击“完成”。

注意：此选项仅适用于 Unity 2019.x 版本以及通过 Unity Hub 安装 Unity 的情况。另外，您可以按照以下部分中的说明手动安装 Android 工具。

2、手动安装 Android 工具

1. 下载并安装 Android Studio 。如果已安装，请跳过此步骤。

2. 打开 Android Studio，从菜单中转到工具> SDK 管理器。

3. 转到“ SDK 工具”标签。

4. 从列表中选择“ Android SDK 工具”，然后单击“确定”。

注意：Android Studio 3.6 或更高版本认为 Android SDK 工具已过时。如果您使用的是这两个版本，请首先清除标签底部的“隐藏过时的软件包”，以在列表中显示“ Android SDK 工具”选项。

5. 选择 NDK（并排），然后从选项卡底部选择显示软件包详细信息。

6. 在展开的 NDK（并排）列表中，选择 19.2.5345600 版本（支持Unity2019.x版本），清除所有其他选定的版本，然后单击确定。

注意：Unity版本与NDK版本有兼容性，选择兼容版本即可。

建立新专案

安装 Unity 后，请创建一个新项目，以开始进行其余设置和应用程序开发。

1. 打开 Unity Hub。

2. 单击项目选项卡，然后单击新建。如果安装了多个 Unity 版本，请单击“新建”旁边的箭头，然后选择要用于创建项目的 Unity 版本。

3. 选择 3D，输入项目名称和位置，然后单击创建。

4. 创建项目后，Unity 会将其添加到 Unity Hub。要打开现有的 Unity 项目，请打开 Unity Hub，然后单击项目名称。

3、在 Unity 中映射 Android 工具

如果您使用的是 Unity 2019.x 及更高版本，则 Unity 会自动映射 Android SDK 和 NDK。

要在 Unity 中映射或更改 Android SDK 的位置，请执行以下操作：

1. 通过工具> SDK 管理器打开 Android Studio 以验证 Android SDK 的位置。

2. 打开 Unity 项目或创建一个新项目。

3. 从菜单中转到 Unity >首选项>外部工具。

4. 在 Android 下，在 SDK 中，粘贴 Android SDK 路径。或者，单击浏览找到 Android SDK 文件夹。例如，/Users/username/Library/Android/sdk/。

5. 在 NDK 中，粘贴 NDK 文件夹路径。通常，NDK 工具是在 SDK 文件夹中下载的。例如，/Users/username/Library/Android/sdk/ndk/。

二、XRSDK for Unity 入门

扩展现实工具包（XRSDK）是什么？

XRSDK for Unity 是一款面向扩展现实应用程序的开源跨平台开发工具包。 XRSDK 为空间交互提供了跨平台的输入系统、基础组件和常用的构建基块、Slam 系统、手势算法（即将加入）等；拥有完整的应用管理、窗口交互管理、图像优化处理、I/O处理等机制；可支持3D空间中的3D\2D应用多任务并行，同时提供了主流语言的API/SDK。 XRSDK旨在加快面向 AR平台的应用程序开发。该项目旨在降低准入门槛、快速创建扩展现实应用程序

OPPOXR快速入门

欢迎入门教程系列，这些教程将介绍扩展开发工具包（XRSDK）及提供的一些功能。此外，还将构建一个扩展现实体验，让用户可在其中掌握如何快速构建一个应用程序。本系列结束后，你将牢牢把握XRSDK及其如何加速开发过程。

Step1：打开新建HelloGabor工程

在完整安装Unity以及平台插件之后，初始化项目并部署第一个应用程序，切换至Android平台。如图：

Step2：导入XRSDK

1）点击 Window->Package Manager，如图所示：

2）在弹出的对话框点击左上角‘+’号，点击Add package from tarball，进行安装，如图：

3）在弹出的文件对话框中找到放置在本地路径下SDK包（.tgz），点击打开即可安装，如图：

4）安装SDK包之后，如果想查看示例Demo，可点击右侧界面Import into Project，如图：

Step3：新建HelloGabor场景

1）删除MainCamera，使用XRSDK中相机组件。

2）在Unity->Packgers下可找到SDK的包，如图：

3）将XRSDK包内的主要预制体拖入场景中，其中XRManager为头部预制体，包含事件相机、 XR立体相机、外部投屏相机预制体，XRWindow为window预制体；

4）场景中的Window拖拽赋值给XRManager脚本中的Window属性

n XRManager是XRSDK主要的控制类，负责SDK的初始化及逻辑驱动

n XRCameraManager的属性Preview Positon和Preview Euler为UnityEditor模式运行时相机默认的位置和朝向；

n XRCameraManager负责立体相机（StereoCamera）及UI事件相机(EventCamera)的管理(其中UI事件相机在UnityEditor状态下也作为主显示相机);

XRWindow为XR应用的窗口对象，与OppoXR系统相关联，负责与OppoXR系统进行交互（接收OppoXR系统的相关事件回调）；XRWindow节点的Transform位置和旋转均应为 0 ，Scale 为期望的 Window尺寸；默认挂载的XRWindowBase为默认为窗口模式，若应用为全屏模式需要更换为XRWindowFullScreen; 用户可以继承 XRWindowBase 类型，以自定义 Window 行为。

（1）InitialPosition和InitialEulerAngles 为窗口的初始位置和角度；

（2） fullscreenHeadPosition为全屏时相机初始位置

5）新建Text文本，赋值“Hello Gabor”，调整大小及位置，拖拽挂载至XRWindow的子对象。如图：

其中，UI部分需要设置为3D空间对象，则需要设置Canvas->RenderMode为‘WorldSpace’，将XRManager的‘EventCamera’赋值给Canvas->RenderMode的EventCamera。如图：

Step4：为XRSDK配置工程

a) Edit->Project Settings->Script Execution Order 中将XRManager设置为-100（保证XRManager先于其他脚本运行）；

b) Edit->Project Setting->Player->Other Setting中将Minimum API Level设为24， SetTargetAPILevel建议设为24或更高，最高测试到27；

c) Edit->Project Setting->Player->Other Setting中Scripting Backend建议设置为IL2CPP，当然也可以设置为Mono;

d) Edit->Project Setting->Player->Other Setting中将ApiCompatibilityLevel设置为NET4.x,

e) Edit->Project Setting->Player中勾选Multithreaded Rendering选项；

f) OXR SDK暂不支持Vulkan，建议勾选Auto Graphics API选项；

如需自定义，请移除Vulkan。如下图

g) Aspect Ratio Mode调为：Legacy Wide Screen(1.86)。如下图：

h) Default Orientation调为：Landscape Left

i）首次安装可忽略本项。安装应用程序时，系统会检测该安装包(APK)，如匹配到与已安装应用包名一致的，属于更新应用程序，此时会对比新包版本号，如果版本号未更新，则不更新应用配置。

小提示：按规则填写版本号，如：0.1.0，0.1.1，等；每次发布应用，版本号递增更新，如：0.1.2。

Step5：AndroidManifest 配置

AndroidManifest 配置必须遵循如下：

Packages下有模板文件：XRWindowSDK->Editor->SampleManifest/,将文件

拷贝至Assets->Plugins->Android/下(路径不存在，就新建)。如下图：

其中相关配置说明如下：

1. 在application下包含以下meta-data，用来标明应用为XR应用：

2.在application下包含以下meta-data,设置应用型:"normal","launcher","popup", 默认类型为"normal", SDK会根据类型采用不同控制策略；

3. 将Activity中的intent-filter修改为以下形式，为了去除桌面图标并让ArLauncher可以跳转：

<intent-filter>

</intent-filter>

</activity>

4. 包含以下权限，用来使用系统OPPOXR服务：

<uses-permission android:name="com.xr.AccessIrisCoreService" />

Step6：项目配置

打开Edit->Project Settings->XR Plug-in Management标签下的XR Window Setting，可配置SDK。（必须勾选XRWindow）

XRWindowSetting的SDK配置：

基础配置（窗口模式），如下图：

- Use Custom Activity仅在用户使用自定义的Android Activity(需继承XRWindowActivity或恰当的调用XRUnityPlayerHolder) 时需要勾选。不勾选这个会将主activity（包含android.intent.action.MAIN和android.intent.category.LEANBACK_LAUNCHER）覆盖为sdk的activity，勾选了则不会覆盖。

- Auto Request Permissions用于在应用打开时自动申请AndroidManifest.xml中设置的动态权限。

- 勾选Quit if not Granted可在申请权限失败时退出应用。

如上图所示：

- Run on Phone用于控制应用在开启于手机屏幕还是眼镜中，主要影响Unity Splash Screen的位置。在启用Unity Splash Screen的前提下，XR Plug-in Management标签下不勾选Initialize on Startup，Show Activity用于控制应用在眼镜中开启时，能否看到Unity Splash Screen的窗口。 Fullscreen Activity用于控制Unity Splash Screen是否以全屏模式出现。

- Single Pass Stereo选项可控制是否开启`Single Pass Stereo Rendering`。开启`Single Pass Stereo Rendering`可大幅度提升渲染效率，但可能需要对项目做一些适配(如Shader、后处理等)，详见[Unity官方文档 ]。

- Application Type用于设置应用类型，开发者不应改动此项。

- 勾选Double Screen可使应用同时显示于手机上和眼镜中。Double Screen Demo应勾选此项。

- External Render Pass用于控制投屏方式，开发者不应改动此项。

Step7：发布APK，真机运行

1）打开Build Settings，添加Hello Gabor场景；

2）点击Build，发布APK，真机运行。如图：

3）真机运行效果图：

坐标系统

XRSDK拥有一套自己的坐标系统，分为窗口应用和全屏应用，Vector3的Z轴需与unity坐标取反。

如下图:

窗口应用：1部分红框是窗口大小，需要在红框内部才能显示在设备端；2部分以头部位置（相机）为基点，InitialPosition为窗口的初始位移，InitalEulerAngles 为窗口的初始欧拉角度。

全屏应用：1部分不需要红框限制；2部分以头部位置（相机）为基点，FullscreenHeadPosition为头部坐标位移，ForceUpWhenFullscreen为全屏时Y轴是否强制向上，ResetPoseWhenFullscreen为全屏时是否可以重置位姿

注意事项

1、Unity版本

2018.1~2018.4不完全支持；

2019.1~2019.3不完全支持；

2020.1~2020.2不完全支持；

2、Unity模块

PostProcessing无法使用；

URP部分无法使用；

多相机无法使用；

Vulkan无法使用；

ARM64无法使用；

LWRP部分无法使用；

HybridRender部分无法使用；

三、控制器Gtouch

当手机与AR眼镜相连接后，手机会出现Gtouch界面，它是眼镜的多功能控制器，手机的旋转会控制射线的方向，其次屏幕下方三个按钮，分别有各自作用。

录屏按钮

左下角按钮为录屏按钮

单击：截屏

长按：录屏

录屏中单击：结束录屏

主控按钮

中间按钮为主控按钮

在Launcher界面单击：重定位主界面，让主界面显示在用户正前方。在应用中单击：当前应用进入后台，主界面返回前台。

射线按钮

右下角按钮为射线按钮

射线隐藏时：显示射线

射线显示时：校准射线

四、基本交互

手柄射线：以手机作为手柄控制器（GTouch），射线起点即手机正前方顶部位置，射线以某个长度（自定义），与空间对象进行交互，如点击对象等功能，射线输入则通过Unity-UI事件系统EventSystem响应事件,并且附带视觉和听觉反馈

分屏交互：是以手机界面和眼镜界面双屏显示内容，以一种新型交互需求展示给玩家，方便玩家操作，达到更加美好的体验。如，手机端显示虚拟按键，眼镜端显示游戏画面，操作虚拟按键控制游戏角色。

射线交互

1. UI交互

1. 导入XRWindowSDK

2. 将XRWindowSDK/Prefab文件夹下的XRManager和XRWindow拖入场景中

3.选中场景中的XRManager，并将XRWindow拖拽到XRManager->Window下

4. 在场景中选中XRWindow，并在此节点下创建的UGUI，将Canvas中RenderMode模式设置为World Space， EventCamera选择XRManager下的EventCamera后，即可实现UGUI与射线交互。

5.实际场景交互

2. GameObject交互

1．在需要交互的物体上添加相应的Colider

2.在对象上挂载脚本使用EventSystem相关接口即可与物体交互

2.实际场景交互

3. 自定义射线

可使用实线、虚线：

自定义射线赋值：

自定义射线之后，将射线拖拽赋值给XRWindow下的Cursor

自定义射线代码：

1.重载父类方法OnRay

2.重载父类方法HasCursor，并return True

分屏交互

1. 手机屏幕显示虚拟按键，眼镜显示画面，以手机屏幕的虚拟按键来操作眼镜

一、 SDK分屏设置：

1. 配置：

2. 场景搭建：

1）建立 layer:ActivityPlayer,所有在手机端显示的内容，设置为此layer。

2）相机CullingMask设置为ActivityPlayer，表示此相机只渲染这个layer的对象。

3）XRWindow挂载自定义脚本,继承XRWindowBase。
脚本内容：
必要的部分，必须在子类override一个Create(),并且持有父类特性，
重要的一点：如果为全屏应用，必须设置WindowFullscreen = true;
public override void Create()
{
base.Create();
WindowFullscreen = true;
}

二、 手机端界面：

三、 AR眼镜端画面：

五、渲染优化

通过渲染优化，提高画面品质并提升渲染速度，达到提高用户体验

锯齿优化

由于SDK只是将Unity画面传输到眼镜端显示，所以还需要用户在Unity中设置相应的渲染设置，以达到更好的视觉效果。

以塔防项目为例，推荐设置相机使用MSAA算法并开启2倍抗锯齿或后处理中SMAA反锯齿算法等，具体的效果还需要用户自己尝试定义。以下是未使用和使用抗锯齿、后处理的视觉效果

未开启抗锯齿

开启2倍MSAA抗锯齿

2倍MSAA反锯齿效果

开启MSAA2倍+后处理SMAA抗锯齿效果叠加

其中，抗锯齿设置路径：Edit->Project Setting->Quality->High->Anti Aliasing；这里使用的是High，用户可根据自己的需求自行选择。

后处理插件使用： Window->Package Manager，搜索Post Processing，点击安装即可，在场景中左右眼上都挂载组件Post-process Layer，可调节相应的参数以达到更好的视觉效果，这里推荐如上图所示配置参数。

综上视觉效果，可以看到开启抗锯齿和使用后处理会在视觉效果上有很大的提升，其他的抗锯齿设置需要根据用户需求自行定义尝试。

性能优化

性能对XR应用非常重要，应用如果无法以最佳帧率运行，用户体验可能会大大降低，图像会不稳定，头部跟踪会不准确，从而给用户带来糟糕体验。必须将性能优化作为XR应用的必要工作
最佳帧率：OppoAR应用目标频率为60帧/秒，以达到最佳体验。为达到目标帧速率有以下做法：

一、 了解性能瓶颈：

如果你的XR应用帧率不足，第一步是分析并了解应用的性能瓶颈，有两个主要的处理器负责渲染场景：
CPU与GPU，每个处理器负责应用的不同方面。
CPU：负责应用逻辑处理，包括输入输出，物理，动画，数据加载解析等。
GPU：渲染线程将绘图指令从CPU提交给GPU，GPU负责渲染模型，计算光照，纹理等操作，最终将生成的图像提交到设备屏幕。

二、 发现性能瓶颈：

有很多优秀工具能帮你发现应用中的性能瓶颈
Unity Profiler ：https://docs.unity3d.com/Manual/Profiler.html
Unity Frame Debugger ：https://docs.unity3d.com/Manual/FrameDebugger.html
SnapDragon Profiler：https://developer.qualcomm.com/software/snapdragon-profiler
RenderDoc ：https://renderdoc.org/

三、 XR优化性能的建议：

1.限制场景物体数量与结构
合理的管控场景内物体会大大节省处理器和内存资源。
注意事项：
    1.Unity的渲染流程会扫描场景内全部物体和子物体，不论物体是否disable。长时间禁用的物体或开发时的临时搭建尽量移除，而不是禁用。在需要时再动态生成。
    2.使用物体池（Object pool）管理可以重复利用的物体，如子弹，同样兵种的小兵等，这样可以减少动态生成时资源占用以及减少内存增益。
    3.在不影响整体架构的情况下尽量利用ECS（Entity Component System），ECS在移动设备和AR设备上对资源使用非常高效。
2.遮挡剔除（Occlusion Culling）
    推荐使用Unity的遮挡剔除减轻渲染对资源的占用。
注意事项：
    1.如果场景是相对Unity坐标系静止的，只有AR相机移动，bake occlusion可以进一步优化渲染和occlusion culling自身对资源的占用。
    2.合并mesh的两个物体A和B，即使只有一个物体可见，但是A和B依旧都会被渲染。
3.后期处理（Post processing）
     Post processing会为场景提供更加酷炫的视觉，但同时也使用大量的资源，平衡视觉效果和运行的流畅性至关重要。 注意事项：
    如果后期处理会造成fps下降则尽量使用shader技巧来代替。AR 移动应用上Post processing不推荐使用。
4.编译设置(Player Setting)
    1.不同的编译方法在应用运行时会有截然不同的效率。建议使用IL2CPP，不推荐使用Mono。 IL2CPP会大大优化运行效率和提升fps。
    2. Single pass stereo rendering SDK已经可以很好的支持Unity的Single pass stereo rendering技术，因此尽量开启这个选项进行开发，可以提高渲染效率

5.渲染优化
渲染会占据大量的系统资源，在不影响效果的情况下最大优化渲染才是王道。
注意事项：
1.DrawCall：
    应用的DrawCall峰值建议控制在200以内，降低DrawCall的方法：
    1:合并相同Shader的模型
    2:合并模型的贴图
    3:采用HLOD与Mipmap提升性能
    4:OverDraw建议不超过5
    5:巧妙使用Static与Dynamic batching
1.Shader:
    1:避免使用复杂Shader，精简Shader种类
    2:不使用多Pass的Shader，尽量使用shared material，开启GPU Instance
    3:鼓励使用CutOut Shader与Ulit Shader
    4:鼓励使用Shader Preload和ShaderVariantCollection.WarmUp
    5:UI要尽量合理的使用Sprite Atlas, 减少UI组件的Draw Call
    6:尽量少使用透明和半透明Shader