插件介绍

这篇介绍以及整个文档适用于与EasyAR Sense 3.1或更高版本一同发布的EasyAR Sense Unity Plugin。 老版本应阅读与EasyAR Sense (SDK)文档在一起的说明, EasyAR Sense 1.0EasyAR Sense 2.0

EasyAR Sense Unity Plugin是一个建立在EasyAR Sense C# API之上的非常薄的封装,用于在Unity中暴露EasyAR Sense的功能。建议阅读 EasyAR Sense 文档 来理解EasyAR Sense是如何工作的。

插件并未被设计成兼容多个版本的EasyAR Sense,因此插件仍旧使用与EasyAR Sense相同的版本规则。插件的发布包内包含了EasyAR Sense的库文件,因此在使用插件的时候不需要再使用独立的EasyAR Sense。插件中的EasyAR Sense文件与同版本的EasyAR Sense二进制相同。如果你在尝试让插件运行在在不同版本的EasyAR Sense上,必须保证csapi与库文件版本一致。

EasyAR Sense Unity Plugin的所有代码经过良好的接口设计且都是开源的。你可以直接使用这个插件来快速创建AR体验,也可以参考插件代码来更加灵活和自定义的使用EasyAR Sense接口和功能,或是创建属于自己的Unity插件。

深入EasyAR Sense Unity插件

Scripts

插件设计为是一个EasyAR Sense的薄封装,因此大多数脚本都是EasyAR Sense组件在3D场景中的控制器,在Unity环境中提供一些扩展能力。它可以辅助组织和连接EasyAR Sense的组件。

插件尽可能多的使用了Unity本身的功能,比如使用OnEnable/OnDisable来控制start/stop。大多数EasyAR Sense功能都可以不需要写脚本直接工作。插件并不封装EasyAR Sense的所有功能,EasyAR Sense的所有功能都由C# API直接暴露到Unity环境,并可以从MonoBehaviour中访问。

插件在ARAssembly中实现了一种对所有EasyAR Sense组件的典型的组装策略,同时在ARSession控制数据流。但这并不是EasyAR Sense的所有能力。通过EasyAR Sense API的强大灵活性,你可以重写这两个脚本从而实现自定义的AR工作流。

这个插件是开源的。代码中有所有公有类型和成员的中英文文档。你可以自由修改脚本以扩展渲染管线支持或创建自定义工作流。

兼容性提示:在大多数情况下,自定义功能(比如found/lost事件处理或控制场景中的物体等)可以通过现有接口实现,这种情况下不应修改EasyAR内部脚本。这是因为插件不保证脚本设计的兼容性。所有 EasyAR 文件夹内部的资源将在不同发布版本中随时改变且不会有特殊通知。

Editors

插件提供了一些编辑器功能以辅助开发,包括

  • 运行前 Inspector上可配置的脚本输入参数

  • 运行时控制,比如CenterMode 和 HorizontalFlipMode

  • license key和云服务配置的菜单项

  • image target的gizmo

  • 生成image target data的工具

Prefabs

Prefabs 可以辅助快速创建AR场景。如果你不熟悉EasyAR Sense,通常使用prefab会是很好的开始。但如果你已经可以在场景中手动安排脚本,那这些prefab并不是必须的。

Prefabs分为两种类型:

  • Primitive,在大多数情况下是空节点加上EasyAR Sense的一个组件,在构建自定义AR场景的时候很有用。

  • Composite,是primitives的组合,用于提供通常的使用场景,对不熟悉组装系统的新手来说非常有用。

Samples

插件的发布包含了展示不同EasyAR Sense功能以及不同算法组合工作的样例。

如果你在 下载页 寻找样例,需要确保下载名字中含有 Sample 的发布包,它们包含EasyAR Unity Plugin以及对应的样例。在同一页面中你也可以找到插件本身的下载,插件的发布包名字中不包含 Sample ,它是纯粹的插件,不包含可运行的场景。

插件的样例 位于 Samples 文件夹中。尽管Unity会在同一个VS工程中打开所有脚本,但它们并不是插件的一部分。

插件的样例有一个启动器,你可以从启动器中打开大部分样例。如果要使用这个启动器,必须在Unity的build settings中添加启动器以及所有被其引用的场景。

插件的样例展示API如何使用以及EasyAR Sense如何工作,其代码逻辑是非常直接的。你可以基于样例构建自己的应用,或是复制部分样例代码到自己的工程中。但需要注意的是,样例并不是插件,所有样例的代码都不会保证在任何情况下可以不做修改而直接重用。

EasyAR Sense 及其Unity插件包含丰富的API。虽然样例中展示了重要的功能和使用,还是有很多API调用与功能使用情况未覆盖。如果样例工程不能满足项目需求,可以尝试先查看插件中MonoBehaviours的接口以及对应的EasyAR Sense组件功能。

从样例入手,它们会帮你理解EasyAR Sense及其 Unity Plugin 是如何工作的。