.. _1 SDK简介 :

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章<常见问题解答>

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

.. _示例教程: https://developer.ximmerse.com/#/example

1.2 SDK架构
-----------------

SDK系统架构如下图所示：

.. image:: _static/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

对渲染管线的支持情况:

.. image:: _static/SDK_Support_Rendering_Pipeline.png


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

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

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

.. _unity2019设置URP的官方文档: https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@7.1/manual/InstallURPIntoAProject.html


.. note::
      - 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属性默认配置，如果没有此默认配置，则打包的应用不会显示在头显主界面。
  
.. code-block:: xml

    <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默认必要权限，开发者可以根据需要增加新的权限

.. code-block:: xml

    <!--网络访问权限>
    <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应用: 

1.4.2 安装运行RhinoX应用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

**环境准备**

*硬件：*

- RhinoX头显

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

- 一台win10及机上版本开发电脑
  
*软件：*

- adb工具

- RhinoX Demo

 
**adb环境安装**

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

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

.. _教程: https://blog.csdn.net/L_201607/article/details/78150107

**安装RhinoX Demo**

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

.. _adb安装应用: https://cloud.tencent.com/developer/article/2092843

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

.. image:: _static/adbinstall.png

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

**运行demo**

运行Demo前，请确认：
  
  1.已拔出与头显连接的USB线

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

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


1.5 升级指南
--------------------------------------------

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

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

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

1.5.1 v1.5 的更新内容
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. 支持环形控制器。

.. image:: _static/ringcontrollerquicklook.jpg


2. 支持大空间融合算法

.. image:: _static/roomspacefusion.jpg


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

.. image:: _static/LensOptimization.png


4. 支持 Unity editor debugger 

.. image:: _static/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 目录下。如下图所示:
 
 .. image:: _static/move_dll_rhinoX_unity.png
 
.. note::
   - 在覆盖 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 选项。
 
 .. image:: _static/v1.5_sdk_export_resources.png
 
 .. image:: _static/v1.5_sdl_dont_include_dependency.png
 
 

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