Migration Guide for Native Vuforia Engine Applications

This page documents the changes between Vuforia Engine version 9.8 and version 10 as the API has fundamentally changed. Use this overview to learn about the native changes and for migrating your existing projects to the new API.

We recommend reading the Vuforia Engine 10 API page for a general introduction to the new API. For a step-by-step structure for using Vuforia Engine 10 API, please see Vuforia Engine Lifecycle.

The Vuforia Engine API has changed from a manager centric and object-oriented C++ library to an imperative struct-based C library.

This makes it easier to integrate Vuforia Engine in rendering and game engines or create bindings for platform specific programing languages, such as Swift or Kotlin.

On a high level, the new Vuforia Engine 10 API is simplifying many concepts, in particular life cycle management of Trackers, Datasets, the Camera and Targets.

Content:

High-level Comparison

Vuforia Engine v.9.8 Vuforia Engine v.10

Object-oriented C++ API.

Uses Singleton (Manager). Static methods, and inheritance.

Imperative C API.

Uses instances for everything, opaque pointers, and a struct-based configuration and composition
Static lifecycle management with Tracker, Trackable and its TrackableResult.

Lifecycle management with an Engine instance via Configuration options (Config),

Observer (with Config) and its Observations,

Camera/Render/Platform Controller (with Config)

Tracker Manager has been REMOVED.

Trackers are replaced by Observers, a list of Observers can be directly retrieved from Engine. State updates can be directly done from the Engine instance (VuEngine).

Vuforia lifecycle Static methods:

init, deinit, pause, and resume.

Vuforia lifecycle management is done with a VuEngine object that can be created, destroyed, started, and stopped.

Configure Engine with EngineConfig.

Only one instance is supported at a time.

Camera support with lifecycle control:

init, deinit, pause, and resume.

Abstracted by CameraController. Camera lifecycle is bound to the VuEngine lifecycle, no need to directly control it.
Rendering support with Renderer and RenderingPrimitives. Abstracted by the RenderController and the RenderState, latter is available from the State. Read and use your rendering primitives like immutable elements directly from the State.

Tracking Support:

Tracker lifecycle.

Tracker has been REMOVED and replaced by Observers.

Abstracted by the generic concept of Observer.

An Observer can deliver Observation(s) that contain different types of information.

An Observer can be created, destroyed, activated or deactivated.

Each Observer can be configured via an ObserverConfig and via getter/setter functions.

Observers can have dependencies between each other, which is spelled out explicitly in the respective ObserverConfig.

Activating/deactivating an Observer can be seen as starting/stopping the action of tracking an element.

Tracking Support: Trackable and TrackableResult (configuration, access, type).

A Target (or a property of the real world) is being observed by an Observer.

Observations are created in the State.

They can be configured via ObserverConfig.

Observation(s) represent a more generic concept than just tracking targets and can contain different types of information such as: Tracking pose, recognition and detection result, mapping information, etc.

Trackable is now accessible from a VuObserver.
id is now Observer id.
name is now optional, see different Observer types with targets for that.
User data has been REMOVED.

TrackableResult is replaced by VuObservation. Observations use composition where you can get different components by calling a getInfo method.

vuObservationGetPoseInfo allows you to access pose + status.
Status info and pose info is available for different observations via a typed method, e.g., for AreaTarget, vuAreaTargetObservationGetStatusInfo.

(status info), vuAreaTargetObservationTargetInfo, (pose info).

TrackableSource REMOVED.

Tracking Support:

DataSet

Abstracted under the hood and no longer a high-level concept. Dataset life cycle no longer needs to be managed explicitly
DataSet is now referenced as Database, which is a container format for targets. Database has associated utility methods for doing container operations with VuDatabaseTargetInfo.

Tracking Support:

Getting updates from State (pull) and callback (push).

State is still retrieved via push and pull mechanisms.

Parsing the State has additional built-in mechanisms: You can directly get all Observations of a specific type or get all the Observations for an Observer.

Similar as in previous versions, pull should be the preferred method over push (except if you need to do critical operation in camera callback)
Type Replaced by int32_ type for Observer (Tracker/Trackable) and Observation (TrackableResult) with anonymous enum with vuObserverGetType, vuObserverIsType, utility methods.

Utils:

Math

Matrix34F has been REMOVED.

Instead, new built-in utility functions let you manipulate Vector, Matrix, transformation, etc.

