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

1、MojingSDK For Unity 接口说明文档资料MojingSDK for Unity3D接口说明文档北京暴风魔镜科技有限公司2016-06版本Version日期Data作者Author注释Comments1.32016.6.6罗敏1、IOS平台发布设置，Home键在右；2、不再支持Unity5.1及以下版本；3、增加魔镜5代、RIO镜片支持；1.32016-06-21刘满松1、支付相关接口增加错误详情回调void MjFailedDetailsCallback(string json)2、支付确认页面增加取消按钮的回调1.32016-06-23罗敏1、增加Unity_IOS Meta

2、l选项的支持；2、增加对Unity5.3.5的支持；法律声明本文档包含的所有内容除特别声明以外，版权均属于北京暴风魔镜科技有限公司所有。未经本公司书面许可，任何单位和个人不得以任何方式（电子机械，包括影印）翻印或转载本文档的任何部分，否则将视为侵权，追究法律责任。正 文 一、简介MojingSDK for Unity3D（下文简称SDK）是为了配合Unity3D软件开发者开发适用于VR眼镜（包括但不限于暴风魔镜公司出品的眼镜）而推出的SDK（Software Development Kit）开发包。开发包主要从手机陀螺仪获取头部跟踪数据、校正静态偏置值，图像抗镜片畸变、蓝牙手柄适配及交互性操作

3、等方面为开发者提供便利性支持。SDK采用Unity3D的标准unitypackage包格式发布，同时支持Windows(X64)平台、Android平台和iOS平台发布。二、开发环境1、Windows 平台发布SDK开发环境为Unity5.2.2(Win 64bit)，提供64位库，采用OpenGL2渲染绘制，支持双眼反畸变渲染，键盘鼠标模拟头部Camera旋转，以及Unity原生Input作为交互。开发者在导入unitypackage之前，需将Unity 图形API设为OpenGL2，如图22所示。2、Android平台发布SDK开发环境为Unity3D 5.2.2(Win)，建议采用Uni

4、ty3D 5.2.2（Win）及以上的版本，Android-SDK版本为 24.0.2，JDK 1.7.0以上；支持暴风魔镜系列、HID标准协议等蓝牙手柄（详见下表2）作为交互外设进行控制，支持Android4.4以上。Android SDK Location配置，如下图1所示。图1 Android SDK Location配置3、iOS平台发布SDK开发环境为Unity3D 5.2.2(Mac) & XCode7.1，建议采用Unity3D 5.2.2（Mac）及以上版本，Xcode采用7.1以上版本，支持Mojing4（魔镜4代手柄）、iCade模式手柄和iPhoneMFi手柄作为交互外设

5、进行控制，支持iOS6.0以上。三、支持的设备1、支持的眼镜及镜片目前支持暴风魔镜所有型号的眼镜镜片，参见表1。厂商 Manufacture产品 Product眼镜 Glasses暴风魔镜暴风魔镜II 标准镜片暴风魔镜III标准镜片Plus B镜片Plus A镜片暴风魔镜IV标准镜片(96)观影镜观影镜魔镜小D标准镜片暴风魔镜5代魔镜5暴风魔镜RIO魔镜RIO表1 SDK支持镜片列表1.1 获取厂商列表 GetManufacturers ( string strLanguageCodeByISO639) 函数功能：获取json文件厂商列表 输入参数：中文（“zh”） 返回值：厂商列表1.2 获

6、取产品列表 GetProducts ( string strManufacturerKey, string strLanguageCodeByISO639) 函数功能：获取Manufacturer下的产品列表 输入参数：厂商信息KEY，“zh” 返回值：产品列表1.3 获取镜片列表 GetGlasses(string strProductKey, string strLanguageCodeByISO639) 函数功能：获取Product下的镜片列表 输入参数：产品信息KEY，“zh” 返回值：镜片列表Mojing.cs，Awake( )中解析出GlassesKey和GlassesName，获

7、取所有镜片的名称和对应的Key，加入glassesKeyList和glassesNameList；Menu.unity示例场景中生成眼镜列表，选择不同的眼镜，产生不同的畸变效果。图2 Game窗口镜片切换下拉菜单效果2、支持的蓝牙手柄SDK包里，凡涉及到蓝牙手柄交互操作的场景demo，均需提前在手机上适配并连接蓝牙手柄，对于不同的系统平台，需要相应的蓝牙手柄做支持，如下表2所示。产品名称支持的系统平台魔镜1代手柄Zeemote JS1 V3Android魔镜2代手柄MojingAndroid魔镜3代手柄Mojing3Android魔镜4代手柄Mojing4AAndroidMojing4iOSH

