MojingSDK For Unity 接口说明文档资料.docx

MojingSDK For Unity 接口说明文档资料.docx

《MojingSDK For Unity 接口说明文档资料.docx》由会员分享，可在线阅读，更多相关《MojingSDK For Unity 接口说明文档资料.docx（67页珍藏版）》请在冰点文库上搜索。

MojingSDKForUnity接口说明文档资料

MojingSDKforUnity3D

接口说明文档

北京暴风魔镜科技有限公司

2016-06

版本

Version

日期

Data

作者

Author

注释

Comments

1.3

2016.6.6

罗敏

1、IOS平台发布设置，Home键在右；

2、不再支持Unity5.1及以下版本；

3、增加魔镜5代、RIO镜片支持；

1.3

2016-06-21

刘满松

1、支付相关接口增加错误详情回调voidMjFailedDetailsCallback（stringjson）

2、支付确认页面增加取消按钮的回调

1.3

2016-06-23

罗敏

1、增加Unity_IOSMetal选项的支持；

2、增加对Unity5.3.5的支持；

法律声明

本文档包含的所有内容除特别声明以外，版权均属于北京暴风魔镜科技有限公司所有。

未经本公司书面许可，任何单位和个人不得以任何方式（电子机械，包括影印）翻印或转载本文档的任何部分，否则将视为侵权，追究法律责任。

正文

Ø一、简介

MojingSDKforUnity3D（下文简称SDK）是为了配合Unity3D软件开发者开发适用于VR眼镜（包括但不限于暴风魔镜公司出品的眼镜）而推出的SDK（SoftwareDevelopmentKit）开发包。

开发包主要从手机陀螺仪获取头部跟踪数据、校正静态偏置值，图像抗镜片畸变、蓝牙手柄适配及交互性操作等方面为开发者提供便利性支持。

SDK采用Unity3D的标准unitypackage包格式发布，同时支持Windows（X64）平台、Android平台和iOS平台发布。

二、开发环境

1、Windows平台发布

SDK开发环境为Unity5.2.2（Win64bit），提供64位库，采用OpenGL2渲染绘制，支持双眼反畸变渲染，键盘鼠标模拟头部Camera旋转，以及Unity原生Input作为交互。

开发者在导入unitypackage之前，需将Unity图形API设为OpenGL2，如图22所示。

2、Android平台发布

SDK开发环境为Unity3D5.2.2（Win），建议采用Unity3D5.2.2（Win）及以上的版本，Android-SDK版本为24.0.2，JDK1.7.0以上；支持暴风魔镜系列、HID标准协议等蓝牙手柄（详见下表2）作为交互外设进行控制，支持Android4.4以上。

AndroidSDKLocation配置，如下图1所示。

图1AndroidSDKLocation配置

3、iOS平台发布

SDK开发环境为Unity3D5.2.2（Mac）&XCode7.1，建议采用Unity3D5.2.2（Mac）及以上版本，Xcode采用7.1以上版本，支持Mojing4（魔镜4代手柄）、iCade模式手柄和iPhoneMFi手柄作为交互外设进行控制，支持iOS6.0以上。

三、支持的设备

1、支持的眼镜及镜片

目前支持暴风魔镜所有型号的眼镜镜片，参见表1。

厂商Manufacture

产品Product

眼镜Glasses

暴风魔镜

暴风魔镜II

标准镜片

暴风魔镜III

标准镜片

PlusB镜片

PlusA镜片

暴风魔镜IV

标准镜片（96）

观影镜

观影镜

魔镜小D

标准镜片

暴风魔镜5代

魔镜5

暴风魔镜RIO

魔镜RIO

表1SDK支持镜片列表

1.1获取厂商列表

ØGetManufacturers（stringstrLanguageCodeByISO639）

Ø函数功能：

获取json文件厂商列表

Ø输入参数：

中文（“zh”）

Ø返回值：

厂商列表

1.2获取产品列表

ØGetProducts（stringstrManufacturerKey,stringstrLanguageCodeByISO639）

Ø函数功能：

获取Manufacturer下的产品列表

Ø输入参数：

厂商信息KEY，“zh”

Ø返回值：

