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.
typedef struct VuDepthFrame_	VuDepthFrame
	Vuforia Depth Frame.

Functions
VuResult	vuEngineAcquireLatestState (const VuEngine *engine, VuState **state)
	Return the latest Vuforia State from Vuforia Engine.
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.
VuResult	vuStateGetObservations (const VuState *state, VuObservationList *list)
	Get all observations from the state.
VuResult	vuStateGetObservationsWithPoseInfo (const VuState *state, VuObservationList *list)
	Get all observations from the state that contain pose information.
VuResult	vuStateGetObservationsByObserver (const VuState *state, const VuObserver *observer, VuObservationList *list)
	Get all observations from the state that have been created by a given observer.
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.
VuResult	vuStateGetCameraFrame (const VuState *state, VuCameraFrame **cameraFrame)
	Get the camera frame from the state.
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.
VuBool	vuStateHasDefaultDepthFrame (const VuState *state)
	Return VU_TRUE if the state contains a depth frame of the type Vuforia Engine uses by default on this device.
VuResult	vuStateGetDefaultDepthFrame (const VuState *state, VuDepthFrame **depthFrame)
	Get the default depth frame (as used by Vuforia Engine) from the state.
VuResult	vuDepthFrameGetDepthMap (const VuDepthFrame *depthFrame, VuImage **depthMap)
	Get the depth map image from the depth frame.
VuResult	vuDepthFrameGetConfidenceMap (const VuDepthFrame *depthFrame, VuImage **confidenceMap)
	Get the confidence map image from the depth frame.
VuResult	vuStateGetRenderState (const VuState *state, VuRenderState *renderState)
	Get the render state from the Vuforia state.

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.

Typedef Documentation

VuDepthFrame

typedef struct VuDepthFrame_ VuDepthFrame

Vuforia Depth Frame.

Note

This type is part of a feature in beta and may change from release to release without notice.

Function Documentation

vuEngineAcquireLatestState()

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

Return the latest Vuforia State from Vuforia Engine.

The acquired state must be released by calling vuStateRelease() when no longer needed to avoid leaking memory.

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.

vuStateAcquireReference()

VuResult vuStateAcquireReference	(	const VuState *	state,
		VuState **	stateOut )

Acquire a new reference to the given state.

The acquired state reference must be released by calling vuStateRelease() when no longer needed to avoid leaking memory.

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

vuStateGetObservations()

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

Get all observations from the state.

Note

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

The content of the list is bound to the lifetime of the state.

vuStateGetObservationsWithPoseInfo()

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

Get all observations from the state that contain pose information.

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

Note

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

The content of the list is bound to the lifetime of the state.

vuStateGetObservationsByObserver()

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

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

Note

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

The content of the list is bound to the lifetime of the state.

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.

The lifetime of the camera frame is bound to the lifetime of the state.

vuCameraFrameGetImages()

VuResult vuCameraFrameGetImages	(	const VuCameraFrame *	cameraFrame,
		VuImageList *	list )

Get camera image list from a camera frame.

Note

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

The content of the list is bound to the lifetime of the camera frame.

vuStateHasDefaultDepthFrame()

VuBool vuStateHasDefaultDepthFrame

(

const VuState *

state

)

Return VU_TRUE if the state contains a depth frame of the type Vuforia Engine uses by default on this device.

Note

Depth frames are currently supported only on iOS devices with a LiDAR sensor when using ARKit. On iOS with ARKit Vuforia Engine uses "scene depth" by default. See https://developer.apple.com/documentation/arkit/arframe/3566299-scenedepth

The state does not contain a depth frame if it is acquired after calling vuEngineStart but before the first camera frame is retrieved by Vuforia. Provided that depth frames have been successfully enabled, there is always a valid depth frame when using a VuStateHandler callback.

Note

This function is part of a feature in beta and may change from release to release without notice.

vuStateGetDefaultDepthFrame()

VuResult vuStateGetDefaultDepthFrame	(	const VuState *	state,
		VuDepthFrame **	depthFrame )

Get the default depth frame (as used by Vuforia Engine) from the state.

Note

Currently this call succeeds only on iOS devices with a LiDAR sensor when using ARKit and will return a depth frame of type "scene depth" as defined in https://developer.apple.com/documentation/arkit/arframe/3566299-scenedepth

This call will fail unless depth frames have been explicitly enabled via vuCameraControllerEnableDepth.

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

Note

This function is part of a feature in beta and may change from release to release without notice.

vuDepthFrameGetDepthMap()

VuResult vuDepthFrameGetDepthMap	(	const VuDepthFrame *	depthFrame,
		VuImage **	depthMap )

Get the depth map image from the depth frame.

Note

The lifetime of the image is bound to the lifetime of the VuDepthFrame instance. It should not be explicitly released using vuImageRelease.

Note

This function is part of a feature in beta and may change from release to release without notice.

vuDepthFrameGetConfidenceMap()

VuResult vuDepthFrameGetConfidenceMap	(	const VuDepthFrame *	depthFrame,
		VuImage **	confidenceMap )

Get the confidence map image from the depth frame.

Note

The lifetime of the image is bound to the lifetime of the VuDepthFrame instance. It should not be explicitly released using vuImageRelease.

Note

This function is part of a feature in beta and may change from release to release without notice.

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