Render Controller

Classes
struct	VuRenderViewConfig
	configure the current view More...
struct	VuVideoBackgroundViewInfo
	Video background view information. More...
struct	VuRenderVideoBackgroundData
	Video background texture input. More...

Functions
VuResult	vuEngineGetRenderController (const VuEngine *engine, VuController **controller)
	Retrieve Render Controller to get access to rendering-specific functionality in Engine.
VuResult	vuRenderControllerSetRenderViewConfig (VuController *controller, const VuRenderViewConfig *renderViewConfig)
	Set the current render view configuration. More...
VuResult	vuRenderControllerGetRenderViewConfig (const VuController *controller, VuRenderViewConfig *renderViewConfig)
	Get the current render view configuration. More...
VuResult	vuRenderControllerGetVideoBackgroundViewport (const VuController *controller, VuVector4I *vbViewport)
	Get the video background viewport (its location/size on screen) More...
VuResult	vuRenderControllerSetVideoBackgroundViewport (VuController *controller, const VuVector4I *vbViewport)
	Configure a custom video background viewport (its location/size on screen) More...
VuResult	vuRenderControllerSetVideoBackgroundViewportMode (VuController *controller, VuVideoBackgroundViewportMode vbMode)
	Configure the video background viewport mode. More...
VuResult	vuRenderControllerGetVideoBackgroundViewInfo (const VuController *controller, VuVideoBackgroundViewInfo *viewInfo)
	Get video background view information for rendering view background. More...
VuResult	vuRenderControllerUpdateVideoBackgroundTexture (VuController *controller, const VuState *state, const VuRenderVideoBackgroundData *renderVBData)
	Update the texture data to use for rendering the video background.
VuResult	vuRenderControllerSetProjectionMatrixNearFar (VuController *controller, float nearPlane, float farPlane)
	Set the values for the near and far plane used by Engine for calculating the projection matrix. More...
VuResult	vuRenderControllerGetProjectionMatrixNearFar (const VuController *controller, float *nearPlane, float *farPlane)
	Get the values of the near and far planes currently used by Engine for calculating the projection matrix. More...

Detailed Description

This controller allows you to control the rendering functionalities of the Vuforia SDK include video background configuration.

Function Documentation

vuRenderControllerSetRenderViewConfig()

VuResult vuRenderControllerSetRenderViewConfig	(	VuController *	controller,
		const VuRenderViewConfig *	renderViewConfig
	)

Set the current render view configuration.

Note

On some devices a default, full screen, render view configuration can be determined by Engine during creation. If the device does not provide the necessary information, no default render view configuration will be set and the Application must call this method explicitly. You can use vuRenderControllerGetRenderViewConfig after Engine creation to determine if a default render view configuration was set.

The default, full screen, render view configuration is setup as landscape orientation only, independent of the actual interface orientation at Engine creation time. If the actual interface orientation is different from landscape at Engine creation time, then vuRenderControllerSetRenderViewConfig should be called immediately after Engine has been created to provide the render view configuration in the correct orientation.

An updated configuration must be provided every time there are changes to the render view resolution or orientation. Values provided here must be consistent with the orientation value that has been provided to vuPlatformControllerSetViewOrientation on a view orientation change.

The render view configuration is used in the calculation of the projection matrix reported in the VuRenderState that is intended for augmentation rendering (field VuRenderState::projectionMatrix). Other values used in this calculation of the projection matrix are the near and far planes set in vuRenderControllerSetProjectionMatrixNearFar and the view orientation set in vuPlatformControllerSetViewOrientation.

The render view configuration is also used in the calcualtion of the viewport if no custom viewport has been set. See vuRenderControllerGetVideoBackgroundViewport for details.

Several API calls depend on the availability of a render view configuration (either default one or user provided). If no render view configuration is available the calls to such as vuRenderControllerSetVideoBackgroundViewport, vuRenderControllerGetVideoBackgroundViewport, vuRenderControllerSetVideoBackgroundViewportMode and vuRenderControllerGetVideoBackgroundViewInfo will fail and the call to vuPlatformControllerSetViewOrientation might not be applied correctly.

Warning

The behavior of the default render view configuration will change in an upcoming release. Vuforia Engine will no longer determine a default full screen render view configuration at Engine creation time on platforms where that was supported before. The client will be required to explicitly provide a render view configuration on all platforms.

Returns

VU_SUCCESS if the render view information was set successfully, VU_FAILED if the render view information could not be set

vuRenderControllerGetRenderViewConfig()

VuResult vuRenderControllerGetRenderViewConfig	(	const VuController *	controller,
		VuRenderViewConfig *	renderViewConfig
	)

Get the current render view configuration.

Note