产品列表

1.3获取镜片列表

ØGetGlasses（stringstrProductKey,stringstrLanguageCodeByISO639）

Ø函数功能：

获取Product下的镜片列表

Ø输入参数：

产品信息KEY，“zh”

Ø返回值：

镜片列表

Mojing.cs，Awake（）中解析出GlassesKey和GlassesName，获取所有镜片的名称和对应的Key，加入glassesKeyList和glassesNameList；Menu.unity示例场景中生成眼镜列表，选择不同的眼镜，产生不同的畸变效果。

图2Game窗口镜片切换下拉菜单效果

2、支持的蓝牙手柄

SDK包里，凡涉及到蓝牙手柄交互操作的场景demo，均需提前在手机上适配并连接蓝牙手柄，对于不同的系统平台，需要相应的蓝牙手柄做支持，如下表2所示。

产品

名称

支持的系统平台

魔镜1代手柄

ZeemoteJS1V3

Android

魔镜2代手柄

Mojing

Android

魔镜3代手柄

Mojing3

Android

魔镜4代手柄

Mojing4A

Android

Mojing4

iOS

HID标准协议手柄

e.g.小米蓝牙手柄

Android

iCade模式手柄

e.g.BETOP2585BFM

iOS

iPhoneMFi手柄

e.g.steelseries

iOS

表2SDK支持蓝牙手柄列表

四、SDK包介绍

1、Unity3D版本要求

在导入UnityPackage之前，确保Unity3D版本满足SDK包的要求，本文第二部分已详细说明，此处不再赘述。

2、导入SDK开发包

如下图3所示，包内容如下图4所示。

图3导入SDKpackage

图4SDK包文件目录

3、SDK示例场景

Demo中包含如下7个示例场景，涵盖SDK各个常见易用的功能模块。

图5场景文件夹目录

3.1Menu.unity

图6Menu场景层次图

在菜单切换场景中，Button选择提供两种交互模式：

（1）蓝牙手柄摇杆键切换Button，OK键按下确定，响应Demo.cs中的回调；

（2）GazePointer射线检测选中Button，触屏按下确定，响应Demo.cs中的回调。

Canvas画布下的各个Button回调响应函数，实现对应的场景切换或者模式切换。

图7ButtonOnClick回调响应函数

UIListController.cs根据镜片列表信息实例化出镜片Text选项，可通过蓝牙手柄摇杆或GazePointer捕获焦点选择镜片模式。

图8镜片切换下拉菜单

3.2360PhotoDemo.unity

图9360PhotoDemo场景层次图

在全景图360PhotoDemo场景中，球体物体材质为全景图片材质，MojingMain实现陀螺仪位姿实时响应，MojingInputManager监听并接受蓝牙外设输入并响应，ruler_x，ruler_y分别为竖直和水平方向的标尺，可测量得到可视范围的角度大小。

Canvas画布实现UIButton，EventSystem监听触屏或按键操作，可切回Menu场景。

MojingMain.prefab、MojingHead.prefab和MojingInputManager.prefab在Assets\MojingSDK\Prefabs目录中已提供，开发人员可根据实际需要添加和修改。

3.3StereoImage.unity

StereoImage是为了呈现立体影像而制作的demo场景，对于影像资源具有一定的要求，需提供左右/上下全景影像文件，可参考Assets\Demo\Materials\Stereoimage.jpg。

在StereoImage场景中，将Assets\Demo\Models\UD中的两个球面模型拖入场景中，并分别设置对应的层Left/Right，VRCamera的Camera组件中，CullingMask分别渲染对应的Left/Right层，运行效果如下图10所示。

图10StereoPhoto场景运行效果

与此类似，开发者可以实现立体视频功能，可考虑采用第三方插件EasyMovieTexture（可从UnityStore中获取）实现移动端视频播放，参数TargetMaterial为渲染的两个球面，属性设置与StereoPhoto场景中设置相同，此处不再赘述，运行效果如下图11所示。

图11StereoVideo场景运行效果

3.4Mojing1stC.unity&Mojing3rdC.unity

