C API Unity API
C API Reference (Version 10.22.5)
Observer and Observation Management

Classes

struct  VuPoseInfo
 Pose-related information for an observation instance. More...
 

Typedefs

typedef struct VuObserver_ VuObserver
 Vuforia Observer handle.
 
typedef int32_t VuObserverType
 Observer type.
 
typedef struct VuObserverList_ VuObserverList
 Vuforia ObserverList handle.
 
typedef struct VuObservation_ VuObservation
 Vuforia Observation handle.
 
typedef int32_t VuObservationType
 Observation type.
 
typedef struct VuObservationList_ VuObservationList
 Vuforia ObservationList handle.
 

Enumerations

enum  VuTrackingOptimization : int32_t {
  VU_TRACKING_OPTIMIZATION_DEFAULT = 0x1,
  VU_TRACKING_OPTIMIZATION_LOW_FEATURE_OBJECTS = 0x2,
  VU_TRACKING_OPTIMIZATION_AR_CONTROLLER = 0x3
}
 Tracking optimization types. More...
 
enum  VuObservationPoseStatus : int32_t {
  VU_OBSERVATION_POSE_STATUS_NO_POSE = 0x1,
  VU_OBSERVATION_POSE_STATUS_LIMITED = 0x2,
  VU_OBSERVATION_POSE_STATUS_TRACKED = 0x3,
  VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED = 0x4
}
 The pose status of an observation. More...
 

Functions

int32_t vuObserverGetId (const VuObserver *observer)
 Get a unique ID associated with an observer. More...
 
VuResult vuObserverGetType (const VuObserver *observer, VuObserverType *observerType)
 Get the type of an observer.
 
VuBool vuObserverIsType (const VuObserver *observer, VuObserverType observerType)
 Check the type of an observer.
 
VuResult vuObserverListCreate (VuObserverList **list)
 Create an observer list.
 
VuResult vuObserverListGetSize (const VuObserverList *list, int32_t *listSize)
 Get number of elements in an observer list.
 
VuResult vuObserverListGetElement (const VuObserverList *list, int32_t element, VuObserver **observer)
 Get an element in an observer list.
 
VuResult vuObserverListDestroy (VuObserverList *list)
 Destroy an observer list.
 
VuResult vuEngineGetObserver (const VuEngine *engine, int32_t observerId, VuObserver **observer)
 Get an observer from Vuforia Engine using its unique ID.
 
VuResult vuEngineGetObservers (const VuEngine *engine, VuObserverList *observerList)
 Get all observers from Vuforia Engine.
 
VuResult vuObserverDestroy (VuObserver *observer)
 Destroy an observer.
 
VuResult vuObserversDestroy (VuObserverList *observerList)
 Destroy multiple observers.
 
VuResult vuEngineDestroyObservers (VuEngine *engine)
 Destroy all observers in Vuforia Engine.
 
VuResult vuObserverActivate (VuObserver *observer)
 Activate an observer.
 
VuResult vuObserverDeactivate (VuObserver *observer)
 Deactivate an observer.
 
VuBool vuObserverIsActivated (const VuObserver *observer)
 Check whether an observer is activated. More...
 
VuResult vuObservationGetType (const VuObservation *observation, VuObservationType *observationType)
 Get the type of an observation.
 
VuBool vuObservationIsType (const VuObservation *observation, VuObservationType observationType)
 Check the type of an observation.
 
int32_t vuObservationGetObserverId (const VuObservation *observation)
 Get ID of the observer which has created given observation.
 
VuBool vuObservationHasPoseInfo (const VuObservation *observation)
 Check whether an observation contains pose information. More...
 
VuResult vuObservationGetPoseInfo (const VuObservation *observation, VuPoseInfo *poseInfo)
 Get pose information associated to an observation. More...
 
VuResult vuObservationListCreate (VuObservationList **list)
 Create an observation list.
 
VuResult vuObservationListGetSize (const VuObservationList *list, int32_t *listSize)
 Get number of elements in an observation list.
 
VuResult vuObservationListGetElement (const VuObservationList *list, int32_t element, VuObservation **observation)
 Get an element in an observation list.
 
VuResult vuObservationListDestroy (VuObservationList *list)
 Destroy an observation list.
 

Detailed Description

Observers are created by observer-specific creation functions consuming an observer-specific configuration data stucture Vu<ObserverType>Config, typically with the following signature:

VuResult vuEngineCreate<ObserverType>Observer(VuEngine* engine, VuObserver** observer, const Vu<ObserverType>Config* config, Vu<ObserverType>CreationError* errorCode);

The configuration data structure can be initialized with default parameters with a dedicated function vu<ObserverType>ConfigDefault(), and can be customized with desired settings. When creation fails, the creation function outputs an observer-specific error code of type Vu<ObserverType>CreationError.

