【祥哥带你玩HoloLens开发】 HoloTookit.Sharing 库的权威介绍
HoloToolkit.Sharing 允许应用程序利用多个设备进行全息协作。
开发的初衷是对 SOTA（微软的一个工作室）与 NASA 使用 HoloLens 协作提升已有的火星探测器规划工具，HoloToolkit.Sharing 可以使用户在多个设备间允许每个设备上运行的应用程序实时通信并无缝的保持同步。
用户还可以与可能在同一房间或者远程工作的其它用户（使用多个设备）进行协作。
目录
Features
---
大厅 & 会话系统
- 发现可用的会话或创建你自己的会话
- 永久或 “until empty” 的会话生命周期
- 查看用户状态：当前会话，沉默状态
- 方便发现会话之间的更替
Anchor 共享
- 会话中的用户可以是在同一个或者不同的物理房间
- 用户可以分享他们与同一房间的其它用户一起放置在他们放假的全息锚的位置。
- 用户加入后可以下载会中中的所有锚
- 允许用个用户查看共享全息物体。
同步系统
在会话中同步数据是通过所有参与者进行的。
- 每个人在会话中保证看到同样的东西。
- 远程变化同时发生的冲突，自动冲突解决
- 实时：看到发生远程修改
- 共享数据集在新用户加入会话时自动合并
- 响应灵敏：在你自己的改变中没有延时
- 所有权：你的数据离开会话时
语音群聊
内置 VOIP 支持
* 基于服务器的混合处理，降低了客户端的处理和带宽需求。
可视化配对
通过以下方式连接设备：
- 一个设备显示一个带有连接信息和安全码的二维码
- 其它设备扫描二维码，连接并通过安全码验证
- 也可以使用内置的基础标记支持探测三维空间的位置
Profiler
在各个设备间分析和调试是一个具有挑战性的体验。所以 HoloToolkit.Sharing 提供了该应用程序来一次接多个设备在一个地方集中他们的 debug 调试输出信息。
同步模型
HoloToolkit.Sharing 具有在连接到指定会话的任何应用程序之间同步数据的能力。无论冲突发生在哪一个级别，冲突解决是由框架自动处理的。
基元类型
以下的基元类型在同步系统中原生支持。C# class 中的每一个基元必须写在括号内。
- Boolean (SyncBool)
- Double (SyncDouble)
- Float (SyncFloat)
- Integer (SyncInteger)
- Long (SyncLong)
- Object,它是一个容器，它可以有自基元 (SyncObject)
- String (SyncString)
除了以上的原生基元外, 以下类型在 C# 也支持:
- Quaternion (SyncQuaternion)
- Transform (SyncTransform)
- Unordered array (SyncArray)
- Vector3 (SyncVector3)
你的程序如果有需要其它类型可以从 SyncObject 来继承，可以参考 SyncVector3 和 SyncTransform 的实现。
定义同步模型
默认情况下，SyncRoot（继承自SyncObject） 对象只包含实例化预设的数组，这可能不满足你的应用程序。
对于任何继承自 SyncObject 的类型，你可以很容易地通过使用 SyncData 属性增加新的子基元，类似下面的例子：
public class MySyncObject : SyncObject
{
[SyncData]
public SyncSpawnArray<MyOtherSyncObject> OtherSyncObject;
[SyncData]
public SyncFloat FloatValue;
}
任何同步基元标记 [SyncData] 属性，将会在当前的 HoloToolkit.Sharing 会话中自动添加到数据模型并同步。
Configuration
---
确保勾选 Player Settings -> Windows Store -> Publishing Settings -> Capabilities 的以下选项:
- SpatialPerception
- InternetClientServer
- PrivateNetworkClientServer
- Microphone capabilities
安装或运行 Server 实例。
Troubleshooting
- 仔细检查 sharing stage 组件上的 Server Address 与 sharing 服务控制台上的地址相匹配
- 确保所有设备都连接在同一个WiFi下。
- 确保所有防火墙设置都正确。Windows 防火墙通过网络类型（私有，公共，家庭）提供给你启用/禁用选项，确保连接类型防火墙是设置的启用。
Invalid Schema Version
SharingService [..\..\Source\Common\Private\SessionListHandshakeLogic.cpp (67)]:
***************************************************************
List Server Handshake Failed: Invalid schema version.
Expected: 17, got 15
Please sync to latest XTools
***************************************************************
- 确保在 HoloToolkit-Unity\External\HoloToolkit\Sharing\Server 目录下的 SharingService.exe 是最新的版本。
Plugins
---
提供了为各中架构特定的 SharingClient.dll ，给 Unity 应用程序访问 sharing API。
这个二进制 dll 是从 原生HoloToolkit\Sharing 编译的
Prefabs
---
联网和共享相关的特性的预设。
Sharing.prefab
- 允许在 Unity 应用程序中共享和联网。
- 运行你在 Windows 和非Windows 设备间通信。
SharingStage.cs 允许您成为主客户端 (典型案例).
Server Address 是运行 HoloToolkit -> Launch Sharing Service 的机器的IP地址
Server Port 显示Server用于通信的端口
AutoJoinSession.cs 用 'Default' 会话名称创建共享会话，该会话名是可以定制的。如果某个会话已经存在则连接到这个会话。
Scripts
---
联网和共享相关特性的脚本。
Editor(Scripts/Editor)
---
仅在编辑器中使用的脚本
SharingMenu.cs
用户可以通过 Unity 编辑器的 HoloToolkit 菜单启动 Sharing Service, Sharing Manager, 和 Profiler
SharingStageEditor.cs
绘制默认 Sharing Stage Inspector 和 添加 SyncRoot Hierarchy 视图，让用户快速验证同步对象更新。
SDK(Scripts/SDK)
---
包含了从原生 HoloToolkit\Sharing 仓库用 SWIG 工具生成的脚本。
Spawning(Scripts/Spawning)
---
使用 sharing 服务批量生成对象的脚本。
PrefabSpawnerManager.cs
SpawnManager 在数据模型中 new SyncSpawnedObject 时基于 prefab 创建对象。这个类可以从 SyncSpawnedObject 继承的任何对象添加删除批量产生 prefab ，从而满使用应用程序能够动态生成 prefab 的需要。
在 SyncRoot 对象里 PrefabSpawnManager 注册到 InstantiatedPrefabs 的SyncArray里。
通过指定哪些类对应于哪个 prefab，可以通过编辑器指定哪个类链接到哪个 prefab。注意 class 字段是当前的一个字符串，必须手工输入（例如，“SyncSpawnedObject”）。这最终可以通过自定义编辑器脚本来改进。
SpawnManager.cs
SpawnManager 负责基于修改数据模型对象数组批量生成对应的对象。它还管理这些生成的对象的生命周期。
这是一个抽象类，你可以通过它实现自定义的 SpawnManager 响应从数据模型中添加或删除的特定同步对象。
SyncSpawnArray.cs
这个数组表示掌控 SyncSpawnedObject 和她的子类。与 SyncArray 相比，这个支持对象的动态类型。
SyncSpawnedObject.cs
SpawnedObject 包含了在另外的设备上与当前设备最初生成对象的同一个位置生成对应对象所需的所有信息。
SyncModel(Scripts/SyncModel)
---
通过 sharing 服务同步数的脚本。
SyncArray.cs
SyncArray class 提供了数据模型中的数据功能。数组能保存整个对象，而不是基元（primitives），因为每个对象都用唯一名称所以。注意这个数组是无序的。
SyncBool.cs
这个 Class 实现了布尔类型基元同步系统。它将添加新的布尔到类中变的简单。
SyncDataAttributes.cs
Used to markup SyncObject classes and SyncPrimitives inside those classes, so that they properly get instantiated when using a hierarchical data model that inherits from SyncObject.
SyncDouble.cs
This class implements the double primitive for the syncing system. It does the heavy lifting to make adding new doubles to a class easy.
SyncFloat.cs
This class implements the float primitive for the syncing system. It does the heavy lifting to make adding new floats to a class easy.
SyncInteger.cs
This class implements the integer primitive for the syncing system. It does the heavy lifting to make adding new integers to a class easy.
SyncLong.cs
This class implements the long primitive for the syncing system. It does the heavy lifting to make adding new longs to a class easy.
SyncObject.cs
The SyncObject class is a container object that can hold multiple SyncPrimitives.
SyncPrimitive.cs
Base primitive used to define an element within the data model. The primitive is defined by a field and a value.
SyncQuaternion.cs
This class implements the Quaternion object primitive for the syncing system. It does the heavy lifting to make adding new Quaternion to a class easy.
SyncString.cs
This class implements the string primitive for the syncing system. It does the heavy lifting to make adding new strings to a class easy.
SyncTransform.cs
This class implements the Transform object primitive for the syncing system. It does the heavy lifting to make adding new transforms to a class easy. A transform defines the position, rotation and scale of an object.
SyncVector3.cs
This class implements the Vector3 object primitive for the syncing system. It does the heavy lifting to make adding new Vector3 to a class easy.
Unity(Scripts/Unity)
---
用来实现 unity 特定同步服务的脚本
DefaultSyncModelAccessor.cs
允许游戏对象的其它组件通过 SyncObject 实例访问共享数据模型的默认行为。
ISyncModelSccessor.cs
允许游戏对象的组件通过 SpawnManager 访问共享数据模型的 Interface。
TransformSynchronizer.cs
通过我的数据模型更新和广播 transform 对象的同步器。
Utilities(Scripts/Utilities)
---
同步服务的工具脚本
AutoJoinSession.cs
允许应用程序在具有有效服务器连接时自动加入指定会话的行为组件。这个类将在整个应用程序生命周期中维护会话连接。
这在拥有程序中主要用于快速测试网络。大多数情况下应该编写一些会话管理代码，以允许用户根据期望的应用程序流程来加入/离开会话。
ConsoleLogWriter.cs
将共享服务日志详细写到Unity引擎的控制台的实用工具类。
DirectPairing.cs
该类允许用户直接与远程客户机进行配对。一方面使用 Receiver 角色，另一方面应该使用 Connector 角色。RemoteAddress 和 RemotePort 是 Connector 角色用的，LocalPort 是给 Receiver 用的。
VoiceChat(Scripts/VoiceChat)
---
语言聊天服务的脚本
MicrophoneReceiver.cs
接收和播放通过会话服务器传输的语音数据。这个数据来自运行 MicrophoneTransmitter 行为的其他客户端。
MicrophoneTransmitter.cs
从你的麦克风发送数据到其它连接到 SessionServer 的客户端。任何接收客户端必须是运行着 MicrophoneReceiver 脚本的。
ServerSessionTracker.cs
ServerSessionTracker 负责列出服务器上存在的各种会话，并暴漏所有这些会话的关联事件。这也是允许应用程序加入或离开会话的 class。实例是在找到连接时通过 Sharing Stage 创建的。
SessionUsersTracker.cs
SessionUsersTracker 保持跟踪当前会话和它的用户。它还暴漏了当前用户加入或离开当前会话时触发的事件。实例时在找到连接时通过 Sharing Stage 创建的。
SharingStage.cs
负责管理应用程序的核心网络层的单例行为。SharingStage具有以下职责：
- 服务器配置（address, port 和 client role）
- 建立和管理服务器连接
- 创建和初始化同步的数据模型（SyncRoot）
- 创建 ServerSessionsTracker 跟踪服务器上的所有会话
- 创建 SessionUsersTracker 跟踪当前会话中的所有用户。
SyncRoot.cs
同步数据模型的根，在改模型下的每个元素都应该定位。SharingStage 将在应用程序初始化时创建和初始化 SyncRoot。
SyncSettings.cs
共享同步设置集合，使用 HoloToolkit 共享同步系统从 SyncObject 中找出在接收数据时需要那些数据模型类。
SyncStateListener.cs
Sharing SyncListener 的 C# 包装，可以通过 Action class 修改。
Test Prefabs
---
用于各种测试场景的 prefab，您可以使用它来实现你自己的想法。
SpawnTestCube.prefab
简单的带有Transform、 Mesh Filter、 Box Collider、 Mesh Renderer和默认同步模型访问组件的 Cube prefab
SpawnTestSphere.prefab
一个简单的带有 Transform、Mesh Filter、 Sphere Collider 和 Mesh Renderer 组件的 Sphere prefab。
SharingSpawnTest 的默认同步模型访问组件故意丢失
Test Scripts
---
测试脚本
CustomMessages.cs
演示如何在客户端之间发送自定义消息的测试类
ImportExportAnchorManager.cs
管理创建锚以及与其他客户端共享锚
RemoteHeadManager.cs
将背地用户的 head transform 广播给在会话中的其它用户，并且在远程用户那添加更新 head transform。Head transform 发送和接收 GameObject 本地空间坐标。
RoomTest.cs
展示创建房间和锚的测试类
SyncObjectSpawner.cs
Class that handles spawning and deleteing sync objects for the SpawningTest.scene. Uses the KeywordManager to spawn objects using voice and keyboard input.
为 SpawningTest.scene 控制生成和删除同步对象。采用 KeywordManager 用语音和键盘输入生成对象。
|---------------|-------|------------------------------------------------------------|
|语音命令 |快捷键 |描述 |
|---------------|-------|------------------------------------------------------------|
| Spawn Basic |`I` 键 | 生成一个带有 `SyncSpawnedObject` 的 cube 基本同步模型 |
| Spawn Custom |`O` 键 | 生成一个带有 `SyncSpawnTestSphere` 的 sphere 自定义同步模型|
| Delete Object |`M` 键 | 删除同步模型类型 |
|_______________|_______|____________________________________________________________|
SyncSpawnTestSphere.cs
使用同步模型属性演示自定义 class 的类。
UserNotifications.cs
用于演示如何在用户离开和进入房间时获取通知。
Tests
---
Tests related to the sharing features. To use the each scene:
与共享特性相关的测试，使用没有一个场景：
- 导航到测试文件夹。
- 双击你想要探索的测试场景。
- Either click "Play" in the unity editor or File -> Build Settings.
- 点击 Unity 编辑器的 "Play" 按钮，或者 File -> Build Settings.
- Add Open Scenes, Platform -> Windows Store, SDK -> Universal 10, Build Type -> D3D, Check 'Unity C# Projects'.
- 启用必要设备的能力 capabilities
- 点击 'Build' 并创建 App 目录. 当编译结束, 打开解决方案并部署到设备.
SharingTest.unity
这个测试展示如何使用 Sharing prefab 并与客户端共享自定义消息。
它还展示了如何在客户端之间共享空间锚以创建一个共享空间。
- 使用 HoloToolkit -> Launch Sharing service 启动共享服务
- 输入控制台显示的IP地址到共享对象的Server Address
- CustomMessages.cs 展示通过通过客户端如何通信特定的信息。
- ImportExportAnchorManager.cs 展示使用共享服务如何创建锚并分享给其它客户端。
- RemoteHeadManager.cs 给远程加入会话的用户绘制一个 cubes 作为 remote head
RoomAndAnchorTest.unity
此测试演示了如何在应用程序中创建新的房间和锚。
它还演示了如何上传和下载新的锚。
- 使用 HoloToolkit -> Launch Sharing service 启动共享服务
- 输入控制台显示的IP地址到共享对象的Server Address
- RoomTest.cs 展示了如何创建、加入及离开房间；也展示了如何创建和下载锚。
SharingSpawnTest.unity
此测试演示如何在场景中和跨网络客户端中生成和删除同步对象。
- 使用 HoloToolkit -> Launch Sharing service 启动共享服务
- 输入控制台显示的IP地址到共享对象的Server Address
- PrefabSpawnManager.cs 运行你在批量生成时使用存储 prefab 引用。
- SyncObjectSpawner.cs 演示如何生成和删除同步对象，以及自定义类型
【转载请说明出处】https://mshololens.cn/d/1044
