Tizen Native API  3.0

Layers provide a mechanism for overlaying groups of actors on top of each other. More...

Inheritance diagram for Dali::Layer:
Dali::Actor Dali::Handle Dali::BaseHandle

Classes

struct  Property
 Enumeration for the instance of properties belonging to the Layer class. More...

Public Types

enum  Behavior
 Enumeration for the behavior of the layer. More...
enum  TreeDepthMultiplier
 Enumeration for TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first. More...
typedef float(* SortFunctionType )(const Vector3 &position)
 The sort function type.

Public Member Functions

 Layer ()
 Creates an empty Layer handle.
 ~Layer ()
 Destructor.
 Layer (const Layer &copy)
 Copy constructor.
Layeroperator= (const Layer &rhs)
 Assignment operator.
unsigned int GetDepth () const
 Queries the depth of the layer.
void Raise ()
 Increments the depth of the layer.
void Lower ()
 Decrements the depth of the layer.
void RaiseAbove (Layer target)
 Ensures the layers depth is greater than the target layer.
void LowerBelow (Layer target)
 Ensures the layers depth is less than the target layer.
void RaiseToTop ()
 Raises the layer to the top.
void LowerToBottom ()
 Lowers the layer to the bottom.
void MoveAbove (Layer target)
 Moves the layer directly above the given layer.
void MoveBelow (Layer target)
 Moves the layer directly below the given layer.
void SetBehavior (Behavior behavior)
 Sets the behavior of the layer.
Behavior GetBehavior () const
 Gets the behavior of the layer.
void SetClipping (bool enabled)
 Sets whether clipping is enabled for a layer.
bool IsClipping () const
 Queries whether clipping is enabled for a layer.
void SetClippingBox (int x, int y, int width, int height)
 Sets the clipping box of a layer, in window coordinates.
void SetClippingBox (ClippingBox box)
 Sets the clipping box of a layer in window coordinates.
ClippingBox GetClippingBox () const
 Retrieves the clipping box of a layer in window coordinates.
void SetDepthTestDisabled (bool disable)
 Whether to disable the depth test.
bool IsDepthTestDisabled () const
 Retrieves whether depth test is disabled.
void SetSortFunction (SortFunctionType function)
 This allows the user to specify the sort function that the layer should use.
void SetTouchConsumed (bool consume)
 This allows the user to specify whether this layer should consume touch (including gestures).
bool IsTouchConsumed () const
 Retrieves whether the layer consumes touch (including gestures).
void SetHoverConsumed (bool consume)
 This allows the user to specify whether this layer should consume hover.
bool IsHoverConsumed () const
 Retrieves whether the layer consumes hover.

Static Public Member Functions

static Layer New ()
 Creates a Layer object.
static Layer DownCast (BaseHandle handle)
 Downcasts a handle to Layer handle.

Detailed Description

Layers provide a mechanism for overlaying groups of actors on top of each other.

When added to the stage, a layer can be ordered relative to other layers. The bottom layer is at depth zero. The stage provides a default layer for it's children (see Stage::GetRootLayer()).

Layered actors inherit position etc. as normal, but are drawn in an order determined by the layers. In case of LAYER_3D, the depth buffer is cleared before each layer is rendered unless depth test is disabled or there's no need for it based on the layers contents; actors in lower layers cannot obscure actors in higher layers.

A layer has either LAYER_2D or LAYER_3D mode. LAYER_2D has better performance, the depth test is disabled, and a child actor hides its parent actor. LAYER_3D uses the depth test, thus a close actor hides a farther one. LAYER_2D is the default mode and recommended for general cases. See Layer::Behavior and SetBehavior() for more information.

Layer is a type of Actor, thus can have parent or children actors. A layer influences rendering of its all descendant actors, until another layer appears in the actor tree and manages its own subtree.

If depth test is disabled, there is no performance overhead from clearing the depth buffer.

Actions | Action Name | Layer method called | |-----------------|----------------------| | raise | Raise() | | lower | Lower() | | raiseToTop | RaiseToTop() | | lowerToBottom | LowerToBottom() |

Since:
3.0, DALi version 1.0.0

Member Typedef Documentation

typedef float(* Dali::Layer::SortFunctionType)(const Vector3 &position)

The sort function type.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]positionThis is the actor translation from camera