The observer-specific configurations have a field of type VuBool called activate, which determines whether observer-internal resources should be activated automatically upon creation, or they require explicit activation by calling vuObserverActivate(). All observers are automatically deactivated when stopping the Vuforia Engine via vuEngineStop(), or they can be deactivated individually by calling vuObserverDeactivate().

If an observer is configured to be automatically activated on creation and the activation fails, then the errorCode parameter supplied to the observer creation function (e.g. vuEngineCreate<ObserverType>Observer()) is set to VU_<OBSERVER_TYPE>_CREATION_ERROR_AUTOACTIVATION_FAILED for all observer types where applicable.

Individual observers can be destroyed with the general vuObserverDestroy() function. A list of observers can be destroyed by calling vuObserversDestroy() with a VuObserverList. Neither of the destruction functions are observer-specific, unlike the observer creation functions.

Note that for modification of observers (vu<ObserverType>ObserverSet<Property>()) or for creation of observers with non-default optional arguments (for example "scale") it is recommended that all observers from the same database are deactivated as these operations can be expensive otherwise - especially when the database contains a large amount of targets.

Enumeration Type Documentation

◆ VuTrackingOptimization

enum VuTrackingOptimization : int32_t

Tracking optimization types.

Enumerator
VU_TRACKING_OPTIMIZATION_DEFAULT 

Best tracking performance for the majority of use cases and targets.

VU_TRACKING_OPTIMIZATION_LOW_FEATURE_OBJECTS 

Optimize tracking for objects with smooth, untextured surfaces, that lack features and detailed structures, including cars, sheet metal parts and many industrial objects.

Note
Do not use for objects that move while being tracked.
VU_TRACKING_OPTIMIZATION_AR_CONTROLLER 

Optimize tracking for use cases where small, handheld fast moving targets are used like an AR/VR controller. Tracking will be less stable if the object is stationary.

◆ VuObservationPoseStatus

enum VuObservationPoseStatus : int32_t

The pose status of an observation.

The pose status provides information about the availability and reliability of the pose reported as part of an observation. It is available for observers that report pose information, i.e. observers for which vuObservationHasPoseInfo will return VU_TRUE on the reported observations. A specific type of observer might report only a subset of these values via a VuPoseInfo. See the documentation of the respective observer type for the possible pose status values reported.

Note
The pose status has an associated status info that provides further information on a given pose status. This information is specific to the respective observer type and has to be requested through the interface of this observer type. For example, for an observer of type "ExampleObserver" that provides pose information there will be a status info of type "VuExampleObservationStatusInfo" and a function "vuExampleObservationGetStatusInfo" to query this information. See the documentation of the respective observer type for the possible values of pose status and status info.
See also
VuPoseInfo
vuObservationHasPoseInfo
vuObservationGetPoseInfo
vuStateGetObservationsWithPoseInfo
Enumerator
VU_OBSERVATION_POSE_STATUS_NO_POSE 

No valid pose available. For details refer to the status info. The NOT_OBSERVED status info is returned if an observed object is currently not being tracked. Some observers may provide additional information for VU_OBSERVATION_POSE_STATUS_NO_POSE in their status info.

VU_OBSERVATION_POSE_STATUS_LIMITED 

Observed object is being tracked in a limited form, and so the pose may be unreliable or degraded. For details refer to the status info.

VU_OBSERVATION_POSE_STATUS_TRACKED 

Observed object is being tracked directly with a valid pose.

VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED 

Observed object is being tracked indirectly using extended tracking.

Function Documentation

◆ vuObserverGetId()

int32_t vuObserverGetId ( const VuObserver observer)

Get a unique ID associated with an observer.

The ID is a positive number and is unique within a Vuforia session. It is generated at runtime and is not persistent across Vuforia sessions

◆ vuObserverIsActivated()

VuBool vuObserverIsActivated ( const VuObserver observer)

Check whether an observer is activated.

Returns
VU_TRUE if the observer is activated, VU_FALSE if the observer is not activated

◆ vuObservationHasPoseInfo()

VuBool vuObservationHasPoseInfo ( const VuObservation observation)

Check whether an observation contains pose information.

Not all types of observers report pose information for their observations. If the observation contains pose information then this call returns VU_TRUE and the pose information can be retrieved via vuObservationGetPoseInfo. Otherwise the observation does not contain pose information and a call to vuObservationGetPoseInfo would return VU_FALSE.

See also
vuStateGetObservationsWithPoseInfo to retrieve all observations from the State that contain pose information.

◆ vuObservationGetPoseInfo()

VuResult vuObservationGetPoseInfo ( const VuObservation observation,
VuPoseInfo poseInfo 
)

Get pose information associated to an observation.

This call fails if the observation does not contain pose information. Please use vuObservationHasPoseInfo to check whether a VuObservation provides pose information.

See also
vuStateGetObservationsWithPoseInfo to retrieve all observations from the State that contain pose information.