Tizen Native API

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

Inheritance diagram for Dali::RenderTask:
Dali::Handle Dali::BaseHandle

Classes

struct  Property
 An enumeration of properties belonging to the RenderTask class. More...

Public Types

enum  RefreshRate
 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 ()
 Create an empty RenderTask handle.
 ~RenderTask ()
 Destructor.
 RenderTask (const RenderTask &handle)
 This copy constructor is required for (smart) pointer semantics.
RenderTaskoperator= (const RenderTask &rhs)
 This assignment operator is required for (smart) pointer semantics.
void SetSourceActor (Actor actor)
 Set the actors to be rendered.
Actor GetSourceActor () const
 Retrieve the actors to be rendered.
void SetExclusive (bool exclusive)
 Set whether the RenderTask has exclusive access to the source actors; the default is false.
bool IsExclusive () const
 Query whether the RenderTask has exclusive access to the source actors.
void SetInputEnabled (bool enabled)
 Set whether the render-task should be considered for input handling; the default is true.
bool GetInputEnabled () const
 Query whether the render-task should be considered for input handling.
void SetCameraActor (CameraActor cameraActor)
 Set the actor from which the scene is viewed.
CameraActor GetCameraActor () const
 Retrieve the actor from which the scene is viewed.
void SetTargetFrameBuffer (FrameBufferImage frameBuffer)
 Set the frame-buffer used as a render target.
FrameBufferImage GetTargetFrameBuffer () const
 Retrieve the frame-buffer used as a render target.
void SetScreenToFrameBufferFunction (ScreenToFrameBufferFunction conversionFunction)
 Set the function used to convert screen coordinates to frame-buffer coordinates.
ScreenToFrameBufferFunction GetScreenToFrameBufferFunction () const
 Retrieve the function used to convert screen coordinates to frame-buffer coordinates.
void SetScreenToFrameBufferMappingActor (Actor mappingActor)
 Set the actor used to convert screen coordinates to frame-buffer coordinates.
Actor GetScreenToFrameBufferMappingActor () const
 Retrieve the actor used to convert screen coordinates to frame-buffer coordinates.
void SetViewportPosition (Vector2 position)
 Set the GL viewport position used when rendering.
Vector2 GetCurrentViewportPosition () const
 Retrieve the GL viewport position used when rendering.
void SetViewportSize (Vector2 size)
 Set the GL viewport size used when rendering.
Vector2 GetCurrentViewportSize () const
 Retrieve the GL viewport size used when rendering.
void SetViewport (Viewport viewport)
 Set the GL viewport used when rendering.
Viewport GetViewport () const
 Retrieve the GL viewport used when rendering.
void SetClearColor (const Vector4 &color)
 Set the clear color used when SetClearEnabled(true) is used.
Vector4 GetClearColor () const
 Retrieve the clear color used when SetClearEnabled(true) is used.
void SetClearEnabled (bool enabled)
 Set whether the render-task will clear the results of previous render-tasks.
bool GetClearEnabled () const
 Query whether the render-task will clear the results of previous render-tasks.
void SetCullMode (bool cullMode)
 Set whether the render task will cull the actors to the camera's view frustum.
bool GetCullMode () const
 Get the cull mode.
void SetRefreshRate (unsigned int refreshRate)
 Set the refresh-rate of the RenderTask.
unsigned int GetRefreshRate () const
 Query the refresh-rate of the RenderTask.
RenderTaskSignalTypeFinishedSignal ()
 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)
 Downcast 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 hierachy 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 targetting the screen.

A RenderTask targetting 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.

Since :
2.4

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
Parameters:
[in,out]coordinatesThe 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 for signals sent by this class.

Since :
2.4

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

Since :
2.4
Parameters:
[in,out]coordinatesThe 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

The refresh-rate of the RenderTask.

Since :
2.4
Enumerator:
REFRESH_ONCE 

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

Since :
2.4
REFRESH_ALWAYS 

Process every frame.

Since :
2.4

Constructor & Destructor Documentation

Create an empty RenderTask handle.

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

Since :
2.4

Destructor.

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

Since :
2.4

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

Since :
2.4
Parameters:
[in]handleA reference to the copied handle

Member Function Documentation

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

Downcast 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
Parameters:
[in]handleA handle to an object.
Returns:
A handle to a RenderTask or an uninitialized handle.

Reimplemented from Dali::Handle.

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

Since :
2.4

Retrieve the actor from which the scene is viewed.

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

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

Since :
2.4
Returns:
The clear color.
Note:
This property can be animated; the return value may not match the value written with SetClearColor().

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

Since :
2.4
Returns:
True if the render-task should clear.

Get the cull mode.

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

Retrieve the GL viewport position used when rendering.

Since :
2.4
Returns:
The viewport.

Retrieve the GL viewport size used when rendering.

Since :
2.4
Returns:
The viewport.

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

Since :
2.4
Returns:
True if the render-task should be considered for input handling.
unsigned int Dali::RenderTask::GetRefreshRate ( ) const

Query the refresh-rate of the RenderTask.

Since :
2.4
Returns:
The refresh-rate.

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

Since :
2.4
Returns:
The conversion function.

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

Since :
2.4
Returns:
The actor used for conversion.

Retrieve the actors to be rendered.

Since :
2.4
Returns:
This actor and its children will be rendered.

Retrieve the frame-buffer used as a render target.

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

Retrieve the GL viewport used when rendering.

Since :
2.4
Returns:
The viewport.

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

Since :
2.4
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
Parameters:
[in]rhsA reference to the copied handle
Returns:
A reference to this

Set the actor from which the scene is viewed.

Since :
2.4
Parameters:
[in]cameraActorThe scene is viewed from the perspective of this actor.
void Dali::RenderTask::SetClearColor ( const Vector4 color)

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

Since :
2.4
Parameters:
[in]colorThe new clear color.
void Dali::RenderTask::SetClearEnabled ( bool  enabled)

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

The default is false.

Since :
2.4
Parameters:
[in]enabledTrue 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)

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

Note that this will only affect image views that use the default vertex shader. The default mode is to cull actors.

Since :
2.4
Parameters:
[in]cullModeTrue if the renderers should be culled.
void Dali::RenderTask::SetExclusive ( bool  exclusive)

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

Since :
2.4
Parameters:
[in]exclusiveTrue if the source actors will only be rendered by this render-task.
void Dali::RenderTask::SetInputEnabled ( bool  enabled)

Set 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
Parameters:
[in]enabledTrue if the render-task should be considered for input handling.
void Dali::RenderTask::SetRefreshRate ( unsigned int  refreshRate)

Set 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
Parameters:
[in]refreshRateThe new refresh rate.

Set 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
Parameters:
[in]conversionFunctionThe conversion function.

Set 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
Parameters:
[in]mappingActorThe actor used for conversion.
Note:
The mapping actor needs to be rendered by the default render task to make the mapping work properly.

Set the actors to be rendered.

Since :
2.4
Parameters:
[in]actorThis actor and its children will be rendered. If actor is an empty handle, then nothing will be rendered.

Set the frame-buffer used as a render target.

Since :
2.4
Parameters:
[in]frameBufferA valid frame-buffer handle to enable off-screen rendering, or an uninitialized handle to disable.

Set 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
Parameters:
[in]viewportThe new viewport.
Note:
Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle.

Set 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
Parameters:
[in]positionThe viewports position (x,y)
Note:
Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle.

Set 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
Parameters:
[in]sizeThe viewports size (width,height)

Member Data Documentation

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.

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".