Member Enumeration Documentation

Enumeration for the behavior of the layer.

Check each value to see how it affects the layer.

Since:
3.0, DALi version 1.0.0
Enumerator:
LAYER_2D 

UI control rendering mode.

Deprecated:
Deprecated since 3.0, DALi version 1.1.45, use LAYER_UI instead
Since:
3.0, DALi version 1.0.0
See also:
LAYER_UI
LAYER_UI 

UI control rendering mode (default mode).

This mode is designed for UI controls. In this mode renderer order will be respective to tree hierarchy of Actors. This mode is expected to have better performance than LAYER_3D as renderers can be sorted more efficiently.

For the following actor tree the rendering order will be A first, then B & C and finally D,E,F regardless of their Z positions. Rendering order between siblings, such as D, E & F or B & C, is determined based on the renderers depth index. In UI we don't normally expect overlap. If you have two overlapped actors, make them parent-child to guarantee order of all renderers.

     Layer1 (parent)
       |
       A
      / \
     B   C
    / \   \
   D   E   F
Since:
3.0, DALi version 1.1.45
LAYER_3D 

Layer will use depth test.

When using this mode, depth test will be used. A depth clear will happen for each layer, which means actors in a layer "above" other layers will be rendered in front of actors in those layers regardless of their Z positions (see Layer::Raise() and Layer::Lower()). Opaque renderers are drawn first and write to the depth buffer. Then transparent renderers are drawn with depth test enabled but depth write switched off. Transparent renderers are drawn based on their distance from the camera. A renderers DEPTH_INDEX property is used to offset the distance to the camera when ordering transparent renderers. This is useful if you want to define the draw order of two or more transparent renderers that are equal distance from the camera. Unlike LAYER_UI, parent-child relationship does not affect rendering order at all.

Since:
3.0, DALi version 1.0.0

Enumeration for TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first.

Since:
3.0, DALi version 1.0.0

Constructor & Destructor Documentation

Creates an empty Layer handle.

This can be initialized with Layer::New(...).

Since:
3.0, DALi version 1.0.0

Destructor.

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

Since:
3.0, DALi version 1.0.0
Dali::Layer::Layer ( const Layer copy)

Copy constructor.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]copyThe actor to copy

Member Function Documentation

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

Downcasts a handle to Layer handle.

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

Since:
3.0, DALi version 1.0.0
Parameters:
[in]handleHandle to an object
Returns:
Handle to a Layer or an uninitialized handle

Reimplemented from Dali::Actor.

Gets the behavior of the layer.

Since:
3.0, DALi version 1.0.0
Returns:
The behavior of the layer

Retrieves the clipping box of a layer in window coordinates.

Since:
3.0, DALi version 1.0.0
Returns:
The clipping box
unsigned int Dali::Layer::GetDepth ( ) const

Queries the depth of the layer.

0 is the bottom most layer, higher number is on top.

Since:
3.0, DALi version 1.0.0
Returns:
The current depth of the layer
Precondition:
Layer is on the stage. If layer is not added to the stage, returns 0.
bool Dali::Layer::IsClipping ( ) const

Queries whether clipping is enabled for a layer.

Since:
3.0, DALi version 1.0.0
Returns:
True if clipping is enabled

Retrieves whether depth test is disabled.

Since:
3.0, DALi version 1.0.0
Returns:
True if depth test is disabled

Retrieves whether the layer consumes hover.

Since:
3.0, DALi version 1.0.0
Returns:
True if consuming hover, false otherwise

Retrieves whether the layer consumes touch (including gestures).

Since:
3.0, DALi version 1.0.0
Returns:
True if consuming touch, false otherwise

Decrements the depth of the layer.

Since:
3.0, DALi version 1.0.0
Precondition:
Layer is on the stage.
void Dali::Layer::LowerBelow ( Layer  target)

Ensures the layers depth is less than the target layer.

If the layer already is below the target layer, its depth is not changed. If the layer was above target, its new depth will be immediately below target.

Since:
3.0, DALi version 1.0.0
Parameters:
targetLayer to get below of
Precondition:
Layer is on the stage.
Target layer is on the stage.
Note:
All layers between this layer and target get new depth values.

Lowers the layer to the bottom.

