C API Unity API
C API Reference
Engine

Classes

struct  VuLibraryVersionInfo
 Vuforia library version information. More...
 

Typedefs

typedef struct VuEngine_ VuEngine
 Vuforia Engine handle.
 
typedef struct VuLibraryVersionInfo VuLibraryVersionInfo
 Vuforia library version information.
 

Enumerations

enum  VuEngineCreationError : int32_t {
  VU_ENGINE_CREATION_ERROR_NONE = 0x0,
  VU_ENGINE_CREATION_ERROR_DEVICE_NOT_SUPPORTED = 0x1,
  VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR = 0x2,
  VU_ENGINE_CREATION_ERROR_LICENSE_ERROR = 0x3,
  VU_ENGINE_CREATION_ERROR_INITIALIZATION = 0x4
}
 Vuforia Engine instance creation error codes. More...
 

Functions

VuResult vuEngineCreate (VuEngine **engine, const VuEngineConfigSet *configSet, VuErrorCode *errorCode)
 Create a Vuforia Engine instance. More...
 
VuResult vuEngineDestroy (VuEngine *engine)
 Destroy a Vuforia Engine instance. More...
 
VuResult vuEngineStart (VuEngine *engine)
 Start a Vuforia Engine instance. More...
 
VuResult vuEngineStop (VuEngine *engine)
 Stop a Vuforia Engine instance. More...
 
VuBool vuEngineIsRunning (const VuEngine *engine)
 Return VU_TRUE if the given Vuforia Engine instance has been started.
 
VuLibraryVersionInfo vuEngineGetLibraryVersion ()
 Get Vuforia Engine version information. More...
 

Detailed Description

Engine is the main entry point for interacting with the Vuforia SDK. It is an instance of the Vuforia Engine.

A Vuforia Engine instance can be created, destroyed and should be coupled with the lifecycle of your application.

A Vuforia Engine instance maintains a list of Observers that are used to observe the real world and report Observations (see Observers section).

A Vuforia Engine instance can be configured with a set of EngineConfig data structures to define the general behavior of the Engine (see EngineConfig section).

Enumeration Type Documentation

◆ VuEngineCreationError

enum VuEngineCreationError : int32_t

Vuforia Engine instance creation error codes.

Note
Additional errors are related to engine configuration, see the respective error code for each engine configuration type
Enumerator
VU_ENGINE_CREATION_ERROR_NONE 

No error.

VU_ENGINE_CREATION_ERROR_DEVICE_NOT_SUPPORTED 

The device is not supported.

VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR 

One or more permissions required by Vuforia Engine are missing or not granted by user (e.g. the user may have denied camera access to the app)

VU_ENGINE_CREATION_ERROR_LICENSE_ERROR 

A valid license configuration is required.

VU_ENGINE_CREATION_ERROR_INITIALIZATION 

An error occurred during initialization of the Vuforia Engine instance (e.g. an instance already exists)

Function Documentation

◆ vuEngineCreate()

VuResult vuEngineCreate ( VuEngine **  engine,
const VuEngineConfigSet configSet,
VuErrorCode errorCode 
)

Create a Vuforia Engine instance.

Parameters
engineWill be set to the created Engine instance on success, otherwise stays unmodified
configSetSet of configurations for creating the Engine instance
errorCodeOptional output error code (can be NULL). The error code will only be set if the call fails, otherwise stays unmodified
Returns
VU_SUCCESS if the Engine instance was created successfully, otherwise VU_FAILED to indicate an error. The value of errorCode provides the specific reason for the error.
Note
The parameter errorCode has the generic type VuErrorCode and not the more specific VuEngineCreationError type because Engine creation may also fail because of configuration errors. Engine creation error codes have 2 main categories:
  • VuEngineCreationError: General Engine creation error type not related to configuration errors
  • Vu*ConfigError: Engine creation errors related to a specific configuration, e.g. VuLicenseConfigError for license configuration-specific errors of the VuLicenseConfig All error types are converted to the generic VuErrorCode when an error is reported. Each error code has a unique value across the various error types. You can compare the returned error code with the values of the general VuEngineCreationError type as well as the respective error types for the configurations used when creating the Engine instance, e.g. VuLicenseConfigError, to determine the reason for the failure.
Engine creation is a potentially long running operation and should not be called on the main/UI thread. Not calling it from the main/UI thread is critical on platforms that require user permissions for accessing hardware such as the camera (e.g. on iOS or Android), as the approval process typically requires the main/UI thread not being blocked.
Only one Engine instance can exist at any given time. The call will fail if another engine instance already exists. You need to destroy the first instance before creating a new Engine instance.

◆ vuEngineDestroy()

VuResult vuEngineDestroy ( VuEngine engine)

Destroy a Vuforia Engine instance.

Note
This will release all resources used by the Engine instance and implicitly stop the Engine instance if it is still running. It is recommended to explicitly shutdown/free any resources prior to destroying the Engine instance.
Destroying the engine instance is a potentially long running operation and should not be called on the main/UI thread. The time also depends on the features being used when destroying the Engine instance. Please also see the documentation of the respective Engine features in use.
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.

◆ vuEngineStart()

VuResult vuEngineStart ( VuEngine engine)

Start a Vuforia Engine instance.

Note
This may implicitly start any internal resources of observers and controllers that have been activated or started prior to starting the Engine instance.
Starting the engine instance is a potentially long running operation and should ideally not be called on the main/UI thread. The time also depends on the observer and controller resources being started implicitly. Please also see the documentation of the respective Engine features.
This function will fail if the Engine instance is already running

◆ vuEngineStop()

VuResult vuEngineStop ( VuEngine engine)

Stop a Vuforia Engine instance.

Note
This will also deactivate all observers and stop any running controllers
Stopping the engine instance is a potentially long running operation and should ideally not be called on the main/UI thread. The time also depends on the features being used when stopping the Engine instance. Please also see the documentation of the respective Engine features in use.
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.

◆ vuEngineGetLibraryVersion()

VuLibraryVersionInfo vuEngineGetLibraryVersion ( )

Get Vuforia Engine version information.

Returns
A data structure with the Vuforia Engine version