Poses are now represented by 4x4 matrices in OpenGL format with a transformation matrix with homogeneous coordinates and column major representation.

Utils:

User Data on trackable

REMOVED

Use app-level mechanisms to associate data to Observers.
Coordinate System, Frame of References and Poses. Coordinate System is unchanged except for the Guide View’s Coordinate System: Its pose is now consistent with the general convention of the SDK (Y-up). See Spatial Frame of Reference for more information.
Poses are now also delivered strictly as Matrix44F in OpenGL format.
Object Lifetime Objects are now opaque pointers with specific create/destroy, acquire/release methods. Any raw pointer is generally bound to an associated object which has a maintained lifecycle.

 

Camera

Vuforia Engine v.9.8 Vuforia Engine v.10
CameraCalibration VuCameraIntrinsics
FOV (field of view) accessible via utility method vuCameraIntrinsicsGetFov()
Extended to also deliver the distortion mode used.
CameraDevice CameraController
Lifecycle of the camera is now bound to the lifecycle of the Vuforia Engine.
Flash, focus, advanced camera fields are accessible via getter and setter functions.
Video modes have been SIMPLIFIED: You can now only get the list of preset modes and get/set an active one.
CameraField Camera fields are accessible via the CameraController using getter/setter functions
Frame VuCameraFrame

Image

Represents an image, typically as returned by the CameraDevice.

VuImage
VideoMode

VuCameraVideoMode

index replaced by preset enum.

 

Rendering

Vuforia Engine v.9.8 Vuforia Engine v.10
Device Abstracted now via PlatformController.
RenderingPrimitives is not directly accessible anymore, but returned in the state as RenderState.
Similarly as existing behavior, calling setRenderViewConfig() to change the video mode or changing the video background config will impact the returned RenderState
Renderer vuRenderController.
setVideoBackgroundTexture and updateVideoBackgroundTexture is now done with an unique method vuRenderControllerUpdateVideoBackgroundTexture.
information about video background texture can be retrieved via vuRenderControllerGetVideoBackgroundViewInfo.
Configuring the viewport can now been done in 2 ways: Using preset mode or specifying the viewport (legacy).
FPS (frames per second) methods have been REMOVED. You can query the video mode from the camera controller to get the current FPS and adapt your rendering loop using modern techniques (choreographer on Android, CADisplayLink on iOS, etc.).
Concept of render scope (begin/end) has been removed.
TextureData, TextureUnit and RenderData are now abstracted via VuRenderVideoBackgroundData.
RenderingPrimitives Concepts of View has been REMOVED.
Normalized viewport has been REMOVED.
adjustForViewportCentreToEyeAxis parameter has been REMOVED.
Eye-to-display-matrix have been REMOVED.
Viewport, video background projection matrix, mesh, and projection matrix are now accessible from the RenderState.
A utility method in RenderController allows you to configure the near/far plane of the projection matrix with get/set functions: vuRenderControllerSetProjectionMatrixNearFar.
Added a viewMatrix as a utility method to get the inverse of the camera pose.
Video background texture size is available from the vuRenderController.
VideoBackgroundConfig Replaced by a VuVector4I viewport that can be set from the vuRenderController via vuRenderControllerSetVideoBackgroundViewport.
Viewport is now using origin rather than screen center.
VideoBackgroundTextureInfo Replaced by VuVideoBackgroundViewInfo.
GLRenderer Replaced by calling vuRenderControllerUpdateVideoBackgroundTexture.
int mTextureIndex has been REMOVED.
Current context is implicit.
DXRenderer Replaced by calling vuRenderControllerUpdateVideoBackgroundTexture.
MetalRenderer Replaced by calling vuRenderControllerUpdateVideoBackgroundTexture.
texture index has been REMOVED.
id<MTLTexture> drawableTexture has been REMOVED.

 

Tracking Support

Vuforia Engine v.9.8 Vuforia Engine v.10
DeviceTrackable VuDevicePoseObserver
id is now observer id.
name has been REMOVED.
(Remark: DevicePose is scaleless and no size or bbox (bounding-box) info is available).
DeviceTrackableResult VuObservation from VuDevicePoseObserver.
includes: vuObservationGetPoseInfo (pose + status), vuDevicePoseObservationGetStatusInfo (status info).
DeviceTracker REMOVED.
PositionalDeviceTracker Abstracted as VuDevicePoseObserver (only one can consist at a time)
It is no longer needed to start/stop tracker (just activate/deactivate your Observer).
Reset world tracking is now an Engine level method vuEngineReset. Any Observer dependent on the Device Pose Observer may be affected by the reset.
Anchor creation (created from device pose, created from hit test) is now handled by its dedicated Observer: vuAnchorObserver.

 

