开发接口

VOID AR SDK提供接口有三种方式：

方式一：直接调用API方法，例如：

VoidAR.GetInstance().startMarkerlessTracking();

方式二：重写基类方法或者实现接口（interface），例如：

 protected override IMarker SetCloudVideoComponent(GameObject markerTarget, GameObject videoPlayTarget, string markerName, string videoPath){
 ...  
 }

方式三：VoidAREvent事件机制，例如：

AddEventListener(VoidAREvent.FIND, OnFind);

VoidAREvent属性如下： name：事件名称； currentTarget：事件目标，可以获取事件派发目标对象。 data：事件数据，比如云资源加载时，data为进度数据。

下面为VoidAR SDK的主要功能点提供的开发接口：

1、本地识别

识别和丢失接口：

ImageTarget对象上脚本组件ImageTargetBehaviour提供事件派发机制。

void Awake() {
    //侦听识别事件
    AddEventListener(VoidAREvent.FIND, OnFind);
    AddEventListener(VoidAREvent.LOST, OnLost);
}
//Find事件处理
void OnFind(VoidAREvent evt){
    Debug.Log("OnFind");
}
//Lost事件处理
void OnLost(VoidAREvent evt){
    Debug.Log("OnLost");
}

目标识别成功时派发FIND事件，目标丢失时派发LOST事件。

2、云识别

云识别需要在ARCamera上添加CloudController脚本组件，CloudController提供了云识别状态，云资源下载，云识别自定义数据处理等接口。

云识别数据成功响应：指云服务器已经成功识别了目标，返回识别结果。

  /// <summary>
  /// 云识别数据成功响应
  /// </summary>
  /// <param name="url">资源URL</param>
  /// <param name="name">资源名称</param>
  /// <param name="metadata">扩展数据</param>
  protected override void OnSuccess(string url, string name, string metadata)
  {
      //默认AB模型资源Assetsbundle通过WWW加载，云视频创建视频播放器，
      //可以通过自定义数据实现云识别目标自定义创建（创建完成后，通过VoidAR.GetInstance().addCloudTarget()接口加入到SDK识别）
      base.OnSuccess(url, name, metadata);
      Debug.Log("OnSuccess metadata:" + metadata);
  }

云平台添加的自定义数据通过此方法获取。

设置云视频组件：云视频播放时，可以扩展播放器，处理播放事件

  /// <summary>
    /// 设置云视频组件
    /// 可以设置扩展后的ImageTargetBehaviour和VideoPlayBehaviour（使用Unity5.6原生播放器）
    /// </summary>
    /// <param name="markerTarget">marker目标对象</param>
    /// <param name="videoPlayTarget">视频播放器对象</param>
    /// <param name="markerName">marker图片</param>
    /// <param name="videoPath">云视频路径</param>
    /// <returns>IMarker接口对象</returns>
    protected override IMarker SetCloudVideoComponent(GameObject markerTarget, GameObject videoPlayTarget, string markerName, string videoPath)
    {
        var itb = markerTarget.AddComponent<ImageTargetBase>();
        itb.AddEventListener(VoidAREvent.FIND, OnFind);
        itb.AddEventListener(VoidAREvent.LOST, OnFind);
        itb.SetPath(markerName);
        var vpb = videoPlayTarget.AddComponent<VideoPlayBehaviour>();
        vpb.path = videoPath;
        return itb;
    }

消息类事件：

  //云识别目标本地创建完成（开始跟踪）
  AddEventListener(VoidAREvent.COMPLETE, OnComplete);
  //AB资源下载进度
  AddEventListener(VoidAREvent.PROGRESS, OnDownload);
  //异常通知
  AddEventListener(VoidAREvent.ERROR, OnError);

3、VOID SLAM

启动和停止接口：需要在跟踪目标GameObject上添加ITricking接口组件，SDK默认实现类为MarkerlessTracking。ITricking接口用于获取SLAM状态，包括异常情况。

public interface ITricking
{
    bool GetActive();
    int GetTrackingState();
    //跟踪活动状态
    void SetActive(bool value);
    //跟踪反馈（可以根据stateCode的值判断异常状态，具体参见MarkerlessTracking代码）
    void UpdateTracking(int stateCode);
}

SLAM异常状态代码目前有：

1099：网络错误；

501：开发者帐号异常，帐号没有填写或者帐号数据不正确；

101：帐号使用次数超过限制

SLAM使用接口：

//启用跟踪
VoidAR.GetInstance().startMarkerlessTracking();
//停止跟踪
VoidAR.GetInstance().resetMarkerless();

4、视频播放

视频播放接口：

通过IMediaPlayer接口可实现视频播放功能，在移动平台上通过VoidVideoPlayer类实现，在其他平台上用UnityVideoPlayer类（Unity官方播放器）实现。 IMediaPlayer提供的接口如下：

