1.SDK 简介

RhinoX Unity SDK 是Ximmerse为Unity开发者度身定制的SDK工具包。 开发者使用此SDK工具包，可以快速在 RhinoX 上制作MR混合现实应用。

本文介绍如何使用UnitySDK制作运行在燧光头显上的AR应用。SDK提供了如下功能：

AR渲染系统：双目立体渲染、光学矫正、虚实对齐等。

AR交互系统：6Dof双控制器交互、X-Tag交互、多外设扩展等。

扩展功能：大空间定位、中控系统接入等。

RhinoX Unity Debugger : 支持开发者无需编译安装apk，可以在 Unity Editor 内快速 debug 的工具。

1.1 阅读指南

如果您首次使用燧光UnitySDK，建议从第1章开始阅读；

如果您已经有使用燧光UnitySDK开发AR应用的经验，可以直接从第4章开始阅读，其中：

第4章，主要介绍UnitySDK的常用组件；

第5章，介绍SDK的进阶功能,如大空间融合定位，URP的使用等；

第6章，介绍RhinoX开发的扩展模块，如多人协同开发，第三视角展示开发等；

如果您有开发使用方面的疑问，请看第8章<常见问题解答>

如果您需要一些开发范例，请参考 示例教程

1.2 SDK架构

SDK系统架构如下图所示：

_images/unitysdk_arch.jpg

图1.2 SDK系统架构

AR渲染系统

ARCamera： AR渲染相关接口，包括头部追踪等接口

Spatial Anchors(空间锚定)

Ground Plane：平面中心锚定，可以作为地面/桌面等

Big Space：支持超大空间锚定

ObjectTracking(信标追踪)

Trackable identity：追踪物体的类型和ID设置

Tracking Profile：定位信标跟踪配置文件

Dynamic Target： 将追踪信标的姿态更新给对象

Input(输入系统)

RXController：包含控制器姿态、按键等事件更新

RxInput：包括按键接口、控制器状态等

RxButtonEvent Trigger：输入事件回调接口

1.3 SDK配置需求

1.3.1 开发环境要求

UnitySDK_2018支持Unity版本：2018.3、2018.4

UnitySDK_2019支持Unity版本：2019.2、2019.3、2019.4

UnitySDK_2020支持Unity版本：2020.1, 2020.2, 2020.3, 2021.1

对渲染管线的支持情况:

_images/SDK_Support_Rendering_Pipeline.png

如果您使用的是Unity 2018版本， 我们推荐使⽤ Unity2018.4最新版本。

如果您使⽤的是Unity 2019版本，您的项⽬也⽀持通⽤渲染管线，我们推荐使⽤Unity2019.4版本。

URP设置方法参见 unity2019设置URP的官方文档

注解

  • 2019.3、2019.4须开启Universal Rendering Pipile

  • 从 v1.5.1 开始, SDK支持 Unity 2020, Unity 2021。

  • 2021目前只支持到2021.1，不支持2021.2以及2021.3

1.3.2 Unity设置

Minimum API Level： API level 25(Android 7.1)

Target API Level: Automatic(hightest installed)

Resolution and Presentation->Orientation->Default Orientation: Landscape Left

1.4 开发注意事项

1.4.1 Android Manifest文件介绍

文件位置：Plugins/Android/AndroidManifest.xml

  • Intent属性默认配置，如果没有此默认配置，则打包的应用不会显示在头显主界面。

<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
<!--应用显示到Launcher上>
<category android:name="com.ximmerse.category.WONDERLAND_AR" />
</intent-filter>

  • SDK默认必要权限，开发者可以根据需要增加新的权限

<!--网络访问权限>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!--RGB Camera访问权限>
<uses-permission android:name="android.permission.CAMERA" />

1.4.2 安装运行RhinoX应用

目前RhinoX安装应用只能通过adb命令，具体使用方法以及准备条件如下：

环境准备

硬件：

  • RhinoX头显

  • 标配的TypeC数据线(Type-C接口)

  • 一台win10及机上版本开发电脑

软件：

  • adb工具

  • RhinoX Demo

adb环境安装

adb是安卓开发必备的调试工具，您可以参考该 教程 在开发电脑安装adb工具，如果您已安装，请略过该步骤。