DataSet

Vuforia Engine v.9.8 Vuforia Engine v.10
DataSet Replaced with utility methods to parse check database of targets: vuDatabaseTargetInfo.
Only the type of trackable + name are now accessible (not all trackable info such as unique id, scale, etc.).
 
The file-exist-check method has been REMOVED
CreateTrackable from source methods have been moved to the ImageTargetObserver and ImageTargetCloudObserver.
Destroy method and target limit check have been REMOVED.
Create MultiTarget has been REMOVED.

 

 State

Vuforia Engine v.9.8 Vuforia Engine v.10
State VuState.
Frame – VuCameraFrame.
Camera calibration - VuCameraIntrinsics.
Trackable results - VuObservation with pose info.
Device trackable results -  VuObservation are all accessible from VuState via functions like VuStateGet. Typed Observation can be easily accessible via dedicated methods, e.g., retrieving device pose observations: vuStateGetDevicePoseObservations.
StateUpdater Update state replaced by vuEngineAcquireLatestState
The concept of getLatestState has been REMOVED. Instead, you need to do your own bookkeeping to keep the state around.
The getLatestTimeStamp method has been REMOVED.
UpdateCallback vuEngineRegisterUpdateStateHandler.

 

Vuforia

Vuforia Engine v.9.8 Vuforia Engine v.10
Vuforia

init, onpause, onresume has been replaced by Vuforia Engine lifecycle (Create, destroy, start, stop).

isInitialized has been REMOVED.

setHint has been replaced by multiple methods:

  • HINT_MAX_SIMULTANEOUS_IMAGE_TARGETS => vuImageTargetObserverSetMaximumSimultaneousImageTargets.
  • HINT_MAX_SIMULTANEOUS_OBJECT_TARGETS => vuObjectTargetObserverSetMaximumSimultaneousObjectTargets.
  • HINT_DELAYED_LOADING_OBJECT_DATASETS => vuObjectTargetObserverSetDelayedLoading.
  • HINT_ASYNC_FETCH_OF_LATEST_CALIBRATION => VuDeviceCalibrationConfig. Must be set during Engine config.
  • HINT_MODEL_TARGET_RECO_WHILE_EXTENDED_TRACKED => REMOVED.
  • HINT_STATIC_DEVICE_TRACKER => VuDevicePoseConfig. Must be set during engine config.

FusionProvider is now get/set from vuPlatformController.
requiresAlpha has been REMOVED.

getBitsPerPixel replaced by vuImagePixelFormatGetBitsPerPixel.

getBufferSize replaced by vuImageGetBufferSize.

setFrameFormat replaced by registration format methods in vuCameraController.
registerCallback replaced by vuEngineRegisterUpdateStateHandler.

onSurfaceCreated has been REMOVED.

onSurfaceChanged has been replaced by setRenderViewConfig on vuRenderController library,

Build version are now accessible via vuEngineGetLibraryVersion.

Driver library is now set via a vuDriverConfig when configuring engine.

Vuforia Engine now requires to be configured with an orientation enum via vuPlatformControllerSetViewOrientation. Orientation may be dependent on the platform type. See Rendering in Native for details.

 

Other API Function Changes

  • Eyewear Calibration support.
  • Concept of multiple views or stereo rendering for eyewear/stereo display.
  • Frame per second fps removed – use native platform specific calls instead.
  • Multi Target dynamic creation.
  • Filtering mode for cloud recognition.