8、ID标准协议手柄e.g. 小米蓝牙手柄AndroidiCade模式手柄e.g. BETOP 2585 BFMiOSiPhone MFi手柄e.g. steelseriesiOS表2 SDK支持蓝牙手柄列表四、SDK包介绍1、Unity3D版本要求在导入UnityPackage之前，确保Unity3D版本满足SDK包的要求，本文第二部分已详细说明，此处不再赘述。2、导入SDK开发包如下图3所示，包内容如下图4所示。图3 导入 SDK package图4 SDK包文件目录3、SDK示例场景Demo中包含如下7个示例场景，涵盖SDK各个常见易用的功能模块。图5 场景文件夹目录3.1 Menu.uni

9、ty 图6 Menu场景层次图在菜单切换场景中，Button选择提供两种交互模式：（1）蓝牙手柄摇杆键切换Button，OK键按下确定，响应Demo.cs中的回调；（2）GazePointer射线检测 选中Button，触屏按下确定，响应Demo.cs中的回调。Canvas画布下的各个Button回调响应函数，实现对应的场景切换或者模式切换。图7 ButtonOnClick回调响应函数UIListController.cs根据镜片列表信息实例化出镜片Text选项，可通过蓝牙手柄摇杆或GazePointer捕获焦点选择镜片模式。图8 镜片切换下拉菜单3.2 360PhotoDemo.unity图

10、9 360PhotoDemo场景层次图在全景图360PhotoDemo场景中，球体物体材质为全景图片材质，MojingMain实现陀螺仪位姿实时响应，MojingInputManager监听并接受蓝牙外设输入并响应，ruler_x，ruler_y分别为竖直和水平方向的标尺，可测量得到可视范围的角度大小。Canvas画布实现UI Button，EventSystem监听触屏或按键操作，可切回Menu场景。MojingMain.prefab、MojingHead.prefab和MojingInputManager.prefab在AssetsMojingSDKPrefabs目录中已提供，开发人员可根

11、据实际需要添加和修改。3.3 StereoImage.unity StereoImage是为了呈现立体影像而制作的demo场景，对于影像资源具有一定的要求，需提供左右/上下全景影像文件，可参考AssetsDemoMaterialsStereoimage.jpg。在StereoImage场景中，将AssetsDemoModelsUD中的两个球面模型拖入场景中，并分别设置对应的层Left/Right，VR Camera的Camera组件中，Culling Mask分别渲染对应的Left/Right层，运行效果如下图10所示。图10 StereoPhoto场景运行效果与此类似，开发者可以实现立体视频

12、功能，可考虑采用第三方插件EasyMovieTexture（可从Unity Store中获取）实现移动端视频播放， 参数Target Material为渲染的两个球面，属性设置与StereoPhoto场景中设置相同，此处不再赘述，运行效果如下图11所示。图11 StereoVideo场景运行效果3.4 Mojing1stC.unity & Mojing3rdC.unity漫游示例场景中，根据需要拖入MojingFirstCharacterController.prefab或MojingThirdCharacterController.prefab，实现角色控制，MojingInputManag

13、er.prefab监听并接受蓝牙外设指令键值并响应。3.5 MojingLogin_Pay.unityMojingLogin_Pay场景用于示例注册登录支付功能的实现，该模块依赖库文件MJPaySdk.jar、android-query.0.26.7.jar（文件路径：AssetsPluginsAndroid），请求接口调用脚本MojingLoginPay.cs，回调接口脚本Callback.cs（文件路径：AssetsMojingSDKScripts）。具体接口说明，详见本文档五.5部分。图12 MojingLoginPay场景3.6 MojingReport.unity数据统计示例场景用以

14、测试和举例PageStart、PageEnd、SetEvent、AppResume、AppPause接口函数；开发者可在进入场景时调用Unity_AppPageStart，退出场景时调用Unity_AppPageEnd，触发特定事件时调用Unity_AppSetEvent，应用切到前端时调用Unity_AppResume，应用切到后台时调用Unity_AppPause。4、Plugins文件夹图13 Plugins文件夹目录4.1 Plugins/x64存放Windows_x64平台发布所需动态链接库及依赖库文件。4.2 Plugins/Android存放Android插件，包括.jar、.s

15、o、.xml文件等。4.3 Plugins/iOS存放iOS插件，包括.a、.bundle、.m、.mm文件等。开发者可在UnityIOSAPI.h头文件中看到接口函数的声明，具体的函数功能及参数说明见本文第五部分“SDK功能模块”。5、StreamingAssets文件夹json文件用于配置手柄的使用方式以及使能可支持的蓝牙手柄型号。配置文件可以配置例如按键的键值映射、轴转换为gamepad按键、选择使用四向键或者八向键或者配置特定标准HID手柄等功能。图14 StreamingAssets文件夹目录用户可以参考SDK提供的默认的配置文件，并在此基础上修改出自定义的配置文件，默认配置文件说明

