RenderTasks describe how the Dali scene should be rendered. More...

Inheritance diagram for Dali::RenderTask:

Classes
struct	Property
	Enumeration for instances of properties belonging to the RenderTask class. More...
Public Types
enum	RefreshRate
	Enumeration for the refresh-rate of the RenderTask. More...
typedef Signal< void(RenderTask &source) >	RenderTaskSignalType
	Typedef for signals sent by this class.
typedef bool(*	ScreenToFrameBufferFunction )(Vector2 &coordinates)
	A pointer to a function for converting screen to frame-buffer coordinates.
typedef bool(*const	ConstScreenToFrameBufferFunction )(Vector2 &coordinates)
	A pointer to a function for converting screen to frame-buffer coordinates.
Public Member Functions
	RenderTask ()
	Creates an empty RenderTask handle.
	~RenderTask ()
	Destructor.
	RenderTask (const RenderTask &handle)
	This copy constructor is required for (smart) pointer semantics.
RenderTask &	operator= (const RenderTask &rhs)
	This assignment operator is required for (smart) pointer semantics.
void	SetSourceActor (Actor actor)
	Sets the actors to be rendered.
Actor	GetSourceActor () const
	Retrieves the actors to be rendered.
void	SetExclusive (bool exclusive)
	Sets whether the RenderTask has exclusive access to the source actors; the default is false.
bool	IsExclusive () const
	Queries whether the RenderTask has exclusive access to the source actors.
void	SetInputEnabled (bool enabled)
	Sets whether the render-task should be considered for input handling; the default is true.
bool	GetInputEnabled () const
	Queries whether the render-task should be considered for input handling.
void	SetCameraActor (CameraActor cameraActor)
	Sets the actor from which the scene is viewed.
CameraActor	GetCameraActor () const
	Retrieves the actor from which the scene is viewed.
void	SetTargetFrameBuffer (FrameBufferImage frameBuffer)
	Sets the frame-buffer used as a render target.
FrameBufferImage	GetTargetFrameBuffer () const
	Retrieves the frame-buffer used as a render target.
void	SetFrameBuffer (FrameBuffer frameBuffer)
	Sets the frame-buffer used as a render target.
FrameBuffer	GetFrameBuffer () const
	Retrieves the frame-buffer used as a render target.
void	SetScreenToFrameBufferFunction (ScreenToFrameBufferFunction conversionFunction)
	Sets the function used to convert screen coordinates to frame-buffer coordinates.
ScreenToFrameBufferFunction	GetScreenToFrameBufferFunction () const
	Retrieves the function used to convert screen coordinates to frame-buffer coordinates.
void	SetScreenToFrameBufferMappingActor (Actor mappingActor)
	Sets the actor used to convert screen coordinates to frame-buffer coordinates.
Actor	GetScreenToFrameBufferMappingActor () const
	Retrieves the actor used to convert screen coordinates to frame-buffer coordinates.
void	SetViewportPosition (Vector2 position)
	Sets the GL viewport position used when rendering.
Vector2	GetCurrentViewportPosition () const
	Retrieves the GL viewport position used when rendering.
void	SetViewportSize (Vector2 size)
	Sets the GL viewport size used when rendering.
Vector2	GetCurrentViewportSize () const
	Retrieves the GL viewport size used when rendering.
void	SetViewport (Viewport viewport)
	Sets the GL viewport used when rendering.
Viewport	GetViewport () const
	Retrieves the GL viewport used when rendering.
void	SetClearColor (const Vector4 &color)
	Sets the clear color used when SetClearEnabled(true) is used.
Vector4	GetClearColor () const
	Retrieves the clear color used when SetClearEnabled(true) is used.
void	SetClearEnabled (bool enabled)
	Sets whether the render-task will clear the results of previous render-tasks.
bool	GetClearEnabled () const
	Queries whether the render-task will clear the results of previous render-tasks.