Since:
3.0, DALi version 1.0.0
Precondition:
layer is on the stage.
void Dali::Layer::MoveAbove ( Layer  target)

Moves the layer directly above the given layer.

After the call, this layers depth will be immediately above target.

Since:
3.0, DALi version 1.0.0
Parameters:
targetLayer to get on top of
Precondition:
Layer is on the stage.
Target layer is on the stage.
Note:
All layers between this layer and target get new depth values.
void Dali::Layer::MoveBelow ( Layer  target)

Moves the layer directly below the given layer.

After the call, this layers depth will be immediately below target.

Since:
3.0, DALi version 1.0.0
Parameters:
targetLayer to get below of
Precondition:
Layer is on the stage.
Target layer is on the stage.
Note:
All layers between this layer and target get new depth values.
static Layer Dali::Layer::New ( ) [static]

Creates a Layer object.

Since:
3.0, DALi version 1.0.0
Returns:
A handle to a newly allocated Layer

Reimplemented from Dali::Actor.

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

Assignment operator.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]rhsThe actor to copy
Returns:
A reference to this

Increments the depth of the layer.

Since:
3.0, DALi version 1.0.0
Precondition:
Layer is on the stage.
void Dali::Layer::RaiseAbove ( Layer  target)

Ensures the layers depth is greater than the target layer.

If the layer already is above the target layer, its depth is not changed. If the layer was below target, its new depth will be immediately above target.

Since:
3.0, DALi version 1.0.0
Parameters:
targetLayer to get above of
Precondition:
Layer is on the stage.
Target layer is on the stage.
Note:
All layers between this layer and target get new depth values.

Raises the layer to the top.

Since:
3.0, DALi version 1.0.0
Precondition:
Layer is on the stage.
void Dali::Layer::SetBehavior ( Behavior  behavior)

Sets the behavior of the layer.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]behaviorThe desired behavior
void Dali::Layer::SetClipping ( bool  enabled)

Sets whether clipping is enabled for a layer.

Clipping is initially disabled; see also SetClippingBox().

Since:
3.0, DALi version 1.0.0
Parameters:
[in]enabledTrue if clipping is enabled
Note:
When clipping is enabled, the default clipping box is empty (0,0,0,0), which means everything is clipped.
void Dali::Layer::SetClippingBox ( int  x,
int  y,
int  width,
int  height 
)

Sets the clipping box of a layer, in window coordinates.

The contents of the layer will not be visible outside this box, when clipping is enabled. The default clipping box is empty (0,0,0,0) which means everything is clipped. You can only do rectangular clipping using this API in window coordinates.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]xThe X-coordinate of the top-left corner of the box
[in]yThe Y-coordinate of the top-left corner of the box
[in]widthThe width of the box
[in]heightThe height of the box

Sets the clipping box of a layer in window coordinates.

The contents of the layer will not be visible outside this box when clipping is enabled. The default clipping box is empty (0,0,0,0).

Since:
3.0, DALi version 1.0.0
Parameters:
[in]boxThe clipping box
void Dali::Layer::SetDepthTestDisabled ( bool  disable)

Whether to disable the depth test.

By default a layer enables depth test if there is more than one opaque actor or if there is one opaque actor and one, or more, transparent actors in LAYER_3D mode. However, it's possible to disable the depth test by calling this method.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]disableTrue disables depth test. false sets the default behavior
void Dali::Layer::SetHoverConsumed ( bool  consume)

This allows the user to specify whether this layer should consume hover.

If set, any layers behind this layer will not be hit-test.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]consumeWhether the layer should consume hover

This allows the user to specify the sort function that the layer should use.

The sort function is used to determine the order in which the actors are drawn and input is processed on the actors in the layer.

A function of the following type should be used:

  float YourSortFunction(const Vector3& position);
Since:
3.0, DALi version 1.0.0
Parameters:
[in]functionThe sort function pointer
Note:
If the sort function returns a low number, the actor with the data will be drawn in front of an actor whose data yields a high value from the sort function.
All child layers use the same sort function. If a child layer is added to this layer, then the sort function used by the child layer will also be the same.
void Dali::Layer::SetTouchConsumed ( bool  consume)

This allows the user to specify whether this layer should consume touch (including gestures).

If set, any layers behind this layer will not be hit-test.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]consumeWhether the layer should consume touch (including gestures)