Other Useful Tips

*For guidance on the latest version, refer to the GitHub page.

In this section, we will demonstrate some useful code snippets so that you can reference in your own project.

Switch Render Mode

In the previous stereoscopic rendering sample, we use the default HoloKit UI Canvas prefab to control the render mode switch. You can also switch the render mode with your own code.

// Class HoloKitCamera is a singleton
// Switch to the Stereo render mode
HoloKitCamera.Instance.RenderMode = HoloKitRenderMode.Stereo;

// Switch to the Mono render mode (the screen AR mode)
HoloKitCamera.Instance.RenderMode = HoloKitRenderMode.Mono;

When the render mode is switched, a static event HoloKitCamera.OnRenderModeChanged is also invoked to indicate the switching. You can register this event to get notified.

Center Eye Pose

When you develop a HoloKit app, you may want to get the pose of the user's head. You can get the pose by a single line of code.

Transform centerEyePose = HoloKitCamera.Instance.CenterEyePose;

Please notice that, under the Stereo mode, the center eye pose indicates the pose of the center point between the user's two eyes. Under the Mono mode, the center eye pose indicates the pose of the iPhone's camera.

Background Video Format

Under the screen AR mode, the camera video image is rendered as the background. We offer an option to enhance the background video format so that you can have a better background video image quality. This option is useful when you want to record some videos using the screen AR mode.

You can easily set the format in the inspector of HoloKitCamera.

Set BackgroundVideoFormat in the inspector of HoloKitCamera

You can also change the background video format in code at runtime.

// Set the background video format at runtime
HoloKitCamera.Instance.BackgroundVideoFormat = BackgroundVideoFormat.VideoFormat2K;
HoloKitCamera.Instance.BackgroundVideoFormat = BackgroundVideoFormat.VideoFormat4K;
HoloKitCamera.Instance.BackgroundVideoFormat = BackgroundVideoFormat.VideoFormat4KHDR;

As you can see in the above code snippet, there are three video format options. One important thing to know is that if you set the video format to VideoFormat4K or VideoFormat4KHDR, the FPS will be dropped down to 30 to fit the high quality background image! Therefore, unless you really want to enhance the background video quality, just keep this option to the default VideoFormat2K for most cases.

Camera Tracking State

In an ARSession, the camera tracking state indicates the current tracking state of the camera. In HoloKit Unity SDK, we use an enum to represents all possible camera tracking states as shown below.

public enum CameraTrackingState
{
    NotAvailable = 0,
    LimitedWithReasonNone = 1,
    LimitedWithReasonInitializing = 2,
    LimitedWithReasonExcessiveMotion = 3,
    LimitedWithReasonInsufficientFeatures = 4,
    LimitedWithReasonRelocalizing = 5,
    Normal = 6
}

We provide a static event in HoloKitCamera, which is invoked when the camera tracking state changes. You can register this event to get notified. An example of registering the event is shown below.

// Register the event at the beginning
private void Awake() 
{
    HoloKitCamera.OnCameraChangedTrackingState += OnCameraChangedTrackingState;
}

// You must unregister every static event
// Failing to do this will cause your app to crash
private void OnDestroy()
{
    HoloKitCamera.OnCameraChangedTrackingState -= OnCameraChangedTrackingState;
}

private void OnCameraChangedTrackingState(CameraTrackingState state) 
{
    Debug.Log($"Camera changed tracking state to {state}");
}

Session Should Attempt Relocalization

In HoloKitCamera script, the property SessionShouldAttemptRelocalization indicates whether the ARSession should attempt to relocalize when it is recovered from an interruption. When this value is set to false, when the ARSession resumes from a break, the session origin will be set to the current pose of the device. When this value is set to true, when the ARSession resumes, it will try to relocalize to the previous world map. This relocalization process needs you to move your device around its previously scanned environment and may never succeed.

You can monitor the relocalization status via CameraTrackingState.When the device enters relocalization stage, the CameraTrackingState will change to CameraTrackingState.LimitedWithReasonRelocalizing. It will remain in this state until the relocalization succeeds, at which moment the CameraTrackingState will change back to CameraTrackingState.Normal.

AR Scene List

When you are developing a complicated app with more than one Unity scene, you should put the HoloKitDriver prefab into your first scene and then drag all your Unity scenes which have an ARSession object in it into the HoloKitDriver.ArScenes list. HoloKitDriver will help you reset the ARKit when you quit a scene with ARSession so that when you enter a new AR scene, you will get a brand new clean ARSession. Failing to do that will mess up your ARSession when you quit and enter AR scenes repeatedly.

Drag all AR scenes into the list