void	SetCullMode (bool cullMode)
	Sets whether the render task will cull the actors to the camera's view frustum.
bool	GetCullMode () const
	Gets the cull mode.
void	SetRefreshRate (unsigned int refreshRate)
	Sets the refresh-rate of the RenderTask.
unsigned int	GetRefreshRate () const
	Queries the refresh-rate of the RenderTask.
bool	WorldToViewport (const Vector3 &position, float &viewportX, float &viewportY) const
	Gets viewport coordinates for given world position.
bool	ViewportToLocal (Actor actor, float viewportX, float viewportY, float &localX, float &localY) const
	Gets actor local coordinates for given viewport coordinates.
RenderTaskSignalType &	FinishedSignal ()
	If the refresh rate is REFRESH_ONCE, connect to this signal to be notified when a RenderTask has finished.
Static Public Member Functions
static RenderTask	DownCast (BaseHandle handle)
	Downcasts a handle to RenderTask handle.
Static Public Attributes
static ConstScreenToFrameBufferFunction	DEFAULT_SCREEN_TO_FRAMEBUFFER_FUNCTION
	The default conversion function returns false for any screen coordinates.
static ConstScreenToFrameBufferFunction	FULLSCREEN_FRAMEBUFFER_FUNCTION
	This conversion function outputs the (unmodified) screen coordinates as frame-buffer coordinates.
static const bool	DEFAULT_EXCLUSIVE
	false
static const bool	DEFAULT_INPUT_ENABLED
	true
static const Vector4	DEFAULT_CLEAR_COLOR
	Color::BLACK.
static const bool	DEFAULT_CLEAR_ENABLED
	false
static const bool	DEFAULT_CULL_MODE
	true
static const unsigned int	DEFAULT_REFRESH_RATE
	REFRESH_ALWAYS.

Detailed Description

RenderTasks describe how the Dali scene should be rendered.

The Stage::GetRenderTaskList() method provides access to an ordered list of render-tasks.

Each RenderTask must specify the source actors to be rendered, and a camera actor from which the scene is viewed.

RenderTasks may optionally target a frame-buffer, otherwise the default GL surface is used; typically this is a window provided by the native system.

By default Dali provides a single RenderTask, which renders the entire actor hierarchy using a default camera actor and GL surface. If stereoscopic rendering is enabled, Dali will create two additional render tasks, on for each eye. Each render task will have its own camera parented to the default camera actor.

The first RenderTask used for input handling will be the last one rendered, which also has input enabled, and has a valid source & camera actor; see SetInputEnabled().

If none of the actors are hit in the last RenderTask rendered, then input handling will continue with the second last RenderTask rendered, and so on.

All RenderTasks which target a frame-buffer (i.e. off screen) will be rendered before all RenderTasks which target the default GL surface. This allows the user to render intermediate targets which are used later when targeting the screen.

A RenderTask targeting a frame-buffer can still be hit-tested, provided that the screen->frame-buffer coordinate conversion is successful; see SetScreenToFrameBufferFunction().

If the refresh rate id REFRESH_ONCE and a "Finish" signal is connected, it will be emitted when the RenderTask is completed. Note that all connected signals must be disconnected before the object is destroyed. This is typically done in the object destructor, and requires either the Dali::Connection object or Dali::RenderTask handle to be stored.

Signals | Signal Name | Method | |--------------|-----------------------| | finished | FinishedSignal() |

Since:: 2.4, DALi version 1.0.0

Member Typedef Documentation

typedef bool(* const Dali::RenderTask::ConstScreenToFrameBufferFunction)(Vector2 &coordinates)

A pointer to a function for converting screen to frame-buffer coordinates.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen

Returns:: True if the conversion was successful, otherwise coordinates should be unmodified

typedef Signal< void (RenderTask& source) > Dali::RenderTask::RenderTaskSignalType

Typedef for signals sent by this class.

Since:: 2.4, DALi version 1.0.0

