C API Unity API
C API Reference (Version 10.17.4)
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