漫游示例场景中，根据需要拖入MojingFirstCharacterController.prefab或MojingThirdCharacterController.prefab，实现角色控制，MojingInputManager.prefab监听并接受蓝牙外设指令键值并响应。

3.5MojingLogin_Pay.unity

MojingLogin_Pay场景用于示例注册登录支付功能的实现，该模块依赖库文件MJPaySdk.jar、android-query.0.26.7.jar（文件路径：

Assets\Plugins\Android），请求接口调用脚本MojingLoginPay.cs，回调接口脚本Callback.cs（文件路径：

Assets\MojingSDK\Scripts）。

具体接口说明，详见本文档五.5部分。

图12MojingLoginPay场景

3.6MojingReport.unity

数据统计示例场景用以测试和举例PageStart、PageEnd、SetEvent、AppResume、AppPause接口函数；开发者可在进入场景时调用Unity_AppPageStart，退出场景时调用Unity_AppPageEnd，触发特定事件时调用Unity_AppSetEvent，应用切到前端时调用Unity_AppResume，应用切到后台时调用Unity_AppPause。

4、Plugins文件夹

图13Plugins文件夹目录

4.1Plugins/x64

存放Windows_x64平台发布所需动态链接库及依赖库文件。

4.2Plugins/Android

存放Android插件，包括.jar、.so、.xml文件等。

4.3Plugins/iOS

存放iOS插件，包括.a、.bundle、.m、.mm文件等。

开发者可在UnityIOSAPI.h头文件中看到接口函数的声明，具体的函数功能及参数说明见本文第五部分“SDK功能模块”。

5、StreamingAssets文件夹

json文件用于配置手柄的使用方式以及使能可支持的蓝牙手柄型号。

配置文件可以配置例如按键的键值映射、轴转换为gamepad按键、选择使用四向键或者八向键或者配置特定标准HID手柄等功能。

图14StreamingAssets文件夹目录

用户可以参考SDK提供的默认的配置文件，并在此基础上修改出自定义的配置文件，默认配置文件说明参考手柄配置文件详细说明，目录：

Assets\StreamingAssets\MojingSDK\InputMap_mojing_default.json。

如开发者需要实现自定义的json配置文件，需在同目录下新加InputMap_mojing_user.json，SDK会自动读取自定义配置文件，获取响应。

五、SDK功能模块

1、陀螺仪头部跟踪

为了获取手机陀螺仪数据，控制场景内相机的位姿，需将场景内默认Camera替换为MojingMain，并且为GameObject添加脚本组件，如图15所示。

图15MojingMain物体结构及组件

1.1启动头部跟踪

ØboolUnity_StartTracker（intnSampleFrequence）

Ø函数功能：

启动头部跟踪，此函数必须在调用其它头部跟踪函数之前调用。

Ø输入参数：

采样频率，以Hz为单位。

内部会判定用户手机头部跟踪可使用的最小采样间隔，如果最小采样间隔不能满足nSampleFrequence参数所指定的采样频率，则自动采用手机允许的最小采样间隔，SDK中设置为100。

Ø返回值：

初始化成功返回True，否则返回False。

Ø注意：

调用本函数之前，所有其他的头部跟踪相关函数调用都将失败；

本函数必须与Unity_StopTracker函数成对调用。

1.2复位YAW旋转角

ØvoidUnity_ResetSensorOrientation（）

Ø函数功能：

YAW旋转角度复位，即欧拉角中的横摇角。

Ø输入参数：

无。

Ø返回值：

无。

1.3开始校准头部跟踪偏置值

ØboolUnity_StartTrackerCalibration（）;

Ø函数功能：

强制校准头部跟踪偏置值。

Ø输入参数：

无。

Ø返回值：

成功清楚偏置值校准状态返回True，否则返回False。

Ø注意：

无论是否调用此函数，在StartTracker之后都会自动进入校准状态。

1.4获取头部跟踪偏置值是否已经校准

ØboolUnity_IsTrackerCalibrated（）;

Ø函数功能：

判断头部跟踪偏置值是否已完成校正。

Ø输入参数：

无。

Ø返回值：

已经校准过返回True，否则返回False。

1.5获取当前视角，以矩阵形式表示