typedef bool(* Dali::RenderTask::ScreenToFrameBufferFunction)(Vector2 &coordinates)

A pointer to a function for converting screen to frame-buffer coordinates.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen

Returns:: True if the conversion was successful, otherwise coordinates should be unmodified

Member Enumeration Documentation

enum Dali::RenderTask::RefreshRate

Enumeration for the refresh-rate of the RenderTask.

Since:: 2.4, DALi version 1.0.0

Enumerator:

REFRESH_ONCE

Process once only e.g. take a snap-shot of the scene.

Since:: 2.4, DALi version 1.0.0

REFRESH_ALWAYS

Process every frame.

Since:: 2.4, DALi version 1.0.0

Constructor & Destructor Documentation

Dali::RenderTask::RenderTask ( )

Creates an empty RenderTask handle.

This can be initialised with RenderTaskList::CreateRenderTask().

Since:: 2.4, DALi version 1.0.0

Dali::RenderTask::~RenderTask ( )

Destructor.

This is non-virtual since derived Handle types must not contain data or virtual methods.

Since:: 2.4, DALi version 1.0.0

Dali::RenderTask::RenderTask ( const RenderTask & handle )

This copy constructor is required for (smart) pointer semantics.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] handle A reference to the copied handle

Member Function Documentation

static RenderTask Dali::RenderTask::DownCast ( BaseHandle handle ) [static]

Downcasts a handle to RenderTask handle.

If handle points to a RenderTask, the downcast produces valid handle. If not, the returned handle is left uninitialized.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] handle A handle to an object

Returns:: A handle to a RenderTask or an uninitialized handle

Reimplemented from Dali::Handle.

RenderTaskSignalType& Dali::RenderTask::FinishedSignal ( )

If the refresh rate is REFRESH_ONCE, connect to this signal to be notified when a RenderTask has finished.

Since:: 2.4, DALi version 1.0.0

Returns:: The signal to connect to

CameraActor Dali::RenderTask::GetCameraActor ( ) const

Retrieves the actor from which the scene is viewed.

Since:: 2.4, DALi version 1.0.0

Returns:: The scene is viewed from the perspective of this actor

Vector4 Dali::RenderTask::GetClearColor ( ) const

Retrieves the clear color used when SetClearEnabled(true) is used.

Since:: 2.4, DALi version 1.0.0

Returns:: The clear color

Note:: This property can be animated; the return value may not match the value written with SetClearColor().

bool Dali::RenderTask::GetClearEnabled ( ) const

Queries whether the render-task will clear the results of previous render-tasks.

Since:: 2.4, DALi version 1.0.0

Returns:: True if the render-task should clear

bool Dali::RenderTask::GetCullMode ( ) const

Gets the cull mode.

Since:: 2.4, DALi version 1.0.0

Returns:: True if the render task should cull the actors to the camera's view frustum

Vector2 Dali::RenderTask::GetCurrentViewportPosition ( ) const

Retrieves the GL viewport position used when rendering.

Since:: 2.4, DALi version 1.0.0

Returns:: The viewport

Vector2 Dali::RenderTask::GetCurrentViewportSize ( ) const

Retrieves the GL viewport size used when rendering.

Since:: 2.4, DALi version 1.0.0

Returns:: The viewport

FrameBuffer Dali::RenderTask::GetFrameBuffer ( ) const

Retrieves the frame-buffer used as a render target.

Since:: 3.0, DALi version 1.1.38

Returns:: The framebuffer

bool Dali::RenderTask::GetInputEnabled ( ) const

Queries whether the render-task should be considered for input handling.

Since:: 2.4, DALi version 1.0.0

Returns:: True if the render-task should be considered for input handling

unsigned int Dali::RenderTask::GetRefreshRate ( ) const

Queries the refresh-rate of the RenderTask.

Since:: 2.4, DALi version 1.0.0

Returns:: The refresh-rate