API functions removed or replaced

  • Area – Only subtype still exists as VuRectangle
  • Box3D – Replaced with AABB (axis-aligned bounding box)
  • EyeID – REMOVED
  • EyewearCalibrationReadings – REMOVED
  • EyewearDevice – replaced with utility methods in vuPlatformController
  • EyewearUserCalibrator – REMOVED
  • Illumination - supported by creating an VuIlluminationObserver, and accessing VuIlliminationObservation
  • List – Vuforia Engine no longer has a general List type, but typed lists can be created (e.g. for a type “Object”, methods will be vuObjectListCreate, vuObjectListDestroy, vuMyObjectListGetSize, vuObjectListGetElement)
  • Matrices – vuMatrix33F and vuMatrix44F. Matrix34F has been REMOVED
  • MeshVuMesh. Its has methods were REMOVED (look instead for num of elements methods)
  • NonCopyable – REMOVED
  • Obb2d - REMOVED
  • Obb3D – Replaced with VuAABB. Utility method to get min vuAABBMin and max vuAABBMax
  • RectangleVuRectangle
  • SessionRecorderVuSessionRecorderController Introduced notion of a recording (VuRecording). You can now record separately the camera image, device pose or sensor.
  • StandardLibraryDefinitions - REMOVED
  • System - unchanged. We are now explicitly using the type from <stdint.h> for 64 bits types.
  • Tool - Methods using Matrix34F have been REMOVED. All the other methods are now available in MathUtils.h.
  • Vectors - VuVector.., supporting [2,3,4][F,I] component type.
  • View - REMOVED
  • ViewList – REMOVED
  • Virtual Buttons
    • VirtualButton - VuVirtualButtonObserver with get/set functions. Activation is on by default. id is now observer id. name has been REMOVED.
    • VirtualButtonResult - VuObservation from VuVirtualButtonObserver. Includes: VuObjectTargetObservationTargetInfo. isPressed replaced by a VuVirtualButtonState

 

Area Targets

We recommend re-generating legacy Area Targets with the latest tools to match the Vuforia Engine version in use to avoid compatibility issues.

Vuforia Engine v.9.8 Vuforia Engine v.10
AreaTarget
(inherit from Trackable)

VuAreaTargetObserver with get/set functions. Activation is on by default.
id is now the Observer id.
Box3D is now AABB.

Relocalize with vuAreaTargetObserverSetExternalPosition. Large Area Targets will return VU_TRUE for vuAreaTargetObserverRequireExternalPosition.
AreaTargetResult
(inherit from TrackableResult)

VuObservation from VuAreaTargetObserver.
includes: VuAreaTargetObservationTargetInfo.

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuAreaTargetObservationGetStatusInfo (status info).
AreaTracker
(inherit from Tracker)
Abstracted as VuAreaTargetObserver (can have multiple of them, one for each Area Target). 
No more dataset management: It is no longer required to start/stop the ObjectTracker (just activate/deactivate the Observer).

 

Model Targets

Vuforia Engine v.9.8 Vuforia Engine v.10
GuideView VuGuideView
Note that the coordinate system (CS) is now CHANGED for the Guide View pose: Y-Up (rather than Y-down) pose of the camera in the model CS (rather than pose of the model in the camera CS).
ModelTarget VuModelTargetObserver with get/set functions. Activation is on by default.
id is now observer id.
NOTE: The active Guide View is now set via name and not via index (you can get id from the Guide View list, list index maps to the persistent).
ModelTargetResult

VuObservation from VuModelTargetObserver.
includes: VuModelTargetObservationTargetInfo.

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuModelTargetObservationGetStatusInfo (status info).

 

Image Targets

Vuforia Engine v.9.8 Vuforia Engine v.10
ImageTarget VuImageTargetObserver with get/set functions. Activation is on by default.
id is now observer id
ImageTargetResult

VuObservation from VuImageTargetObserver.
includes: VuImageTargetObservationTargetInfo.

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuAreaTargetObservationGetStatusInfo (status info).
RuntimeImageSource Runtime image source is now accessible via a VuImageTargetObserver with a VuImageTargetBufferConfig or VuImageTargetFileConfig configured
TargetFinder Abstracted with VuCloudImageTargetObserver.
Configured via VuCloudImageTargetConfig.
init, deinit, start, stop lifecycle has been replaced with create, destroy, activate, deactivate.

Recognition updates are available by pull mechanism,

Registering event handler is now
vuCloudImageTargetObserverRegisterHandlers.

Filter Mode has been REMOVED.
enableTracking can now been done by creating a VuImageTargetObserver from a cloud observation via VuImageTargetBufferConfig.
clearTrackables can be done by deactivating and destroying VuImageTargetObserver.
getObjectTargets can be done by retrieving the list of Image Target Observers fromvuEngine.
TargetSearchResult VuObservation from VuCloudImageTargetObserver.
includes: VuCloudImageTargetObservationTargetInfo.

 

Cloud Recognition

Vuforia Engine v.9.8   Vuforia Engine v.10
CloudRecoSearchResult   VuObservation from VuCloudImageTargetObserver.
includes: VuCloudImageTargetObservationTargetInfo.

 

Cylinder Targets