ØvoidUnity_getLastHeadView（float[]headView）

Ø函数功能：

获取当前视角，以矩阵形式表示。

Ø输入参数：

headView浮点型数组，长度必须是16。

Ø返回值：

返回的视角信息存放于headView数组中。

1.6停止使用头部跟踪

ØvoidUnity_StopTracker（）

Ø函数功能：

停止使用头部跟踪。

Ø输入参数：

无。

Ø返回值：

无。

Ø注意：

调用此函数之后，除Unity_StartTracker（）之外其他的头部跟踪调用都将不可使用；

本函数必须与Unity_StartTracker（）函数成对调用。

SDK中在程序启动时调用Unity_StartTracker（），程序退出时调用Unity_StopTracker（），而并非场景切换时调用，此做法是为了保持整个Application中的陀螺仪坐标系保持一致。

1.7陀螺仪位姿预测（TimeWarp）

ØTW_STATE

Ø参数功能：

是否启用陀螺仪位姿预测功能。

Ø参数值：

设置ConfigItem.cs中TW_STATE值，false为不启用陀螺仪位姿预测；true为启动预测。

1.8是否创建畸变渲染线程

ØMT_STATE

Ø参数功能：

是否为畸变渲染创建独立线程；

Ø参数值：

设置ConfigItem.cs中MT_STATE值，false为UnityGL渲染线程与畸变共用同一线程；true时为畸变渲染单起独立线程，Unity5.2.0及以上版本支持此功能发布。

1.9屏幕是否保持常亮

ØScreenNeverSleep

Ø参数功能：

是否保持屏幕常亮。

Ø注意：

设置ConfigItem.cs中ScreenNeverSleep值，ScreenNeverSleep为true时屏幕常亮；ScreenNeverSleep为false时Screen.sleepTimeout保持系统设置。

2、图像抗镜片畸变

反畸变是为了适用于对抗镜片畸变、色散而必须在显示图像中做特殊的图形处理和颜色处理的过程。

如无特别声明，所有畸变函数的调用必须在OpenGL线程中进行。

2.1启用畸变

ØboolUnity_EnterMojingWorld（stringsGlassedName,boolbMultithread,boolbTimeWarp）

Ø函数功能：

启动畸变系统。

Ø输入参数：

GlassesName：

指定畸变需要适配的眼镜型号，参见表1；

bMultithread：

是否创建独立的畸变线程，详见1.9；

bTimeWarp：

陀螺仪位姿预测模式，详见1.8；

Ø返回值：

True表示执行成功，False表示执行失败。

2.2获取推荐视场角（FOV）

ØfloatUnity_GetGlassesFOV（）

Ø函数功能：

获取推荐的视场角，以角度为单位。

Ø输入参数：

无。

Ø返回值：

以角度为单位的视场角大小。

2.3绘制本地纹理

ØvoidSetTextureID（intleft_textureID,intright_textureID）

Ø函数功能：

SDK根据当前的眼镜型号、畸变参数、和手机屏幕尺寸，生成一副纹理。

Ø输入参数：

left_textureID为获取本地左眼纹理ID，right_textureID为获取本地右眼纹理ID，可通过Unity_SetTextureID（intiLeftTextureID,intiRightTextureID）接口获取。

Ø返回值：

无。

Ø注意：

通过此函数得到Texture句柄以后，应该根据纹理的类型绘制对应的图像内容，图像内容应该充满整个纹理；

推荐分别获取单眼的纹理并分别绘制图像后交由绘制畸变图像方法绘制；

使用自行创建的纹理绘制并绘制图像后交由反畸变系统绘制的方法依然被SDK支持，但是不推荐使用。

2.4绘制场景变化通知

ØboolUnity_OnSurfaceChanged（intnewWidth,intnewHeight）

Ø函数功能：

当绘制场景变化时，通知SDK根据新的屏幕尺寸计算畸变参数。

Ø输入参数：

newWidth新的窗口宽度值，必须是窗口的长边；

newHeigth新的窗口高度值，必须是窗口的短边。

Ø返回值：

True表示执行成功，False表示执行失败。

Ø注意：

此函数可以在OpenGL线程之外调用；