16、参考手柄配置文件详细说明，目录：AssetsStreamingAssetsMojingSDKInputMap_mojing_default.json。如开发者需要实现自定义的json配置文件，需在同目录下新加InputMap_mojing_user.json，SDK会自动读取自定义配置文件，获取响应。五、SDK功能模块1、陀螺仪头部跟踪为了获取手机陀螺仪数据，控制场景内相机的位姿，需将场景内默认Camera替换为MojingMain，并且为GameObject添加脚本组件，如图15所示。 图15 MojingMain物体结构及组件1.1 启动头部跟踪 bool Unity_StartTrack

17、er (int nSampleFrequence) 函数功能：启动头部跟踪，此函数必须在调用其它头部跟踪函数之前调用。 输入参数：采样频率，以Hz为单位。内部会判定用户手机头部跟踪可使用的最小采样间隔，如果最小采样间隔不能满足nSampleFrequence参数所指定的采样频率，则自动采用手机允许的最小采样间隔，SDK中设置为100。 返回值：初始化成功返回True，否则返回False。 注意：调用本函数之前，所有其他的头部跟踪相关函数调用都将失败；本函数必须与Unity_StopTracker函数成对调用。1.2 复位YAW旋转角 void Unity_ResetSensorOrientat

18、ion () 函数功能：YAW旋转角度复位，即欧拉角中的横摇角。 输入参数：无。 返回值：无。1.3 开始校准头部跟踪偏置值 bool Unity_StartTrackerCalibration(); 函数功能：强制校准头部跟踪偏置值。 输入参数：无。 返回值：成功清楚偏置值校准状态返回True，否则返回False。 注意：无论是否调用此函数，在StartTracker之后都会自动进入校准状态。1.4 获取头部跟踪偏置值是否已经校准 bool Unity_IsTrackerCalibrated (); 函数功能：判断头部跟踪偏置值是否已完成校正。 输入参数：无。 返回值：已经校准过返回True

19、，否则返回False。1.5 获取当前视角，以矩阵形式表示 void Unity_getLastHeadView (float headView) 函数功能：获取当前视角，以矩阵形式表示。 输入参数：headView 浮点型数组，长度必须是16。 返回值：返回的视角信息存放于headView 数组中。1.6 停止使用头部跟踪 void Unity_StopTracker() 函数功能：停止使用头部跟踪。 输入参数：无。 返回值：无。 注意：调用此函数之后，除Unity_StartTracker( )之外其他的头部跟踪调用都将不可使用；本函数必须与Unity_StartTracker( )函数成

20、对调用。SDK中在程序启动时调用Unity_StartTracker( )，程序退出时调用Unity_StopTracker( )，而并非场景切换时调用，此做法是为了保持整个Application中的陀螺仪坐标系保持一致。1.7 陀螺仪位姿预测（Time Warp） TW_STATE 参数功能：是否启用陀螺仪位姿预测功能。 参数值：设置ConfigItem.cs中TW_STATE值，false为不启用陀螺仪位姿预测；true为启动预测。1.8 是否创建畸变渲染线程 MT_STATE 参数功能：是否为畸变渲染创建独立线程； 参数值：设置ConfigItem.cs中MT_STATE值，false为

21、Unity GL渲染线程与畸变共用同一线程；true时为畸变渲染单起独立线程， Unity5.2.0及以上版本支持此功能发布。1.9 屏幕是否保持常亮 ScreenNeverSleep 参数功能：是否保持屏幕常亮。 注意：设置ConfigItem.cs中ScreenNeverSleep值，ScreenNeverSleep为true时屏幕常亮；ScreenNeverSleep为false时Screen.sleepTimeout保持系统设置。2、图像抗镜片畸变反畸变是为了适用于对抗镜片畸变、色散而必须在显示图像中做特殊的图形处理和颜色处理的过程。如无特别声明，所有畸变函数的调用必须在Open GL

22、线程中进行。2.1 启用畸变 bool Unity_EnterMojingWorld(string sGlassedName, bool bMultithread, bool bTimeWarp ) 函数功能：启动畸变系统。 输入参数： GlassesName：指定畸变需要适配的眼镜型号，参见表1；bMultithread：是否创建独立的畸变线程，详见1.9；bTimeWarp：陀螺仪位姿预测模式，详见1.8； 返回值：True 表示执行成功，False表示执行失败。2.2 获取推荐视场角(FOV) float Unity_GetGlassesFOV () 函数功能：获取推荐的视场角，以角度为

23、单位。 输入参数：无。 返回值：以角度为单位的视场角大小。2.3 绘制本地纹理 void SetTextureID(int left_textureID, int right_textureID) 函数功能：SDK根据当前的眼镜型号、畸变参数、和手机屏幕尺寸，生成一副纹理。 输入参数：left_textureID为获取本地左眼纹理ID，right_textureID为获取本地右眼纹理ID，可通过Unity_SetTextureID (int iLeftTextureID, int iRightTextureID )接口获取。 返回值：无。 注意：通过此函数得到Texture句柄以后，应该根据纹

