Skip to content

Building and Using the File Driver Sample in Native

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. Add the Vuforia File Driver Sample to your project to play back 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 Stones Image Target and sequence for Native.

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 that is a part of the package. Make sure that the output file corresponds to your development platform.

See Using the File Driver Sample in Unity for importing the File Driver in Unity.

Add the File Driver

After you have built the File Driver for your desired platform, the output can be added to your project. The steps below depend on which platform/IDE you are using.

Android

  1. Add the libFileDriver.so for each needed architecture from build/bin/android to your Android app project by modifying either Android.mk or CMakeLists.txt and build.gradle. Select the option that best fits your project:

    • Android.mk:

      Add the libFileDriver-prebuilt definition to your Android.mk file:

      1
2
3
4
      include $(CLEAR_VARS)
LOCAL_MODULE := libFileDriver-prebuilt
LOCAL_SRC_FILES = [path-in-your-filesystem]/FileDriver/build/bin/Android/Release/$(TARGET_ARCH_ABI)/libFileDriver.so   
include $(PREBUILT_SHARED_LIBRARY)

      When defining your local module in the same Android.mk add libFileDriver-prebuilt as a dependency to your LOCAL_SHARED_LIBRARIES:

    • CMakeLists.txt:

      Add the VUFORIA_FILEDRIVER_LIBRARY definition to your CMakeLists.txt file:

      1
2
3
      add_library(VUFORIA_FILEDRIVER_LIBRARY SHARED IMPORTED)
set_property(TARGET VUFORIA_FILEDRIVER_LIBRARY PROPERTY IMPORTED_LOCATION
[path-in-your-filesystem]/FileDriver/build/bin/Android/Release/${ANDROID_ABI}/libFileDriver.so)

      In the same CMakeLists.txt add the File Driver library to your application:

      1
2
3
4
5
6
7
8
      target_link_libraries(
VuforiaSample
${ANDROID_LIBRARY}
${LOG_LIBRARY}
${GLES3_LIBRARY}
VUFORIA_LIBRARY
VUFORIA_FILEDRIVER_LIBRARY
)

    • Gradle:

      If using either Android.mk or CMakeLists.txt you will also need to update your build.gradle to include the library in the APK. Add the following in your app/build.gradle:

      1
2
3
4
5
      android {
    sourceSets.main {
        jniLibs.srcDirs += '[path-in-your-filesystem]/FileDriver/build/bin/Android/Release/'
    }
}

      NOTE: If you are using the Android Plugin version 4.x and a CMakeLists.txt then the above change to build.gradle is not required.

  2. Skip this step if you are using Vuforia 10.21. or later as the FileDriver.jar has been removed from the File Driver sample.

    Add the FileDriver.jar from build/bin to your Android-app project. Use the following code in your app/build.gradle:

    1
2
3
    dependencies {
    implementation files("[path-in-your-filesystem]/FileDriver/build/bin/Android/Release/FileDriver.jar")
}

  3. Add the sample sequence from the data directory to your Android-app project. Add the following in your app/build.gradle:

    1
2
3
4
5
    android {
    sourceSets.main {
        assets.srcDirs += '[path-in-your-filesystem]/FileDriver/data/stones'
    }
}

  4. Modify your App code to configure Vuforia Engine to use the driver by adding the following code before calling vuEngineCreate():

    1
2
3
4
    VuDriverConfig driverConfig = vuDriverConfigDefault();
driverConfig.driverName = "libFileDriver.so";
driverConfig.userData = nullptr;
vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);

UWP

  1. Add the FileDriver.dll from build/bin/uwp into your Visual Studio UWP app project.
    1. Import the FileDriver.dll to the root of your project. Remember to use a .dll that matches your architecture (x64/ARM64) and build type (Debug/Release) configurations.
    2. Click the FileDriver.dll from the project file list and set the property Content to True.

  2. Add a sample sequence from the data directory into your Visual Studio UWP app project. For example, to use the "stones" sequence:

    1. Import the FileDriver/data/stones/FileDriverRecording.mp4 file into your project.
    2. Select the file and set the property Content to True.

  3. Modify your App code to configure Vuforia Engine to use the driver by adding the following code before calling vuEngineCreate():

    1
