Creating a Custom Driver

Developers of external systems looking to take advantage of Vuforia Engine can write their own Driver to provide data from external systems for Vuforia to work with. A Driver is a native C/C++ dynamic library (.so or .dll file) that implements specific calls. During runtime, Vuforia Engine loads the library and uses the it as a source of data (such as image frames).

To get started, developers should download the Native SDK package appropriate for their platform from the Developer Portal. The main file we are interested in is Driver.h file. Driver.h defines several functions along with Classes which must be extended by the custom Driver. More information can be found in the comments of Driver.h.

Functions

  • vuforiaDriver_getAPIVersion() – Returns a number containing the Driver Framework version that the library has been built against and conforms to. This constant is defined in Driver.h as VUFORIA_DRIVER_API_VERSION
  • vuforiaDriver_getLibraryVersion() – Return a string containing the version describing the library version. It is up to the Driver developer to choose a version value, but it must be non-empty and generally under 50 characters long. eg. “AndroidUVC-1.0.0”
  • vuforiaDriver_init() – Constructs and returns an instance of the VuforiaDriver object which defines the custom driver. The memory and the lifetime of this object is owned  by the library. Object is expected to remain valid until vuforiaDriver_deinit() is called
  • vuforiaDriver_deinit() – Destructs the specified instance of the VuforiaDriver object

VuforiaDriver Class

  • createExternalCamera() – Constructs a new ExternalCamera object. The memory and lifetime of this object is owned by the library. Object should remain valid until destroyExternalCamera() is called.
  • destroyExternalCamera() – Destructs the specified instance of the ExternalCamera object

ExternalCamera Class

  • open() – Allows the Driver to allocate any resources needed. After calling open() the supported camera modes must be available
  • getNumSupportedCameraModes() – Returns the number of supported camera modes.
  • getSupportedCameraMode(index) – Returns a specific supported camera mode by index
  • start(cameraMode, CameraCallback) – Start providing camera frames to the specified callback class for the specified cameraMode
  • stop() – Stop producing new camera frames to the callback
  • close() – Close the camera and release any resources obtained from open()

The ExternalCamera class also provides access  to the following info through various functions (such as gets/sets). For more information, please refer to the comments in Driver.h

  • ExposureMode
  • ExposureValue
  • FocusMode
  • FocusValue

CameraCallback Class

The Driver provides camera frames to Vuforia Engine through a Callback class. The Driver pushes CamereFrame structure to Vuforia Engine through the CameraCallback::onNewCameraFrame function. Each CameraFrame structure points to a buffer containing the actual frame data. Frame data also includes details such as an accurate timestamp, exposureTime and frame width and height. Along with the frame data, camera details must also be provided through the intrinsics parameter of type CameraIntrinsics. For more details for the CameraIntrinsics structure please refer to External Camera Calibration. It is important that the information provided by the CameraFrame structure is accurate for the best performance.

Driver Lifetime

The Vuforia Engine manages the lifetime of the Driver by making the function calls in the following order.

  1. vuforiaDriver_init() – Is called to create a new instance of the VuforiaDriver class
  2. VuforiaDriver::createExternalCamera() – Is called to create a new instance of the ExternalCamera class
  3. ExternalCamera::open() – Is called to allocate any resources required by the external system
  4. ExternalCamera::start() – Is called to signal the external system to start providing CameraFrame structures through the CameraCallback
  5. Vuforia Engine will now consume CameraFrame structures provided through the CameraCallback.
  6. ExternalCamera::stop() – Is called to signal the external system to stop providing camera frames
  7. ExternalCamera:close() – Is called to deallocate any resources that the external system was using
  8. VuforiaDriver:: destroyExternalCamera() – Is called to destruct the ExternalCamera instance
  9. vuforiaDriver_deinit() – Is called to destruct the VuforiaDriver instance

Using a Driver in Vuforia Engine

Once the Driver has been compiled, it may be shared with other developers that wish to make use of the external system. To use a Driver within Vuforia Engine, the application developer must call

Vuforia.setDriverLibrary("libCustomDriver.so");

from Android or

Vuforia::setDriverLibrary("CustomDriver.dll", nullptr);

in UWP.

The setDriverLibrary call must be made before calling Vuforia::init();

To disable an active driver and to go back to using default Vuforia Engine data capture mechanisms, pass an zero-length string to setDriverLibrary as follows:

Vuforia.setDriverLibrary("");

from Android or

Vuforia::setDriverLibrary("", nullptr);

in UWP.

Learn More