ScreenToFrameBufferFunction Dali::RenderTask::GetScreenToFrameBufferFunction ( ) const

Retrieves the function used to convert screen coordinates to frame-buffer coordinates.

Since:: 2.4, DALi version 1.0.0

Returns:: The conversion function

Actor Dali::RenderTask::GetScreenToFrameBufferMappingActor ( ) const

Retrieves the actor used to convert screen coordinates to frame-buffer coordinates.

Since:: 2.4, DALi version 1.0.0

Returns:: The actor used for conversion

Actor Dali::RenderTask::GetSourceActor ( ) const

Retrieves the actors to be rendered.

Since:: 2.4, DALi version 1.0.0

Returns:: This actor and its children will be rendered

FrameBufferImage Dali::RenderTask::GetTargetFrameBuffer ( ) const

Retrieves the frame-buffer used as a render target.

Since:: 2.4, DALi version 1.0.0

Returns:: A valid frame-buffer handle, or an uninitialised handle if off-screen rendering is disabled

Viewport Dali::RenderTask::GetViewport ( ) const

Retrieves the GL viewport used when rendering.

Since:: 2.4, DALi version 1.0.0

Returns:: The viewport

bool Dali::RenderTask::IsExclusive ( ) const

Queries whether the RenderTask has exclusive access to the source actors.

Since:: 2.4, DALi version 1.0.0

Returns:: True if the source actors will only be rendered by this render-task

RenderTask& Dali::RenderTask::operator= ( const RenderTask & rhs )

This assignment operator is required for (smart) pointer semantics.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] rhs A reference to the copied handle

Returns:: A reference to this

void Dali::RenderTask::SetCameraActor ( CameraActor cameraActor )

Sets the actor from which the scene is viewed.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] cameraActor The scene is viewed from the perspective of this actor

void Dali::RenderTask::SetClearColor ( const Vector4 & color )

Sets the clear color used when SetClearEnabled(true) is used.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] color The new clear color

void Dali::RenderTask::SetClearEnabled ( bool enabled )

Sets whether the render-task will clear the results of previous render-tasks.

The default is false.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] enabled True if the render-task should clear

Note:: The default GL surface is cleared automatically at the beginning of each frame; this setting is only useful when 2+ render-tasks are used, and the result of the first task needs to be (partially) cleared before rendering the second.

void Dali::RenderTask::SetCullMode ( bool cullMode )

Sets whether the render task will cull the actors to the camera's view frustum.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] cullMode True if the renderers should be culled

Note:: The default mode is to cull actors.; If the shader uses Shader::Hint::MODIFIES_GEOMETRY then culling optimizations are disabled.

See also:: Shader::Hint

void Dali::RenderTask::SetExclusive ( bool exclusive )

Sets whether the RenderTask has exclusive access to the source actors; the default is false.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] exclusive True if the source actors will only be rendered by this render-task

void Dali::RenderTask::SetFrameBuffer ( FrameBuffer frameBuffer )

Sets the frame-buffer used as a render target.

Since:: 3.0, DALi version 1.1.38

Parameters:

[in] frameBuffer A valid FrameBuffer handle to enable off-screen rendering, or an uninitialized handle to disable it

void Dali::RenderTask::SetInputEnabled ( bool enabled )

Sets whether the render-task should be considered for input handling; the default is true.

The task used for input handling will be last task in the RenderTaskList which has input enabled, and has a valid source & camera actor. A RenderTask targetting a frame-buffer can still be hit-tested, provided that the screen->frame-buffer coordinate conversion is successful; see also SetScreenToFrameBufferFunction().

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] enabled True if the render-task should be considered for input handling

void Dali::RenderTask::SetRefreshRate ( unsigned int refreshRate )

Sets the refresh-rate of the RenderTask.

