State Management

Classes
struct	VuRenderState
	Vuforia Render State. More...

Typedefs
typedef struct VuState_	VuState
	Vuforia State handle.
typedef void()	VuStateHandler(const VuState *state, void *clientData)
	Vuforia State handler function type.
typedef struct VuCameraFrame_	VuCameraFrame
	Vuforia Camera Frame.

Functions
VuResult	vuEngineAcquireLatestState (const VuEngine *engine, VuState **state)
	Return new state from Vuforia Engine (make sure to call release if you use this function) More...
VuResult	vuStateRelease (VuState *state)
	Release the given state.
VuResult	vuStateAcquireReference (const VuState *state, VuState **stateOut)
	Acquire a new reference to the given state.
VuResult	vuEngineRegisterStateHandler (VuEngine *engine, VuStateHandler *handler, void *clientData)
	Register a state handler to get Vuforia State updates. More...
VuResult	vuStateGetObservations (const VuState *state, VuObservationList *list)
	Get a list of observations from the state.
VuResult	vuStateGetObservationsWithPoseInfo (const VuState *state, VuObservationList *list)
	Get all observations from the Vuforia State that contain pose information. More...
VuResult	vuStateGetObservationsByObserver (const VuState *state, const VuObserver *observer, VuObservationList *list)
	Get all observations from the state associated to a given observer. More...
VuResult	vuStateGetCameraIntrinsics (const VuState *state, VuCameraIntrinsics *cameraIntrinsics)
	Get the camera intrinsics from the state.
VuBool	vuStateHasCameraFrame (const VuState *state)
	Return true if the state contains camera frame data. More...
VuResult	vuStateGetCameraFrame (const VuState *state, VuCameraFrame **cameraFrame)
	Get the camera frame from the state. More...
VuResult	vuCameraFrameGetIndex (const VuCameraFrame *cameraFrame, int64_t *index)
	Get index from a camera frame.
VuResult	vuCameraFrameGetTimestamp (const VuCameraFrame *cameraFrame, int64_t *timestamp)
	Get timestamp from a camera frame.
VuResult	vuCameraFrameGetImages (const VuCameraFrame *cameraFrame, VuImageList *list)
	Get camera image list from a camera frame.
VuResult	vuStateGetRenderState (const VuState *state, VuRenderState *renderState)
	Get the render state from the Vuforia state. More...

Detailed Description

The Vuforia State represents a snapshot of what Vuforia Engine "knows" about the user's environment. It contains all information Vuforia clients need to render an AR scene, including observations, camera and rendering information. Individual state information elements can be retrieved from VuState with the respective vuStateGet* getter functions, e.g. vuStateGetObservations() acquires the current list of observations generated by observers. VuState objects are immutable and their data cannot be changed after creation.

There are 2 ways to obtain the latest Vuforia State from the Vuforia Engine:

• Pull mechanism: The function vuEngineAcquireLatestState() allows the acquisition of the latest state on demand while Engine is running. State objects acquired with this mechanism must be released by calling vuStateRelease() when no longer needed to avoid leaking memory.
• Push mechanism: The vuEngineRegisterStateHandler() allows the registration of a callback function of type VuStateHandler, which informs the registered client about the latest state as it becomes available. Only one callback function can be registered at one time. Callbacks keep coming from Engine as long as it is running or the client unregisters the callback by calling vuEngineRegisterStateHandler() with a nullptr as the handler function. State objects obtained with this mechanism do not need to (and cannot) be released, and are valid only during the callback scope.

The VuState object acquired via the pull mechanism remains valid as long as the Engine instance is valid or until vuStateRelease() is called to release the internal state data. The VuState object received via the push mechanism remains valid during the scope of the callback.

If you wish to extend the lifetime beyond its original scope (e.g. to preserve state data outside the state handler callback), you need to create a state reference. You can create any number of references to a VuState instance by calling vuStateAcquireReference(). A state reference contains the same immutable information as the VuState it has been created from but its lifetime becomes independent from it. This means that even if you call vuStateRelease() on a given VuState, a reference created from it beforehand remains valid until vuStateRelease() is called on the state reference.

Function Documentation

vuEngineAcquireLatestState()

VuResult vuEngineAcquireLatestState	(	const VuEngine *	engine,
		VuState **	state
	)

Return new state from Vuforia Engine (make sure to call release if you use this function)

Note

This call will fail if Vuforia is not running.

The state does not contain any camera frame or render state data if it is acquired after calling vuEngineStart() but before the first camera frame is retrieved by Vuforia

vuEngineRegisterStateHandler()

VuResult vuEngineRegisterStateHandler	(	VuEngine *	engine,
		VuStateHandler *	handler,
		void *	clientData
	)

Register a state handler to get Vuforia State updates.

The registered handler function will report the Vuforia State including observations, camera and rendering information at the camera frame rate.

Note

This function will fail if called from a Vuforia Engine callback. Vuforia Engine does not allow certain API functions to be called reentrant from a callback, i.e. to enter the API again on the same callstack. See also section "Callbacks and reentrancy" for more information.

Only one handler can be registered at a given time. A handler can be unregistered by providing NULL to the function.

Parameters

engine	Engine instance
handler	The handler for receiving state updates
clientData	The client data to pass with the state updates

vuStateGetObservationsWithPoseInfo()

VuResult vuStateGetObservationsWithPoseInfo	(	const VuState *	state,
		VuObservationList *	list
	)

Get all observations from the Vuforia State that contain pose information.

Note

The observations returned by this call can be used with vuObservationGetPoseInfo to retrieve pose information.

vuStateGetObservationsByObserver()

VuResult vuStateGetObservationsByObserver	(	const VuState *	state,
		const VuObserver *	observer,
		VuObservationList *	list
	)

Get all observations from the state associated to a given observer.

Returns all observations from the state that have been created by a given observer.

Note

The user has to make sure that state, observer and list are valid during the time of the call, otherwise the behavior is undefined.

Any previous content of the given list will be removed if the operation was successful. On failure the list will not be modified.

Parameters

state	The state containing the observations.
observer	The observer to use as a filter for the observations.
list	The list to fill with the observations found.

Returns

VU_SUCCESS on success, VU_FAILED on failure.

vuStateHasCameraFrame()

VuBool vuStateHasCameraFrame

(

const VuState *

state

)

Return true if the state contains camera frame data.

Note

The state does not contain a camera frame if it is acquired after calling vuEngineStart() but before the first camera frame is retrieved by Vuforia. There is always a valid camera frame when using a VuStateHandler callback

vuStateGetCameraFrame()

VuResult vuStateGetCameraFrame	(	const VuState *	state,
		VuCameraFrame **	cameraFrame
	)

Get the camera frame from the state.

Note

This call will fail if vuStateHasCameraFrame() returns VU_FALSE which happens if the state is acquired after calling vuEngineStart() but before the first camera frame is retrieved by Vuforia.

vuStateGetRenderState()

VuResult vuStateGetRenderState	(	const VuState *	state,
		VuRenderState *	renderState
	)

Get the render state from the Vuforia state.

Note

All members of the render state are 0 if the state is acquired after calling vuEngineStart() but before the first camera frame is retrieved by Vuforia

Viewport and video background rendering data may be 0 on some platforms when Vuforia cannot auto-detect a default render view configuration at engine creation time and vuRenderControllerSetRenderViewConfig() was not called by the user

Warning

The behaviour of the default render view configuration will change in an upcoming release. See vuRenderControllerSetRenderViewConfig for details.

Returns

VU_SUCCESS if the render state could be retrieved, VU_FAILED otherwise