C API Unity API
C API Reference (Version 10.22.5)
Engine

Classes

struct  VuLibraryVersionInfo
 Vuforia Engine library version information. More...
 

Typedefs

typedef struct VuEngine_ VuEngine
 Vuforia Engine handle.
 

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
}
 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 vuEngineGetLibraryVersionInfo ()
 Get the Vuforia Engine library 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.

The parameter errorCode reports a synchronous error happening during the Engine instance creation process. In order to handle errors that occur asynchronously after the Engine instance has already been created and have a fundamental impact on the Engine lifecycle (e.g. Engine stopped internally due to an invalid license key or run-time camera operation issues), add a VuErrorHandlerConfig configuration to the VuEngineConfigSet used for Engine creation.

The error code for synchronously reported errors has the generic type VuErrorCode (as opposed to the more specific VuEngineCreationError type) because Engine creation may fail for multiple reasons incl. configuration errors. Engine creation error codes fall into 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 codes related to Engine creation are converted to the generic VuErrorCode type when the error is reported.

The error codes for asynchronously reported errors use the type VuEngineError, see details on error conditions and the error handler configuration mechanism in the documentation of the VuErrorHandlerConfig data structure.

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 or VuEngineError to determine the reason for the failure.

Note
Engine creation is a potentially long running operation and should not be called on the main/UI thread.
Note
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.
Permissions

Your App must fulfill platform-specific permission / configuration requirements in order to successfully create an Engine instance. Your App is responsible for executing the following platform-specific actions prior to invoking vuEngineCreate(), otherwise the Engine creation call may fail or Engine may not work properly:

  • Android:
    • Camera permission: Add the "android.permission.CAMERA" permission to the AndroidManifest.xml and also request it at run-time in your App's code, otherwise Engine fails to initialize with the error VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR.
    • Network-related permissions: Add the "android.permission.INTERNET" and "android.permission.ACCESS_NETWORK_STATE" permissions to the AndroidManifest.xml to allow Engine to leverage various cloud services and to ensure an optimal AR experience on all devices by downloading device-specific Engine settings, otherwise Engine fails to initialize with the error VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR.
    • High sensor sampling rate: When targeting Android 12 or above, add the "android.permission.HIGH_SAMPLING_RATE_SENSORS" permission to the AndroidManifest.xml to allow Engine to receive IMU sensor readings at a high rate, otherwise device tracking may not work correctly.
  • iOS:
    • Camera usage description: Add the key "NSCameraUsageDescription" to the Info.plist with an explanation why your App requires camera access, otherwise the App will be rejected by the App Store submission process
    • Camera access: Request access to the camera by calling the "AVCaptureDevice requestAccessForMediaType" API with the media type "AVMediaTypeVideo", otherwise Engine fails to initialize with VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR
  • UWP:
    • Video capturing and network device capability: Add the following snippet to the <Capabilities> tag in your App's Package.appxmanifest to enable camera capturing and full network capabilities, otherwise Engine will not work properly:
<Capabilities>
<Capability Name="internetClient" />
<DeviceCapability Name="webcam" />
</Capabilities>
  • Lumin:
    • Add the following permissions to your App's manifest.xml, otherwise Engine fails to initialize with the error VU_ENGINE_CREATION_ERROR_PERMISSION_ERROR:
      • Camera permissions: Add "CameraCapture" and "ComputerVision" permissions to the manifest.xml
      • Network-related permissions: Add the "Internet" permission to the manifest.xml to allow Engine to leverage various cloud services and ensure an optimal AR experience on all devices by downloading device-specific Engine settings
      • Perception system permissions: Add "LowLatencyLightwear", "PcfRead" and "WorldReconstruction" permissions to the manifest.xml

◆ vuEngineDestroy()

VuResult vuEngineDestroy ( VuEngine engine)

Destroy a Vuforia Engine instance.

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.

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

◆ vuEngineStart()

VuResult vuEngineStart ( VuEngine engine)

Start a Vuforia Engine instance.

This may implicitly start any internal resources of observers and controllers that have been activated or started prior to starting the Engine instance.

Note
Starting 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 observer and controller resources being started implicitly. Please also see the documentation of the respective Engine features.
Note
This function will fail if the Engine instance is already running

◆ vuEngineStop()

VuResult vuEngineStop ( VuEngine engine)

Stop a Vuforia Engine instance.

This will also deactivate all observers and stop any running controllers

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

◆ vuEngineGetLibraryVersionInfo()

VuLibraryVersionInfo vuEngineGetLibraryVersionInfo ( )

Get the Vuforia Engine library version information.

Returns
A data structure with the Vuforia Engine library version information