Vuforia Engine v.9.8 Vuforia Engine v.10
CylinderTarget VuCylinderTargetObserver with get/set functions. Activation is on by default.
id is now observer id.
CylinderTargetResult

VuObservation from VuCylinderTargetObserver.
includes: VuACylinderTargetObservationTargetInfo

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuCylinderTargetObservationGetStatusInfo (status info).

 

Multi Targets

Vuforia Engine v.9.8 Vuforia Engine v.10
MultiTarget VuMultiTargetObserver with get/set functions. Activation is on by default.
id is now observer id.
MultiTarget

VuObservation from VuMultiTargetObserver.
includes: VuMultiTargetObservationTargetInfo

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuMultiTargetObservationGetStatusInfo (status info).

 

Ground Plane

Vuforia Engine v.9.8 Vuforia Engine v.10
Anchor 
(inherit from Trackable)
VuAnchorObserver
id is now the Observer id.
name has been REMOVED.
VuAnchorObserver is scaleless; no set size or bounding box info available).

AnchorResult
(inherit from TrackableResult)

VuObservation from VuAnchorObserver.
includes: VuAnchorObservationInfo (“trackable” info), vuObservationGetPoseInfo (pose + status), vuAnchorObservationGetStatusInfo (status info).
HitTestResult VuHitTest returned as part of a VuHitTestList, called from vuAnchorObserverHitTest.
SmartTerrain REMOVED, now handle by a single method: vuAnchorObserverHitTest.

 

Object Targets

Vuforia Engine v.9.8 Vuforia Engine v.10
ObjectTarget VuObjectTargetObserver with get/set functions. Activation is on by default.
id is now observer id.
ObjectTarget is no longer a “generic” base class for Object Targets but a dedicated type of target (3D object with feature, non-CAD like Model Target).
MotionHint has been REMOVED.
ObjectTargetResult

VuObservation from VuObjectTargetObserver.
includes: VuObjectTargetObservationTargetInfo

(“trackable” info), vuObservationGetPoseInfo (pose + status), vuObjectTargetObservationGetStatusInfo (status info).
ObjectTracker Abstracted via a different type of Observers such as VuImageTargetObserver, VuModelTargetObserver, etc. (you can have multiple of them). 
It is no longer needed to start/stop tracker (just activate/deactivate your Observer).

 

VuMarks

Vuforia Engine v.9.8 Vuforia Engine v.10
InstanceId VuVuMarkObservationInstanceInfo
VuMarkTarget

Part of a VuObservation from vuVuMarkObserver (instance of an Observation).
includes:
vuVuMarkObservationGetTemplateInfo,

vuVuMarkObservationGetInstanceInfo, vuVuMarkObservationGetInstanceImage
VuMarkTargetResult VuObservation from vuVuMarkObserver.
includes: vuVuMarkObservationGetTemplateInfo (“trackable” info), vuObservationGetPoseInfo (pose + status), vuVuMarkObservationGetStatusInfo (status info),
vuVuMarkObservationGetInfo (“id”)
VuMarkTemplate vuVuMarkObserver with get/set functions. Activation is on by default.
id is now observer id
User Data has been REMOVED.

 

Platform

iOS

Vuforia changes specific to iOS platform.

  • License is now set via a vuLicenseConfig when configuring Engine.
  • Renderer flag is now set via a vuRenderConfig when configuring Engine.
  • Rotation is set via setPlatformControllerSetScreenOrientation from vuPlatformController.
  • Provider configuration is now set via vuPlatformController from vuPlatformControllerSetARKitConfig.
  • UIGLViewProtocol – REMOVED. You should instead use the native platform feature to support controlling its rendering.

Android

Vuforia changes specific to Android development.

  • Activity is now set via a vuPlatformAndroidConfig when configuring Engine.
  • License is now set via a vuLicenseConfig when configuring Engine.
  • Renderer flag is now set via a vuRenderConfig when configuring Engine.
  • A new method is added to set screen orientation on Android: Rotation is set via setPlatformControllerSetScreenOrientation from vuPlatformController.

UWP

Vuforia changes specific to UWP development

  • License is now set via a vuLicenseConfig when configuring Engine.
  • Rotation is set via setPlatformControllerSetScreenOrientation from vuPlatformController.
  • Provider configuration is now set via vuPlatformController from vuPlatformControllerSetHolographicAppsCS.

Back to top

Can this page be better?
Share your feedback via our issue tracker