2
3
4
    VuDriverConfig driverConfig = vuDriverConfigDefault();
driverConfig.driverName = "FileDriver.dll";
driverConfig.userData = nullptr;
vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);

iOS

  1. In your Xcode project (Or Vuforia sample project), open the build target settings and select the Build Phases tab.

  2. In Embedded Frameworks, click the + icon, and on the subsequent pop-up window, click Add Other -> Add Files to add a new item.

  3. From the file selection menu, select your built iOS File Driver Framework found in bin/Release-iphoneos/FileDriver.framework.

  4. In the new pop-up window, leave the options at their default values, and click **Finish

  5. Copy the FileDriverRecording.mp4 from the File Driver Sample's Data/Stones folder by dragging the file into the Assets folder in the Navigator pane (Or other, if you are not using the Vuforia sample).

  6. In the pop-up window, select your project target in the Add to targets menu.

  7. Configure your app code to use the driver by adding the following code before calling vuEngineCreate():

    1
2
3
4
    VuDriverConfig driverConfig = vuDriverConfigDefault();
driverConfig.driverName = "FileDriver.framework";
driverConfig.userData = nullptr;
vuEngineConfigSetAddDriverConfig(configSet, &driverConfig);

Changing the Sequence

To select which sequence is used for playback, a pointer to a FileDriverUserData object can be passed to the driver using the driverConfig.userData argument.

1
2
3
4
struct FileDriverUserData
{
    const char* sequenceAbsolutePath {};
}
  • If driverConfig.userData or driverConfig.userData->sequenceAbsolutePath is NULL, the File Driver will look for a file named FileDriverRecording.mp4 in the main asset location (depending on platform).
  • If driverConfig.userData->sequenceAbsolutePath is set to a string starting with asset://, FileDriver will interpret the remaining part of the string as a path in the main application asset location (depending on platform).
  • Any other string will be interpreted by File Driver as a normal filesystem path.

Playback Control API

The File Driver API exposes playback controls that can be used to configure the playback behavior of a recording.

Supported controls:

  • Playback start time
  • Playback end time
  • Looping playback
  • Changing playback mode

Set the FileDriverPlaybackMode() to FILEDRIVER_PLAYBACK_MODE_RESPECT for playing the sequence in real-time with possible frames being dropped or to FILEDRIVER_PLAYBACK_MODE_WAIT for playing the sequence with all frames but possibly slowed to let the Engine keep up. Please refer to the header API documentation for more details. It is available in the include/FileDriverPlaybackController.h file that is part of the File Driver sample package.

Using the playback control API

  1. After successfully creating the engine with File Driver, a native platform handle to the loaded library can be retrieved using vuPlatformControllerGetDriverLibraryHandle().
  2. This handle is used to load the File Driver playback controller functions using the native symbol loading mechanism of the current platform (GetProcAddress() on Windows/UWP, dlsym() on POSIX systems(known as Portable Operating System Interface).
  3. The retrieved function pointers are used to configure playback at any provided timestamp until the engine is destroyed and thus the library unloaded.

NOTE: Some playback control functions require that the engine is stopped and restarted before the change takes effect.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
VuController* platformController = nullptr;
vuEngineGetPlatformController(engine, &platformController);

void* handle = nullptr;
vuPlatformControllerGetDriverLibraryHandle(platformController, &handle);

#ifdef _WIN32
void* funcPtr = GetProcAddress(static_cast<HMODULE>(handle), "fileDriverSetPlaybackStartTime");
#else
void* funcPtr = dlsym(handle, "fileDriverSetPlaybackStartTime");
#endif

using FileDriverSetTimeFunc = bool(*)(uint64_t timestamp);
auto fileDriverSetPlaybackStartTime = reinterpret_cast<FileDriverSetTimeFunc>(funcPtr);

fileDriverSetPlaybackStartTime(100);

Learn More

Vuforia Engine Driver Framework

Creating a Camera Driver

External Camera Calibration

Using the File Driver Sample in Unity