如果不熟悉adb的使用，可查找相关资料进行学习。

安装RhinoX Demo

安装前，将RhionX头显通过Type-C线与开发PC相连。连接之后，打开cmd窗口,通过adb install命令进行安装， 具体使用方法参考 adb安装应用

出现 “success” 表示安装成功，在主界面可以看到安装后的应用图标

_images/adbinstall.png

注解

如果主界面没有显示应用图标，请检查AndroidManifest文件是否按照要求配置。

运行demo

运行Demo前，请确认：

1.已拔出与头显连接的USB线

2.控制器已经和头显绑定

然后带上头显，进入Launcher，使用手柄/或者头瞄方式，点击启动刚安装的应用。启动应用后先识别Beacon， 确认场景在Beacon上方即表示识别成功。

1.5 升级指南

如果您使用的是1.5以上的版本，则可以直接将新的SDK中的Plugin文件替换掉旧的即可，需要注意对应的Unity编辑器版本

如果您使用的是1.5之前的版本，则参考如下步骤进行升级

注解

如果您是新项目导入， 不存在升级的问题，只需要直接导入最新的SDK包就可以了。 SDK 升级是针对旧项目而言的。

1.5.1 v1.5 的更新内容

  1. 支持环形控制器。

_images/ringcontrollerquicklook.jpg

  1. 支持大空间融合算法

_images/roomspacefusion.jpg

  1. 优化了光学参数, 改进了对齐效果

_images/LensOptimization.png

  1. 支持 Unity editor debugger

_images/demo_debugger.gif

1.5.2 从v1.2以下的版本升级到 v1.5

  1. 从开发者网站下载v1.5 sdk unitypackage. 或者从 gitee 上下载sdk 工程 : https://gitee.com/PolyEngine_Ent/RhinoX-SDK

  2. 建立一个空的Unity项目，导入第一步下载的 unitypackage 资源包。 或者直接打开从 gitee 上下载的 SDK 工程。

  3. 从刚才打开的工程中， 拷贝以下文件到旧项目的同名目录下, 如果原项目存在同名文件请覆盖原文件:

Assets/Plugins/Android/libs/svrApi-v7a-release.aar (如果原项目存在 svrApi-v7a-Debug.aar, 请删除原项目文件)

Assets/Plugins/Android/libs/svrUnity-v7a-release.aar (如果原项目存在 svrUnity-v7a-Debug.aar, 请删除原项目文件)

Assets/Plugins/Android/libs/xdevice-api.aar (如果原项目存在 xdevice-api.aar 这样的文件, 请删除原项目文件)

覆盖 RhinoX-Unity.dll 和 RhinoX-Unity-Editor.dll:

  1. 请把v1.5项目的文件夹: Assets/Plugins/Unity 2018.4/ 下的 DLL 文件覆盖到原项目的 Asset/Plugins/Android/2018.4 目录下，覆盖同名文件 , 如果是 2019的版本则文件夹名为 2019.4.

  2. 并且,如果原项目文件夹处于 Assets/Plugins/Android/目录下， 请将此文件夹移到 Asset/Plugins 目录下。如下图所示:

_images/move_dll_rhinoX_unity.png

注解

  • 在覆盖 DLL 的过程中，注意不要覆盖 meta 文件，例如 RhinoX-Unity.dll.meta . 只覆盖 DLL, PDB 和 XML 文件。

  • 如果覆盖了 meta 文件， 有可能导致一些关键类的引用丢失， 例如 ARCamera, RXController 等。

拷贝 UnityDebugger 支持文件

将v1.5项目的 Assets/Plugins/Unity 2018.4/UnityDebugger 文件夹完整的拷贝到原项目的 Assets/Plugins/Unity 2018.4/ (或者是2019.4) 路径下。

拷贝 Plugins/RhinoX 目录下的资源文件

打开 v1.5 SDK 项目， 在 Plugins/RhinoX 下右键导出一个 unity package, 注意不要勾选 include dependency 选项。

_images/v1.5_sdk_export_resources.png _images/v1.5_sdl_dont_include_dependency.png

导出资源包后, 然后在原项目中, 导入刚才导出的 unitypackage 资源包。