新的绘制效果将在下一次调用DrawTexture函数时生效；

初始化SDK调用Init函数时会根据当时的窗口信息取得适用的屏幕尺寸并在Unity_EnterMojingWorld时用该尺寸初始化畸变参数表。

2.5修改畸变适配的眼镜型号

ØboolUnity_ChangeMojingWorld（stringsGlassedName）

Ø函数功能：

根据GlassesName，更改绘制图像在屏幕上的位置。

Ø输入参数：

GlassesName：

指定畸变需要适配的眼镜型号；

Ø返回值：

True表示执行成功，False表示执行失败。

Ø注意：

此函数可以在OpenGL线程之外调用；

新的绘制效果将在下一次调用DrawTexture函数时生效。

2.6刷新镜片渲染效果

ØUpdateProfile（）

Ø函数功能：

刷新FOV，获取更新镜片渲染效果

Ø输入参数：

无

Ø返回值：

无

2.7停用畸变

ØboolUnity_LeaveMojingWorld（）

Ø函数功能：

停止使用畸变。

Ø输入参数：

无。

Ø返回值：

无。

注意：

此函数必须与Unity_EnterMojingWorld在同一OpenGL线程中成对调用。

2.8获取默认的魔镜世界对应信息

ØstringUnity_GetDefaultMojingWorld（stringstrLanguageCodeByISO639）

Ø函数功能：

获取默认的魔镜世界的对应信息。

Ø输入参数：

strLanguageCodeByISO639输入参数语言码参考ISO639-1，使用两位不区分大小写的字符。

如果对应的条目没有设定指定的语言码的显示内容，则返回的节点中不会有Display节点。

Ø返回值：

返回JSON字符串：

失败时，内容如下：

{

"ERROR":

"GetdefaultMojingWorldfailed."

}

成功则，类似内容如下：

{

"ClassName":

"GlassInfo",

"ReleaseDate":

"20151028",

"Manufacturer":

{

"Display":

"厂家的名字，没有设定则不存在此节点",

"ID":

不会改变的唯一标识,

"URL":

"URL OF Manufacturer Image , Size = 256 x256",

"KEY":

"用于后续操作的动态字符串密钥，代表此厂商-产品-镜片组合。

这个Key可以直接用于EnterMojingWorld"

},

"Product":

{

"Display":

"产品的名字，没有设定则不存在此节点",

"ID":

不会改变的唯一标识,

"URL":

"URLOFProductImage,Size=256x256",

"KEY":

"用于后续操作的动态字符串密钥，代表此厂商-产品-镜片组合。

这个Key可以直接用于EnterMojingWorld"

},

"Glass":

{

"Display":

"镜片的名字，没有设定则不存在此节点",

"ID":

不会改变的唯一标识,

"URL":

"URLOFGlassImage,Size=256x256",

"KEY":

"用于后续操作的动态字符串密钥，代表此厂商-产品-镜片组合。

这个Key可以直接用于EnterMojingWorld"

}}

2.9获取最后一次切换的魔镜世界对应信息

ØstringUnity_GetLastMojingWorld（stringstrLanguageCodeByISO639）

Ø函数功能：

获取最后一次切换的魔镜世界的对应信息。

Ø输入参数：

strLanguageCodeByISO639输入参数语言码参考ISO639-1，使用两位不区分大小写的字符。

如果对应的条目没有设定指定的语言码的显示内容，则返回的节点中不会有Display节点。

Ø返回值：

返回JSON字符串：

失败时，内容如下：

{

"ERROR":

"GetlastMojingWorldfailed."

}

成功时返回内容格式同Unity_GetDefaultMojingWorld（）。

2.10叠加绘制2D图层

ØvoidUnity_SetOverlay3D（intiEyeType,intiTextureID,floatfWidth,floatfHeight,floatfDistanceInMetre）

Ø函数功能：

在视口坐标系中心位置，叠加绘制出3D场景外的2DResource图层。

Ø输入参数：

iEyeType：

1---绘制左眼视窗内资源，

2---绘制右眼视窗内资源，

3---同时绘制左眼视窗及右眼视窗内资源；

iTextureID：

2DResource本地纹理句柄