24、理的类型绘制对应的图像内容，图像内容应该充满整个纹理；推荐分别获取单眼的纹理并分别绘制图像后交由绘制畸变图像方法绘制；使用自行创建的纹理绘制并绘制图像后交由反畸变系统绘制的方法依然被SDK支持，但是不推荐使用。2.4 绘制场景变化通知 bool Unity_OnSurfaceChanged(int newWidth, int newHeight) 函数功能：当绘制场景变化时，通知SDK根据新的屏幕尺寸计算畸变参数。 输入参数：newWidth 新的窗口宽度值，必须是窗口的长边； newHeigth 新的窗口高度值，必须是窗口的短边。 返回值：True 表示执行成功，False表示执行失败。 注

25、意：此函数可以在OpenGL线程之外调用； 新的绘制效果将在下一次调用DrawTexture函数时生效； 初始化SDK调用Init函数时会根据当时的窗口信息取得适用的屏幕尺寸并在Unity_EnterMojingWorld时用该尺寸初始化畸变参数表。2.5 修改畸变适配的眼镜型号 bool Unity_ChangeMojingWorld(string sGlassedName ) 函数功能：根据GlassesName，更改绘制图像在屏幕上的位置。 输入参数： GlassesName：指定畸变需要适配的眼镜型号； 返回值：True 表示执行成功，False表示执行失败。 注意：此函数可以在Ope

26、nGL线程之外调用；新的绘制效果将在下一次调用DrawTexture函数时生效。2.6 刷新镜片渲染效果 UpdateProfile( ) 函数功能：刷新FOV，获取更新镜片渲染效果 输入参数：无 返回值：无2.7 停用畸变 bool Unity_LeaveMojingWorld() 函数功能：停止使用畸变。 输入参数：无。 返回值：无。注意：此函数必须与Unity_EnterMojingWorld在同一OpenGL线程中成对调用。2.8 获取默认的魔镜世界对应信息 string Unity_GetDefaultMojingWorld(string strLanguageCodeByISO63

27、9) 函数功能：获取默认的魔镜世界的对应信息。 输入参数：strLanguageCodeByISO639输入参数语言码参考ISO 639-1，使用两位不区 分大小写的字符。如果对应的条目没有设定指定的语言码的显示内容，则 返回的节点中不会有Display节点。 返回值： 返回JSON字符串： 失败时，内容如下：ERROR:Get default MojingWorld failed. 成功则，类似内容如下： ClassName:GlassInfo,ReleaseDate:20151028,Manufacturer:Display:厂家的名字，没有设定则不存在此节点, ID:不会改变的唯一标识,

28、 URL:URLOFManufacturerImage,Size=256x256, KEY:用于后续操作的动态字符串密钥，代表此厂商-产品-镜 片组合。这个Key可以直接用于EnterMojingWorld,Product: Display:产品的名字，没有设定则不存在此节点,ID:不会改变的唯一标识, URL:URL OF Product Image , Size = 256 x256, KEY:用于后续操作的动态字符串密钥，代表此厂商-产品-镜 片组合。这个Key可以直接用于EnterMojingWorld,Glass: Display:镜片的名字，没有设定则不存在此节点, ID:不会改变

29、的唯一标识, URL:URL OF Glass Image , Size = 256 x256,KEY:用于后续操作的动态字符串密钥，代表此厂商-产品-镜片组合。这个Key可以直接用于EnterMojingWorld 2.9 获取最后一次切换的魔镜世界对应信息 string Unity_GetLastMojingWorld(string strLanguageCodeByISO639) 函数功能：获取最后一次切换的魔镜世界的对应信息。 输入参数：strLanguageCodeByISO639输入参数语言码参考ISO 639-1，使用两位不区 分大小写的字符。如果对应的条目没有设定指定的语言码的

30、显示内容，则 返回的节点中不会有Display节点。 返回值： 返回JSON字符串： 失败时，内容如下：ERROR:Get last MojingWorld failed.成功时返回内容格式同Unity_GetDefaultMojingWorld()。2.10 叠加绘制2D图层 void Unity_SetOverlay3D(int iEyeType, int iTextureID, float fWidth, float fHeight, float fDistanceInMetre) 函数功能：在视口坐标系中心位置，叠加绘制出3D场景外的2D Resource图层。 输入参数： iEyeType： 1-绘制左眼视窗内资源，2-绘制右眼视窗内资源，3-同时绘制左眼视窗及右眼视窗内资源；iTextureID：2DResource本地纹理句柄