public interface IMediaPlayer {
    //播放源
    string source { get; set; }
    //时间长度
    float duration { get; }
    //播放进度
    float seek { get; set; }
    //播放
    bool Play();
    //暂停
    bool Pause();
    //停止
    bool Stop();
    //是否播放中
    bool isPlaying { get; }
    //是否加载完成
    bool isPrepared { get; }
    //获取播放视频纹理
    Texture texture { get; }
    //音量大小（暂未开放）
    float volume { get; set; }
    //视频宽度
    int videoWidth { get; }
    //视频高度
    int videoHeight { get; }
}

第三方播放器实现IMediaPlayer接口后，也可以用于图片识别后在识别图平面上播放AR视频。

同时，VoidVideoPlayer类和UnityVideoPlayer类提供了以下播放事件：

//视频资源准备完毕
AddEventListener(VoidAREvent.READY, OnReady);
//播放结束
AddEventListener(VoidAREvent.END, OnEnd);

利用这些接口，可以实现像传统播放器一样的视频控制功能（播放，停止，播放进度条，重播等）。

VideoPlane属性面板：

Url：视频资源路径。

如果为本地资源（视频文件必须放在StreamingAssets下），填写视频文件名，比如（xxx.mp4）；

如果为网络资源，填写完整的URL地址，比如(http://www.xxx.com/videos/xx.mp4)

Loop：是否循环播放。

Auto Scale：是否自动缩放。

勾选后，视频会自适应marker图片大小；

不勾选，可自由调整尺寸

Scale Mode：缩放方式选择。

目前支持FILL、FIT、FIT_WIDTH、FIT_HEIGHT，根据需要选择即可。

Scale Mode	说明
FILL（默认值）	填充，视频会被调整到与Marker同样的大小，如果视频与Marker的高宽比不一致，视频会被拉伸变形。
FIT	适配，按比例调整视频，视频会被调整到最大可适配到Marker里面的大小，视频高宽比保持不变。
FIT_WIDTH	适配宽度，按比例调整视频大小，宽度会被设成和Marker的宽度相同。
FIT_HEIGHT	适配高度，按比例调整视频大小，高度会被设成和Marker的高度相同。
注意	视频调整后，不足之处会用黑边填充。

5、录屏

录屏接口：运行中录制AR场景为MP4格式的视频，保存到相册，需要在ARCamera上添加VideoRecordBehaviour脚本组件。 VideoRecordBehaviour脚本组件提供了开启停止录屏功能，并内置了简单GUI。 Enable GUI：是否开启内置GUI，如果禁用，需要调用录屏方法才能使用：
```
//第一次调用开启录屏，再次调用停止录屏
public void REC(){
  ...
}
```
Android录屏后的视频文件路径为扩展卡DCIM文件夹内，iOS录屏后的视频文件路径为相册。

录屏分辨率适配：

Scale Mode	说明
SCALE_FULL（默认值）	全部显示，视频输出高宽比与输入不符，视频不会被裁剪，在某个维度上会有黑边。
SCALE_FIXED	自动适配，视频输出高宽比与输入不符，视频会被裁剪到适合输出的比例。

录屏完成回调：

vrb = Camera.main.GetComponent<VideoRecordBehaviour>();
vrb.AddEventListener(VoidAREvent.COMPLETE, onComplete);
void onComplete(VoidAREvent evt) {
    Debug.Log(evt.data); //视频文件路径
}

6、Camera对焦模式

默认情况：

要获得最佳AR跟踪性能，推荐使用默认配置提供的焦点模式。

除SLAM使用infinity模式外，其他情况对焦为continuous-video。
自定义对焦模式：

如果需要自定义对焦模式，使用VoidARBehaviour脚本CameraFocusMode属性可以实现，目前只支持在初始化阶段自定义对焦（Awake方法中）；

CameraFocusMode的值为-1时，为infinity模式，值为2时为continuous-video模式。
```
protected override void Awake()
{
    CameraFocusMode = -1;
    base.Awake();
    ...
}
```

7、闪光灯开关

默认情况：

闪光灯关闭。

控制接口：

VoidAR.GetInstance().helper.SetFlashTorchMode(true); //打开
VoidAR.GetInstance().helper.SetFlashTorchMode(false); //关闭

8、Android权限申请

SDK运行时自动处理权限包括：
1. ARCamera: 相机权限 android.permission.CAMERA
2. AR录屏: SD卡写入android.permission.WRITE_EXTERNAL_STORAGE 和录制音频android.permission.RECORD_AUDIO

开发者请求其他权限例子：

string[] requestPermissionNames = { "android.permission.WRITE_EXTERNAL_STORAGE", "android.permission.RECORD_AUDIO" };
VoidAR.GetInstance().arbase.requestAndroidPermissions(requestPermissionNames, () =>{
    //请求成功
});