The default is REFRESH_ALWAYS (1), meaning that the RenderTask will be processed every frame if the scene graph is changing. It may be desirable to process less frequently. For example, SetRefreshRate(3) will process once every 3 frames if the scene graph is changing. If the scene graph is not changing, then the render task will not be rendered, regardless of this value.

The REFRESH_ONCE value means that the RenderTask will be processed once only, to take a snap-shot of the scene. Repeatedly calling SetRefreshRate(REFRESH_ONCE) will cause more snap-shots to be taken.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] refreshRate The new refresh rate

void Dali::RenderTask::SetScreenToFrameBufferFunction ( ScreenToFrameBufferFunction conversionFunction )

Sets the function used to convert screen coordinates to frame-buffer coordinates.

This is useful for hit-testing actors which are rendered off-screen.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] conversionFunction The conversion function

void Dali::RenderTask::SetScreenToFrameBufferMappingActor ( Actor mappingActor )

Sets the actor used to convert screen coordinates to frame-buffer coordinates.

The local coordinates of the actor are mapped as frame-buffer coordinates. This is useful for hit-testing actors which are rendered off-screen.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] mappingActor The actor used for conversion

Note:: The mapping actor needs to be rendered by the default render task to make the mapping work properly.

void Dali::RenderTask::SetSourceActor ( Actor actor )

Sets the actors to be rendered.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] actor This actor and its children will be rendered. If actor is an empty handle, then nothing will be rendered

void Dali::RenderTask::SetTargetFrameBuffer ( FrameBufferImage frameBuffer )

Sets the frame-buffer used as a render target.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] frameBuffer A valid frame-buffer handle to enable off-screen rendering, or an uninitialized handle to disable

void Dali::RenderTask::SetViewport ( Viewport viewport )

Sets the GL viewport used when rendering.

This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. By default this will match the target window or frame-buffer size.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] viewport The new viewport

Note:: Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle.

void Dali::RenderTask::SetViewportPosition ( Vector2 position )

Sets the GL viewport position used when rendering.

This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. By default this will match the target window or frame-buffer size.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] position The viewports position (x,y)

Note:: Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle.

void Dali::RenderTask::SetViewportSize ( Vector2 size )

Sets the GL viewport size used when rendering.

This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. By default this will match the target window or frame-buffer size.

Since:: 2.4, DALi version 1.0.0

Parameters:

[in] size The viewports size (width,height)

bool Dali::RenderTask::ViewportToLocal	(	Actor	actor,
		float	viewportX,
		float	viewportY,
		float &	localX,
		float &	localY
	)		const

Gets actor local coordinates for given viewport coordinates.

Since:: 3.0, DALi version 1.1.13

Parameters:

[in]	actor	The actor describing local coordinate system
[in]	viewportX	The viewport x position
[in]	viewportY	The viewport y position
[out]	localX	The local x position
[out]	localY	The local y position

Returns:: true if the screen position has a local coordinate

bool Dali::RenderTask::WorldToViewport	(	const Vector3 &	position,
		float &	viewportX,
		float &	viewportY
	)		const

Gets viewport coordinates for given world position.

Since:: 3.0, DALi version 1.1.13

Parameters:

[in]	position	The world position
[out]	viewportX	The viewport x position
[out]	viewportY	The viewport y position

Returns:: true if the position has a screen coordinate

Member Data Documentation

ConstScreenToFrameBufferFunction Dali::RenderTask::DEFAULT_SCREEN_TO_FRAMEBUFFER_FUNCTION [static]

The default conversion function returns false for any screen coordinates.

This effectively disables hit-testing for RenderTasks rendering to a frame buffer. See also FULLSCREEN_FRAMEBUFFER_FUNCTION below.

ConstScreenToFrameBufferFunction Dali::RenderTask::FULLSCREEN_FRAMEBUFFER_FUNCTION [static]

This conversion function outputs the (unmodified) screen coordinates as frame-buffer coordinates.

Therefore the contents of an off-screen image is expected to be rendered "full screen".

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation