Platform Controller

Topics
	Android-specific Platform Controller
	iOS-specific Platform Controller
	UWP-specific Platform Controller

Enumerations
enum	VuViewOrientation : int32_t {   VU_VIEW_ORIENTATION_LANDSCAPE_LEFT = 0x1 ,   VU_VIEW_ORIENTATION_PORTRAIT = 0x2 ,   VU_VIEW_ORIENTATION_LANDSCAPE_RIGHT = 0x3 ,   VU_VIEW_ORIENTATION_PORTRAIT_UPSIDEDOWN = 0x4 }
	The view orientation describes how the application is oriented, or how the user "views" the camera image. More...
enum	VuFusionProviderType : int32_t {   VU_FUSION_PROVIDER_TYPE_UNKNOWN = 0x1 ,   VU_FUSION_PROVIDER_TYPE_VISION_ONLY = 0x2 ,   VU_FUSION_PROVIDER_TYPE_SENSOR_FUSION = 0x3 ,   VU_FUSION_PROVIDER_TYPE_PLATFORM_SENSOR_FUSION = 0x4 }
	Vuforia Fusion provider types. More...
enum	VuFusionProviderPlatformType : int32_t {   VU_FUSION_PROVIDER_PLATFORM_TYPE_UNKNOWN = 0x1 ,   VU_FUSION_PROVIDER_PLATFORM_TYPE_ARKIT = 0x2 ,   VU_FUSION_PROVIDER_PLATFORM_TYPE_ARCORE = 0x3 ,   VU_FUSION_PROVIDER_PLATFORM_TYPE_WINDOWS_HOLOGRAPHIC = 0x4 ,   VU_FUSION_PROVIDER_PLATFORM_TYPE_LUMIN = 0x5 ,   VU_FUSION_PROVIDER_PLATFORM_TYPE_EXTERNAL = 0x6 }
	Vuforia Fusion Provider Platform type. More...

Functions
VuResult	vuEngineGetPlatformController (const VuEngine *engine, VuController **controller)
	Retrieve Platform Controller to get access to platform-specific functionality and settings in Engine.
VuResult	vuPlatformControllerSetViewOrientation (VuController *controller, VuViewOrientation orientation)
	Set the current view orientation.
VuResult	vuPlatformControllerConvertPlatformViewOrientation (const VuController *controller, const void *platformOrientation, VuViewOrientation *vuOrientation)
	Utility function for converting a platform-specific orientation descriptor to a Vuforia view orientation value.
VuResult	vuPlatformControllerGetFusionProviderType (const VuController *controller, VuFusionProviderType *fusionProvider)
	Get the current fusion provider type.
VuResult	vuPlatformControllerGetFusionProviderPlatformType (const VuController *controller, VuFusionProviderPlatformType *fusionProviderPlatformType)
	Get the current platform fusion provider type if Vuforia Fusion is using platform-provided technology.
VuResult	vuPlatformControllerGetDriverLibraryHandle (const VuController *controller, void **handle)
	Retrieves the handle to the currently loaded Vuforia Driver library.

Detailed Description

This controller allows the control of platform-specific features on certain platforms. Check whether a platform-specific header called {PLATFORM_NAME}/Platfrom_{PLATFORM_NAME}.h exists for the given platform, and look up options there. If no platform-specific header exists, then the Vuforia Engine does not support any platform-specific functionality on the given platform.

Enumeration Type Documentation

VuViewOrientation

enum VuViewOrientation : int32_t

The view orientation describes how the application is oriented, or how the user "views" the camera image.

Enumerator
VU_VIEW_ORIENTATION_LANDSCAPE_LEFT	The app is viewed as wider than it is tall with the device rotated by 90 degrees COUNTER - CLOCKWISE from regular portrait. Note that on iOS this corresponds to "Landscape Right"
VU_VIEW_ORIENTATION_PORTRAIT	The app is viewed as taller than it is wide.
VU_VIEW_ORIENTATION_LANDSCAPE_RIGHT	The app is viewed in a landscape orientation BUT in the opposite direction from the landscape orientation as defined above. In other words, the device is rotated by 90 degrees CLOCKWISE from regular portrait. Note that on iOS this corresponds to "Landscape Left"
VU_VIEW_ORIENTATION_PORTRAIT_UPSIDEDOWN	The app is viewed in a portrait orientation BUT in the opposite direction from the regular portrait orientation

VuFusionProviderType

enum VuFusionProviderType : int32_t

Vuforia Fusion provider types.

Enumerator
VU_FUSION_PROVIDER_TYPE_UNKNOWN	Fusion provider is unknown.
VU_FUSION_PROVIDER_TYPE_VISION_ONLY	Use vision-based Fusion only Please note that not all Vuforia Engine features are supported when using this provider.
VU_FUSION_PROVIDER_TYPE_SENSOR_FUSION	Use Vuforia-provided technology for Fusion. Vuforia Engine will make use of camera and IMU information to try to create a tracking experience that, when compared to vision-only, is more robust to erratic motions and sparse or featureless environments.
VU_FUSION_PROVIDER_TYPE_PLATFORM_SENSOR_FUSION	Use platform-provided technology for Fusion. Vuforia Engine will make use of tracking services offered by the underlying platform, such as ARKit on iOS, ARCore on Android, or Windows Holographic on UWP.

VuFusionProviderPlatformType

enum VuFusionProviderPlatformType : int32_t

Vuforia Fusion Provider Platform type.

Enumerator
VU_FUSION_PROVIDER_PLATFORM_TYPE_UNKNOWN	Provider platform is unknown or unavailable.
VU_FUSION_PROVIDER_PLATFORM_TYPE_ARKIT	ARKit platform.
VU_FUSION_PROVIDER_PLATFORM_TYPE_ARCORE	ARCore platform.
VU_FUSION_PROVIDER_PLATFORM_TYPE_WINDOWS_HOLOGRAPHIC	Windows Holographic platform.
VU_FUSION_PROVIDER_PLATFORM_TYPE_LUMIN	Lumin platform.
VU_FUSION_PROVIDER_PLATFORM_TYPE_EXTERNAL	External (Vuforia Driver)

Function Documentation

vuPlatformControllerSetViewOrientation()

VuResult vuPlatformControllerSetViewOrientation	(	VuController *	controller,
		VuViewOrientation	orientation )

Set the current view orientation.

Note

The view orientation must be set to be able to use Vuforia Engine; otherwise device poses may be incorrectly reported (the default value is platform dependent). Even if an application is not doing any rendering (e.g. robotics, CV), it should still correctly set the view orientation to match the way the device is oriented. Furthermore, Vuforia needs to be notified of any changes in orientation. For more information on the platform-specific view orientation descriptors, please see the conversion utility vuPlatformControllerConvertPlatformViewOrientation described below.

On Android and Lumin, Vuforia does internal view orientation consistency checking. Therefore calls to this API will fail on these platforms if the provided view orientation does not align with the actual view orientation.

On iOS and UWP the view orientation should be provided in the VuEngineConfigSet passed to vuEngineCreate via VuPlatformiOSConfig or VuPlatformUWPConfig respectively.

The view orientation should be consistent with the width and height set in vuRenderControllerSetRenderViewConfig. See vuRenderControllerSetRenderViewConfig for more details on the default render view configuration and the requirements regarding updating the render view configuration.

Warning

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

Returns

VU_SUCCESS if the view orientation has been successfully set, VU_FAILED otherwise

vuPlatformControllerConvertPlatformViewOrientation()

VuResult vuPlatformControllerConvertPlatformViewOrientation	(	const VuController *	controller,
		const void *	platformOrientation,
		VuViewOrientation *	vuOrientation )

