SDK APIs

VOID AR SDK API provide three methods:

first method: call the API directly, e.g.:

VoidAR.GetInstance().startMarkerlessTracking();

second method: override base class methods or implement interface, e.g.:

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

third methed: VoidAREvent mechanism, e.g.:

AddEventListener(VoidAREvent.FIND, OnFind);

VoidAREvent properties are as follows: name: event name. currentTarget: event target, you can get target object for event dispatch. data: event data, e.g.: when cloud resources are loading, data indicates loading process.

The main functional interfaces for VoidAR SDK are as follows：

1. Local Recognization

Recognize and Lost interface:

The script component ImageTargetBehaviour provides the event dispatch mechanism on the ImageTarget object.

void Awake() {
    //event listener
    AddEventListener(VoidAREvent.FIND, OnFind);
    AddEventListener(VoidAREvent.LOST, OnLost);
}
//do Find event 
void OnFind(VoidAREvent evt){
    Debug.Log("OnFind");
}
//do Lost event
void OnLost(VoidAREvent evt){
    Debug.Log("OnLost");
}

Dispatch FIND event when target recognition is successful, and dispatch LOST event when target is lost.

2. Cloud Recognization

Cloud recognition requires adding CloudController script components to the ARCamera, CloudController provides cloud recognition status, Cloud resources download, cloud custom data processing interfaces.

Cloud recognization success response: means the cloud server has recognize the target successfully and returns the result.

  /// <summary>
  /// cloud recognization success response
  /// </summary>
  /// <param name="url">resource URL</param>
  /// <param name="name">resource name</param>
  /// <param name="metadata">extend data</param>
  protected override void OnSuccess(string url, string name, string metadata)
  {
      //The defaul AB model Assetsbundle is using WWW to load, and cloud video recognition create the video player
      base.OnSuccess(url, name, metadata);
      Debug.Log("OnSuccess metadata:" + metadata);
  }

Custom data added to the cloud platform is acquired by this method.

Set cloud video component: you can expand the player and handling play event when cloud video playing.

  /// <summary>
    /// set cloud video component
    /// You can set the extended ImageTargetBehaviour and VideoPlayBehaviour (using the Unity5.6 native player)
    /// </summary>
    /// <param name="markerTarget">marker target object</param>
    /// <param name="videoPlayTarget">video player object</param>
    /// <param name="markerName">marker image</param>
    /// <param name="videoPath">cloud video path</param>
    /// <returns>IMarker interface object</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;
    }

Message class event:

  //Cloud recognition targets are created locally (start tracking)
  AddEventListener(VoidAREvent.COMPLETE, OnComplete);
  //AB resource download progress
  AddEventListener(VoidAREvent.PROGRESS, OnDownload);
  //Exception notification
  AddEventListener(VoidAREvent.ERROR, OnError);

3. VOID SLAM

Start and stop interfaces: you need to add the ITricking interface to the GameObject of tracking, the implementation of ITricking in SDK is MarkerlessTracking in default. ITricking API is used for getting the SLAM status, including abnormal status.
```
public interface ITricking
{
    bool GetActive();
    int GetTrackingState();
    //Track active status
    void SetActive(bool value);
    //Tracking feedback（According to stateCode to judge SLAM status，see MarkerlessTracking for details）
    void UpdateTracking(int stateCode);
}
```
SLAM exception status code:

1099：network error;

501：developer account is abnormal, account is not filled or account data is incorrect;

101：account use exceed the uselimit

SLAM using interfaces:
```
//Start tracking
VoidAR.GetInstance().startMarkerlessTracking();
//Stop tracking
VoidAR.GetInstance().resetMarkerless();
```

4. Video Play

Video play interface:

The video playback can be realized through the IMediaPlayer interface, which is implemented by the VoidVideoPlayer class on the mobile platform and by the UnityVideoPlayer class (Unity official player) on other platforms. The interfaces provided by IMediaPlayer are as below:

