C++ Java Unity
C++ Reference
State Class Reference

Detailed Description

A persistent handle to the state of the whole augmented reality system at a given point in time.

A State can include:

There are two different ways to obtain a State, depending on if you want to access data via a Pull or Push model:

  1. Via an instance of StateUpdater (Pull model)
  2. Via the UpdateCallback mechanism, Vuforia::registerCallback() (Push model)

Both push and pull models can be used simultaneously, if you like. For example, you would typically want to use the Pull interface as part of your render loop, but you may want to simultaneously use the Push interface for other parts of the system, such as if you need access to state information as early as possible in order to do any other custom computer vision in addition to Vuforia.

Note, however, that in an application where the camera, renderer, and main loop are all running on separate threads, care must be taken to ensure that a consistent State object is used across the whole application.

The data associated with a given State instance remains valid as long as the State instance is retained, acting like a smart pointer to the underlying data. Vuforia will continue to run in the background but the retained State instance will not be updated, and will therefore become increasingly out of date over time.

Note that the timestamp of the Frame returned by getFrame() may not match the timestamp on the various returned TrackableResults. See StateUpdater for more details.

Public Member Functions

 State ()
 Default constructor. More...
 
 State (const State &other)
 Copy constructor. More...
 
 ~State ()
 Destructor. More...
 
Stateoperator= (const State &other)
 Thread safe assignment operator. More...
 
Frame getFrame () const
 Get the Frame associated with this State. More...
 
const CameraCalibrationgetCameraCalibration () const
 Get the camera calibration for this State, if available. More...
 
const IlluminationgetIllumination () const
 Get illumination information for this State (if available). More...
 
const DeviceTrackableResultgetDeviceTrackableResult () const
 Get the DeviceTrackableResult, if it exists. More...
 
int getNumTrackables () const
 
const TrackablegetTrackable (int idx) const
 Get an immutable Trackable specific to this State. (DEPRECATED) More...
 
int getNumTrackableResults () const
 Get the number of TrackableResult objects for this State. (DEPRECATED) More...
 
const TrackableResultgetTrackableResult (int idx) const
 Get a single TrackableResult object. (DEPRECATED) More...
 
List< const TrackableResultgetTrackableResults () const
 

Protected Attributes

StateData * mData
 

Constructor & Destructor Documentation

State ( )

Default constructor.

State ( const State other)

Copy constructor.

A State is a lightweight object which keeps internal smart pointers to its data.

Copying is therefore cheap, and recommended over using references.

~State ( )

Destructor.

Member Function Documentation

State& operator= ( const State other)

Thread safe assignment operator.

A State is a lightweight object which keeps internal smart pointers to its data.

Copying is therefore cheap, and recommended over using references.

Frame getFrame ( ) const

Get the Frame associated with this State.

Returns
A Frame object representing the camera frame that any camera-based Trackable instances used to generate the TrackableResults accessible via getTrackableResult().
Note
For non-camera-based TrackableResult instances, the timestamp of this Frame may not match the timestamp of the TrackableResult. See StateUpdater for more details.
const CameraCalibration* getCameraCalibration ( ) const

Get the camera calibration for this State, if available.

Returns
Camara calibration information for this State, or NULL if no camera calibration was available when this State was captured.

The returned object is only valid as long as the State object is valid. Do not keep a copy of the pointer!

const Illumination* getIllumination ( ) const

Get illumination information for this State (if available).

Returns
An Illumination instance containing illumination information for this State, or NULL if no illumination information is available.

The returned object is only valid as long as the State object is valid. Do not keep a copy of the pointer!

const DeviceTrackableResult* getDeviceTrackableResult ( ) const

Get the DeviceTrackableResult, if it exists.

This is a convenience method that provides easy access to the DeviceTrackableResult, if a DeviceTracker has been started.

Note
The DeviceTrackableResult is also available via getTrackableResult().
The returned object is only valid as long as the State object is valid. Do not keep a copy of the pointer!
Returns
the DeviceTrackableResult, or NULL if no DeviceTracker is running.
int getNumTrackables ( ) const

Get the number of Trackable objects that were involved in generating TrackableResult objects for this State. (DEPRECATED)

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackableResults() API instead to get the list of TrackableResults from the State and check the list size.
const Trackable* getTrackable ( int  idx) const

Get an immutable Trackable specific to this State. (DEPRECATED)

Parameters
idxThe index of the Trackable, in the range 0..getNumTrackables()-1
Returns
An immutable, non-comparable pointer to the requested Trackable.

Each of the Trackable instances that this function returns was involved in generating one or more of the TrackableResults available via getTrackableResult().

This Trackable allows historic access to the state of the Trackable at the time when this State was assembled (including access to any DataSet instances that may since have been destroyed). It does not reflect any changes that were made to the Trackable after this State was assembled. It is therefore incompatible with the Trackable returned when querying the Tracker instance (they are not pointer-comparable), even if they refer to the same potentially trackable object.

Note that a Trackable provides only high-level information for reference about a potentially trackable object, whether or not is currently being tracked. To query details such as its position or orientation in the world, use getTrackableResult() instead.

To make changes to the Trackable, query the appropriate Tracker for the canonical Trackable instance, and make your changes there instead. Note however that any changes made there will not be reflected on the Trackable returned here.

The returned object is only valid as long as the State object is valid. Do not keep a copy of the pointer!

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackableResults() API instead to get the list of TrackableResults from the State, then call getTrackable() on the TrackableResult list element with the given index.
int getNumTrackableResults ( ) const

Get the number of TrackableResult objects for this State. (DEPRECATED)

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackableResults() API instead to get the list of TrackableResults from the State and check the list size.
const TrackableResult* getTrackableResult ( int  idx) const

Get a single TrackableResult object. (DEPRECATED)

Parameters
idxThe index of the TrackableResult, in the range 0..getNumTrackableResults()-1
Returns
A pointer to the requested TrackableResult, specific to this State instance.

A TrackableResult returned from this function represents information about a Trackable object that is being actively tracked in this State.

The TrackableResult should be considered specific to this State, i.e., it represents a snapshot of the tracked object at the point in time associated with this State.

The returned object is only valid as long as the State object is valid. Do not keep a copy of the pointer!

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackableResults() API instead.
List<const TrackableResult> getTrackableResults ( ) const

Provides access to the list of TrackableResults in the State referring to Trackable objects currently being tracked. The returned list is only valid as long as the State object is valid. Do not keep a copy of the list or the TrackableResults list elements point to!

Member Data Documentation

StateData* mData
protected