All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Loading...
Searching...
No Matches
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 new state from Vuforia Engine (make sure to call release if you use this function)
 
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 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.
 
VuResult vuStateGetObservationsByObserver (const VuState *state, const VuObserver *observer, VuObservationList *list)
 Get all observations from the state associated to 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:

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 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
engineEngine instance
handlerThe handler for receiving state updates
clientDataThe 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
stateThe state containing the observations.
observerThe observer to use as a filter for the observations.
listThe 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.

◆ 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.
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.
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.
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.
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