|
Tizen Native API
|
RenderTasks describe how the Dali scene should be rendered. More...
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. | |
| RenderTask & | operator= (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. | |
| 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) |
| 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] 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
| typedef bool(* Dali::RenderTask::ScreenToFrameBufferFunction)(Vector2 &coordinates) |
A pointer to a function for converting screen to frame-buffer coordinates.
- Since :
- 2.4
- 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
The refresh-rate of the RenderTask.
- 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
| Dali::RenderTask::RenderTask | ( | const RenderTask & | handle | ) |
This copy constructor is required for (smart) pointer semantics.
- Since :
- 2.4
- Parameters:
-
[in] handle A 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] handle A 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
| CameraActor Dali::RenderTask::GetCameraActor | ( | ) | const |
Retrieve the actor from which the scene is viewed.
- Since :
- 2.4
- Returns:
- The scene is viewed from the perspective of this actor.
| Vector4 Dali::RenderTask::GetClearColor | ( | ) | const |
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().
| bool Dali::RenderTask::GetClearEnabled | ( | ) | const |
Query whether the render-task will clear the results of previous render-tasks.
- Since :
- 2.4
- Returns:
- True if the render-task should clear.
| bool Dali::RenderTask::GetCullMode | ( | ) | const |
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.
| bool Dali::RenderTask::GetInputEnabled | ( | ) | const |
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 |
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.
| Actor Dali::RenderTask::GetSourceActor | ( | ) | const |
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.
| Viewport Dali::RenderTask::GetViewport | ( | ) | const |
Retrieve the GL viewport used when rendering.
- Since :
- 2.4
- Returns:
- The viewport.
| bool Dali::RenderTask::IsExclusive | ( | ) | const |
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] rhs A reference to the copied handle
- Returns:
- A reference to this
| void Dali::RenderTask::SetCameraActor | ( | CameraActor | cameraActor | ) |
Set the actor from which the scene is viewed.
- Since :
- 2.4
- Parameters:
-
[in] cameraActor The 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] color The 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] 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 | ) |
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] cullMode True 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] exclusive True 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] enabled True 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] refreshRate The new refresh rate.
| void Dali::RenderTask::SetScreenToFrameBufferFunction | ( | ScreenToFrameBufferFunction | conversionFunction | ) |
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] conversionFunction The conversion function.
| void Dali::RenderTask::SetScreenToFrameBufferMappingActor | ( | Actor | mappingActor | ) |
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] 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 | ) |
Set the actors to be rendered.
- Since :
- 2.4
- 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 | ) |
Set the frame-buffer used as a render target.
- Since :
- 2.4
- 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 | ) |
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] 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 | ) |
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] 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 | ) |
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] size The 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".