Skip to content

Building and Using the File Driver Sample in Unity

The File Driver Sample demonstrates how to implement a driver which uses an external camera and external device tracking to feed Vuforia Engine camera frames and device poses, respectively. Import the Vuforia File Driver into Unity to play back video sequences on your device.

Prerequisites

The File Driver sample can be downloaded from the Developer Portal. The File Driver is configured to load an MP4 file that was recorded using the SessionRecorder API. The device tracking poses, which are embedded in the recording, are fed into Vuforia Engine along with camera frames from the video track.

The File Driver Sample includes two sets of example recordings: Use the Astronaut Image Target and sequence for Unity.

Or, use the Session Recorder API to create your own sequences as MP4 files, See the Session Recorder API and Recording and Playback for details.

Build the Driver

See the steps for building the File Driver sample in the README.md file that is a part of the package. Make sure to build the library targeting your build platform in Unity.

See Using the File Driver Sample in Native for implementation steps using native IDEs such as Android Studio, Xcode, or Visual Studio.

Add the File Driver

After you have built the File Driver for your desired platform, the output library can be imported into Unity.

NOTE: This sample should be used together with a Session Recording MP4 file available in the device storage.

NOTE: Play mode in Unity does not load Vuforia Engine that is initialized from drivers. Instead, play back a Session Recording in the Unity Editor, see Recording and Playback.

  1. Copy the compiled binaries from build/bin/[platform] to:

    • Android: Assets/Plugins/Android/
    • UWP: Assets/Plugins/WindowsStoreApps/[x64, ARM64]

    • iOS: Assets/Plugins/iOS/

  2. Add the Session Recording to your Unity project. Copy your MP4 recording into the Assets/StreamingAssets folder. This ensures it's included in the application build and stored in device storage.

  3. In the VuforiaConfiguration window, enable Delayed initialization to allow for additional configuration and explicit initialization with the File Driver from your code. See Vuforia Engine Lifecycle for details.

  4. Also, make sure to add a license key as the file driver will not work without it.

  5. The driver library can then be set from any app level script, e.g., in a Start() method. After that, Vuforia Engine can be initialized:

    1
    VuforiaApplication.Instance.Initialize(driverName, userData);
    NOTE: The userData can be replaced with IntPtr.Zero if no user-defined data is needed.

NOTE: Make sure the File Driver framework is included as an embedded framework in your Xcode project when building to iOS platform. Refer to the step relating to linked libraries in the Building and Using the File Driver in Native in the iOS section.

Example script for initiating Vuforia from the file driver sequence. The image sequence should play in a loop instead of using the device camera.

LoadDriver.cs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
using System;
using System.IO;
using System.Runtime.InteropServices;
using UnityEngine;
using UnityEngine.Networking;
using Vuforia;

public class LoadDriver : MonoBehaviour
{
    struct FileDriverUserData
    {
        public string sequenceDirectoryAbsolutePath;
    }

    static FileDriverUserData sUserData;
    static IntPtr sUserDataPtr = IntPtr.Zero;

    void Start()
    {
#if UNITY_WSA || UNITY_IOS
        var recordingPath = Path.Combine(Application.streamingAssetsPath, “myRecording.mp4”);
#else
        var recordingPath = "asset://myRecording.mp4"; //file name relative to StreamingAssets
#endif        
        sUserData = new FileDriverUserData { sequenceDirectoryAbsolutePath = recordingPath };
        sUserDataPtr = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(FileDriverUserData)));
        Marshal.StructureToPtr(sUserData, sUserDataPtr, false);
        var driverName = "";
#if UNITY_ANDROID
        driverName = "libFileDriver.so";
#elif UNITY_WSA
        driverName = "FileDriver.dll";
#elif UNITY_IOS
        driverName = "FileDriver.framework";
#endif
        VuforiaApplication.Instance.Initialize(driverName, sUserDataPtr);
        VuforiaApplication.Instance.OnVuforiaDeinitialized += OnVuforiaDeinitialized;
    }

    static void OnVuforiaDeinitialized()
    {
        // Preserve the pointer to the user data for the whole Vuforia lifecycle 
       Marshal.FreeHGlobal(sUserDataPtr);
    }
}

Learn More

Vuforia Engine Driver Framework

Creating a Camera Driver

Building and Using the File Driver Sample in Native