This call will fail if no render view config is set. See vuRenderControllerSetRenderViewConfig for more details.

Warning

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

Returns

VU_SUCCESS on success, or VU_FAILED if no render view config is set

vuRenderControllerGetVideoBackgroundViewport()

VuResult vuRenderControllerGetVideoBackgroundViewport	(	const VuController *	controller,
		VuVector4I *	vbViewport
	)

Get the video background viewport (its location/size on screen)

If a custom viewport has been set via vuRenderControllerSetVideoBackgroundViewport this viewport will be returned. The custom viewport will also be returned when Engine is not running.

If a custom viewport has NOT been set via vuRenderControllerSetVideoBackgroundViewport, Vuforia will calculate a viewport based on the render view config and the current VuVideoBackgroundViewportMode.

Vuforia Engine will calculate the viewport only after Vuforia Engine has been started and a render view config is available. The calculated viewport can also only be requested while Engine is running.

If no viewport is available at all because Vuforia Engine is not running and no viewport has been set via vuRenderControllerSetVideoBackgroundViewport, this call will fail.

Note

The viewport returned here is identical with the viewport in field VuVideoBackgroundViewInfo::viewport that can be retrieved via vuRenderControllerGetVideoBackgroundViewInfo. However, VuVideoBackgroundViewInfo is only available if Engine is running.

Warning

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

Returns

VU_SUCCESS on success, VU_FAILED if no viewport is available

vuRenderControllerSetVideoBackgroundViewport()

VuResult vuRenderControllerSetVideoBackgroundViewport	(	VuController *	controller,
		const VuVector4I *	vbViewport
	)

Configure a custom video background viewport (its location/size on screen)

Note

This call will fail if no render view config is set. See vuRenderControllerSetRenderViewConfig for more details.

When a custom viewport is set, Engine will return the custom viewport via vuRenderControllerGetVideoBackgroundViewport and VuVideoBackgroundViewInfo::viewport. See vuRenderControllerGetVideoBackgroundViewport for more details.

Warning

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

Returns

VU_SUCCESS on success, VU_FAILED if no custom viewport could be set

vuRenderControllerSetVideoBackgroundViewportMode()

VuResult vuRenderControllerSetVideoBackgroundViewportMode	(	VuController *	controller,
		VuVideoBackgroundViewportMode	vbMode
	)

Configure the video background viewport mode.

Note

This call will fail if no render view config is set. See vuRenderControllerSetRenderViewConfig for more details.

The render view configuration is also used in the calcualtion of the viewport if no custom viewport has been set. See vuRenderControllerGetVideoBackgroundViewport for details.

The video backround viewport mode may also be specified on Engine creation via the VuRenderConfig. See the documentation of VuRenderConfig for more details.

Setting this will reset any currently active custom viewport set via vuRenderControllerSetVideoBackgroundViewport. This means no custom viewport will be available after this call.

Warning

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

Returns

VU_SUCCESS on success, VU_FAILED if no viewport mode could be set

vuRenderControllerGetVideoBackgroundViewInfo()

VuResult vuRenderControllerGetVideoBackgroundViewInfo	(	const VuController *	controller,
		VuVideoBackgroundViewInfo *	viewInfo
	)

Get video background view information for rendering view background.

Note

The video background view information is only available while Vuforia Engine is running. This call will fail if Engine is not running.

The video background view information will only be available when a render view config has been set. Otherwise this call will fail. See vuRenderControllerSetRenderViewConfig for more details.

Warning

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

Returns

VU_SUCCESS on success, VU_FAILED if the video background view information could not be retrieved

vuRenderControllerSetProjectionMatrixNearFar()

VuResult vuRenderControllerSetProjectionMatrixNearFar	(	VuController *	controller,
		float	nearPlane,
		float	farPlane
	)

Set the values for the near and far plane used by Engine for calculating the projection matrix.

Note

These values are used in the calculation of the projection matrix reported in the VuRenderState that is intended for augmentation rendering (field VuRenderState::projectionMatrix). Other values used in this calculation of the projection matrix are the near and far planes set in vuRenderControllerSetProjectionMatrixNearFar and the view orientation set in vuPlatformControllerSetViewOrientation.

Default values after Engine creation are 0.01f (near plane) and 100.0f (far plane).

Returns

VU_SUCCESS if the values have been set successfully, VU_FAILED if invalid values have been provided.

vuRenderControllerGetProjectionMatrixNearFar()

VuResult vuRenderControllerGetProjectionMatrixNearFar	(	const VuController *	controller,
		float *	nearPlane,
		float *	farPlane
	)

Get the values of the near and far planes currently used by Engine for calculating the projection matrix.

Returns

VU_SUCCESS on success, VU_FAILED on failure to retrive the values