public interface IMediaPlayer {
    //Video source
    string source { get; set; }
    //Get the length in time of the video in seconds (Read Only)
    float duration { get; }
    //The current position  in time of the video in seconds
    float seek { get; set; }
    //Play
    bool Play();
    //Pause
    bool Pause();
    //Stop
    bool Stop();
    //Returns true if it is currently playing; otherwise returns false if it is currently stopped or paused(Read Only)
    bool isPlaying { get; }
    //Whether the VideoPlayer has successfully prepared the content to be played. (Read Only)
    bool isPrepared { get; }
    //Get play video texture
    Texture texture { get; }
    //Volume size (not open yet)
    float volume { get; set; }
    //Video width
    int videoWidth { get; }
    //Video height
    int videoHeight { get; }
}

The third-party video player can also be used to play video directly on a image target marker surface after realizing the IMediaPlayer interface.

Meanwhile, the VoidVideoPlayer class and the UnityVideoPlayer class provide playback events as below:

//Video resource is ready
AddEventListener(VoidAREvent.READY, OnReady);
//Playback ends
AddEventListener(VoidAREvent.END, OnEnd);

With these interfaces, you can implement video control functions like the traditional player (play, stop, play progress bar, replay, etc.).

VideoPlane Properties panel：

Url：Video resource directory.

Local video file should be stored in folder "StreamingAssets", and fill in the full name of the video file(xxx.mp4);

Fill in the full url address if you try to use internet video resource(http://www.xxx.com/videos/xx.mp4);

Loop：AutoRewind or not;

Auto Scale：Determines the video size depending on marker or user-defined

Checked for auto-size;

Non-checked for user-defined size

Scale Mode：Support mode FILL, FIT, FIT_WIDTH and FIT_HEIGHT depends on user’s demand;

Scale Mode	Description
FILL (Default)	The video will be stretched to the same size of the marker in this mode
FIT	Keep the width-height ratio of the video to fit the maximum size to the marker
FIT_WIDTH	Same width as the the marker
FIT_HEIGHT	Same Height as the the marker
Caution	If there is blank area after re-size the video, it will be filled with black color.

5. Record Screen

Record screen interface: In runtime, to record the AR scene into MP4 file, and save it to your photo album. Yoou need add VideoRecordBehaviour script to ARCamera. VideoRecordBehaviour script offers the switcher of recording function with easy built-in GUI. Enable GUI: Whether to open built-in GUI. If you do not open, you need to call REC to start or stop recording:
```
//Call it first time for starting recording
//Call it again for stopping recording
public void REC(){
  ...
}
```
The recorded video file from Android will be stored in memory card with directory DCIM folder, and The recorded video file from iOS will be stored in photo album.

Screen recording ratio adaptation：

Scale Mode	Description
SCALE_FULL (Default)	Full Scale Output. The video will not be clipped if output aspect ratio does not fit input, but there will be black borders in one dimension.
SCALE_FIXED	Adaptive Output. The video will be clipped to fit output aspect ratio if output aspect ratio does not fit input.

Callback when screen record is succeeded：

vrb = Camera.main.GetComponent<VideoRecordBehaviour>();
vrb.AddEventListener(VoidAREvent.COMPLETE, onComplete);
void onComplete(VoidAREvent evt) {
    Debug.Log(evt.data); //Video path
}

6. Camera Focus Modes

Default Setting:

For best AR tracking performance, it is recommended to use the focus mode provided by the default configuration.

Under default conditions the camera mode is continuous-video except for SLAM which need to use infinity mode.
Customize Setting:

Set the focus mode with the VoidARBehaviour component CameraFocusMode property. Currently customize focus mode is only available at initialization in Awake method.

The value of CameraFocusMode is -1 represents infinity mode, -2 represents continuous-video mode.
```
protected override void Awake()
{
    CameraFocusMode = -1;
    base.Awake();
    ...
}
```

7. Camera Flash Switch

Default Setting:

Camera Flash is off.

Control API:

VoidAR.GetInstance().helper.SetFlashTorchMode(true); //Switch on
VoidAR.GetInstance().helper.SetFlashTorchMode(false); //Switch off

8. Request Android Permissions

Automatically requesting permissions when running the SDK:
1. ARCamera: android.permission.CAMERA
2. AR Recording: android.permission.WRITE_EXTERNAL_STORAGE, android.permission.RECORD_AUDIO

Example of requesting other permissions：

string[] requestPermissionNames = { "android.permission.WRITE_EXTERNAL_STORAGE", "android.permission.RECORD_AUDIO" };
VoidAR.GetInstance().arbase.requestAndroidPermissions(requestPermissionNames, () =>{
    //Request is succeeded
});