Utility function for converting a platform-specific orientation descriptor to a Vuforia view orientation value.

Parameters

controller	pointer to the Platform Controller
platformOrientation	must be of the following type on each respective platform (valid values are indicated in parentheses):

• Android: an array of 2 integer values where the first entry (array[0]) is the orientation value reported on an orientation change, i.e. config.orientation in onConfigurationChanged(Configuration config), and the second entry (array[1]) is the amount of rotation from the "natural" orientation of the device, which can be obtained by getWindowManager().getDefaultDisplay().getRotation(). This somewhat cumbersome set of parameters is required because the orientation value (the first entry) does not distinguish between the different landscape (left/right) and portrait (regular/upside down) orientations.
• iOS: a UIInterfaceOrientation value (On Objective C: UIInterfaceOrientationPortrait, UIInterfaceOrientationPortraitUpsideDown, UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationLandscapeLeft; On Swift: portrait, portraitUpsideDown, landscapeRight, landscapeLeft). Please note that, internally Vuforia relies on the corresponding entries having the same numeric value for all languages
• UWP: a DisplayOrientations (Windows.Graphics.Display) value (Portrait, PortraitFlipped, Landscape, LandscapeFlipped). Depending on your build configuration, these enums will be defined in one of the following:
  • C++/CX: Windows::Graphics::Display::DisplayOrientations
  • C++/WinRT: winrt::Windows::Graphics::Display::DisplayOrientations
  • Otherwise: ABI::Windows::Graphics::Display::DisplayOrientations (note that the enum entries bear the "DisplayOrientations_" prefix) Please note that, internally Vuforia relies on the corresponding entries having the same numeric value for all languages

Parameters

vuOrientation

populated with the corresponding Vuforia view orientation value on success

Returns

VU_SUCCESS if the passed platform orientation indicates a valid (known) orientation, and can therefore be converted to a valid Vuforia view orientation; VU_FAILED otherwise OR if this functionality is not supported on the current platform

vuPlatformControllerGetFusionProviderType()

VuResult vuPlatformControllerGetFusionProviderType	(	const VuController *	controller,
		VuFusionProviderType *	fusionProvider )

Get the current fusion provider type.

Note

If the fusionProvider parameter is reported to be VU_FUSION_PROVIDER_TYPE_PLATFORM_SENSOR_FUSION, then you can call vuPlatformControllerGetFusionProviderPlatformType() to query the actual Vuforia Fusion provider's underlying platform's type.

vuPlatformControllerGetFusionProviderPlatformType()

VuResult vuPlatformControllerGetFusionProviderPlatformType	(	const VuController *	controller,
		VuFusionProviderPlatformType *	fusionProviderPlatformType )

Get the current platform fusion provider type if Vuforia Fusion is using platform-provided technology.

Note

The function vuPlatformControllerGetFusionProviderType() reports whether Vuforia Fusion is using platform-provided technology by returning VU_FUSION_PROVIDER_TYPE_PLATFORM_SENSOR_FUSION as fusion provider. If another fusion provider is reported, this call will fail.

Returns

VU_FAILED if not running on platform fusion provider, otherwise VU_SUCCESS

vuPlatformControllerGetDriverLibraryHandle()

VuResult vuPlatformControllerGetDriverLibraryHandle	(	const VuController *	controller,
		void **	handle )

Retrieves the handle to the currently loaded Vuforia Driver library.

Note

This function is only supported when a Vuforia Driver library was loaded during vuEngineCreate() and vuPlatformControllerGetFusionProviderType() reports VU_FUSION_PROVIDER_PLATFORM_TYPE_EXTERNAL.

Parameters

controller	pointer to the Platform Controller
handle	will be populated with the native platform handle for the loaded library which can be used for e.g. dlsym()/GetProcAddress() to load additional functions from the Driver.

Returns

VU_FAILED if no driver library is loaded, otherwise VU_SUCCESS