Renderer Class Reference

Detailed Description

A helper class that provides common AR related rendering tasks.

The Renderer class provides methods to fulfill typical AR related tasks such as rendering the video background and 3D objects with up-to-date pose data. It also exposes methods for configuring the rendering frame rate in both AR and VR use cases.

Note

Some methods of the Renderer class may only be called from the render thread.

Inheritance diagram for Renderer:

Public Types
enum	FPSHINT_FLAGS {   FPSHINT_NONE = 0,   FPSHINT_NO_VIDEOBACKGROUND = 1 << 0,   FPSHINT_POWER_EFFICIENCY = 1 << 1,   FPSHINT_FAST = 1 << 2,   FPSHINT_DEFAULT_FLAGS = FPSHINT_NONE }
	Flags for getRecommendedFps() to provide hints about the rendering context. More...

Public Member Functions
virtual void	begin (State state, const RenderData *renderData=0)=0
	Tell the Renderer that rendering of the current frame is about to begin using a specific State. More...
virtual void	end (const RenderData *renderData=0)=0
	Tell the Renderer that rendering is finished. More...
virtual bool	updateVideoBackgroundTexture (const TextureUnit *textureUnit=0)=0
	Update the video background texture. More...
virtual void	setVideoBackgroundConfig (const VideoBackgroundConfig &cfg)=0
	Configure the layout of the video background (its location/size on screen). More...
virtual const VideoBackgroundConfig &	getVideoBackgroundConfig () const =0
	Get the current layout configuration of the video background. More...
virtual const VideoBackgroundTextureInfo &	getVideoBackgroundTextureInfo ()=0
	Get the texture info associated with the current video background. More...
virtual bool	setVideoBackgroundTexture (const TextureData &textureData)=0
	Tell Vuforia which texture to use when updating the video background. More...
virtual bool	setTargetFps (int fps)=0
	Set a target rendering frame rate. More...
virtual int	getRecommendedFps (int flags=FPSHINT_DEFAULT_FLAGS) const =0
	Get a recommended rendering frame rate based on application usage context. More...

Static Public Member Functions
static Renderer &	getInstance ()
	Returns the Renderer singleton instance. More...

Static Public Attributes
static const int	TARGET_FPS_CONTINUOUS
	Target FPS value representing continuous rendering. More...

Member Enumeration Documentation

enum FPSHINT_FLAGS

Flags for getRecommendedFps() to provide hints about the rendering context.

Enumerator
FPSHINT_NONE	No FPS hint defined.
FPSHINT_NO_VIDEOBACKGROUND	The application does not draw the video background (in optical see- through AR or VR mode). Do not set this flag when in video see- through AR mode.
FPSHINT_POWER_EFFICIENCY	The application should be conservative in its power consumption, in order to reduce heat accumulation and increase battery life. On some devices this may come at the cost of reduced application performance and decreased quality of experience.
FPSHINT_FAST	The application uses content that requires a high rendering rate, e.g. smooth character animation or a physics engine that requires frequent updates.
FPSHINT_DEFAULT_FLAGS	Default flags used by Vuforia to determine FPS settings.

Member Function Documentation

static Renderer& getInstance ( )

static

Returns the Renderer singleton instance.

virtual void begin ( State  state, const RenderData *  renderData = 0  )

pure virtual

Tell the Renderer that rendering of the current frame is about to begin using a specific State.

Use this method if you want to draw a specific camera frame, rather than the latest available one.

Parameters

state	the State that rendering will be based on.
renderData	a pointer to 3D graphics rendering API-specific data, which may not be required for the current API (such as OpenGL ES). The renderData object must remain valid until all drawing commands are completed.

Note

May only be called from the render thread.

You may pass a different renderData object to end(); details are platform specific

virtual void end ( const RenderData *  renderData = 0 )

pure virtual

Tell the Renderer that rendering is finished.

Note

May only be called from the render thread.

Parameters

renderData

A pointer to 3D graphics rendering API-specific data, which may not be required for the current API (such as OpenGL ES). The renderData object must remain valid until the call returns.

virtual bool updateVideoBackgroundTexture ( const TextureUnit *  textureUnit = 0 )

pure virtual

Update the video background texture.

Parameters

textureUnit

A pointer to a 3D graphics rendering API specific identifier which binds the texture to the textureUnit value. Pass NULL if you do not wish Vuforia to bind the texture to the textureUnit.

This method may only be called on the render thread, between calls to begin() and end().

The textureUnit (if any) can be discarded after the call as it is only used during the call.

virtual void setVideoBackgroundConfig ( const VideoBackgroundConfig &  cfg )

pure virtual

Configure the layout of the video background (its location/size on screen).

virtual const VideoBackgroundConfig& getVideoBackgroundConfig ( ) const

pure virtual

Get the current layout configuration of the video background.

virtual const VideoBackgroundTextureInfo& getVideoBackgroundTextureInfo ( )

pure virtual

Get the texture info associated with the current video background.

The result is only valid after a call to updateVideoBackgroundTexture().

virtual bool setVideoBackgroundTexture ( const TextureData &  textureData )

pure virtual

Tell Vuforia which texture to use when updating the video background.

Use in conjunction with updateVideoBackgroundTexture().

Note

May only be called from the render thread.

Parameters

textureData

A reference to 3D graphics rendering API specific texture data, such as GLTextureData. Vuforia makes a copy of the textureData object, so you can release the data after the call has been made.

virtual bool setTargetFps ( int  fps )

pure virtual

Set a target rendering frame rate.

Request a rendering frame rate that the application should target in its render loop. Not all requested frame rates may be achievable on all devices and/or usage contexts.

The target frame rate may influence power consumption, heat buildup, battery life and/or application performance. See getRecommendedFps() for more details.

You may use a fixed rate (such as 30 or 60). To get a recommended frame rate, call getRecommendedFps() specifying your usage context via the flags.

Parameters

fps	The desired frame rate, in frames per second, or TARGET_FPS_CONTINUOUS for continuous rendering (if supported).

Returns

true on success, otherwise false (check application logs for details).

virtual int getRecommendedFps ( int  flags = FPSHINT_DEFAULT_FLAGS ) const

pure virtual

Get a recommended rendering frame rate based on application usage context.

The target rendering frame rate of an AR or VR application is an important trade-off between optimal experience and device power usage. The choice is influenced by multiple parameters including device type, the active Trackers, the camera and/or sensor frame rates.

Furthermore there are application specific trade offs to consider, which you can pass to this method via FPSHINT_FLAGS. For example, an application with animated content may need consistent 60 fps rendering, even on a device that can only deliver tracking results at 30 fps.

This method considers the capabilities of the current device along with any hint flags passed to it and returns a recommended frame rate, which should be passed to setTargetFps().

Note

This method may return different values based on the CameraDevice's VideoMode and/or the set of currently active Trackers. It is therefore recommended that you call this method only after initializing the camera and starting all desired Trackers, and possibly again after transitioning between application modes (for example when swapping from AR to VR mode or back).

Parameters

flags

Flags which hint at your application's usage context.

Returns

A recommended target frames per second, which should be passed to setTargetFps().

Member Data Documentation

const int TARGET_FPS_CONTINUOUS

static

Target FPS value representing continuous rendering.