3 # Layer ( Layer inherits from Actor) {#layer}
5 Layers provide a mechanism for overlaying groups of actors on top of each other.
6 Layers can also clip their contents to exclude any content outside a user defined area.
10 When a layer is added to the stage it is assigned a unique depth value. By default the stage has a root layer with a depth value of 0.
12 Layers are actors and inherit position, orientation and scale of their parent actor.
13 They are drawn in an order determined by a layer depth value.
14 The depth buffer is cleared before each layer is rendered, unless depth
15 test is disabled or there's no need for it based on the layers contents.
17 **Note: Layers work independently of the actor hierarchy.**
18 They can be positioned anywhere in the actor tree, but their draw order is always defined by their layer.getDepth() value.
22 // C++ example of adding an actor to the root layer
24 // using stage.add() will automatically add actor to the root layer
25 Stage stage = Stage::GetCurrent();
28 // Or you can explicitly add actor to the root layer.
29 Layer rootLayer = stage.GetRootLayer();
30 rootLayer.add( myActor ); // adds an actor to the root layer
32 // rootLayer.getDepth() == 0
36 Example To create two new layers on top of the root layer.
41 Clips the contents of the layer to a rectangle.
46 layer1.SetProperty( Actor::Property::ANCHOR_POINT, AnchorPoint::CENTER );
47 layer1.SetParentOrigin( ParentOrigin::CENTER );
48 layer1.SetClipping( true );
49 layer1.SetClippingBox( 20, 20, 100, 100 ); // X, Y, Width, Height
53 ### Re-ordering layers
55 The following functions can be used to change the draw order of the layers.
58 - Raise() Raise the layer up by 1
59 - Lower() Lower the layer down by 1
60 - RaiseAbove( layer ) Ensures the layers depth is greater than the target layer
61 - LowerBelow( layer ) Ensures the layers depth is less than the target layer
62 - RaiseToTop() raise the layer to the top
63 - LowerToBottom() lower the layer to the bottom
64 - MoveAbove( layer ) Moves the layer directly above the given layer.
65 - MoveBelow( layer ) Moves the layer directly below the given layer.
68 - The root layer can be moved above and below other layers. However, stage.add( actor ), will always use the root layer object.
70 ### Rendering order of actors inside of a layer
72 Layers have two behaviour modes:
74 - LAYER_2D ( Default )
81 layer.SetBehavior( Layer::LAYER_2D );
86 - Graphics are drawn in DALi using renderers
87 - Actors can have zero or many renderers
88 - Renderers can be shared by actors
89 - Renderers have a depth index property
90 - In LAYER_2D mode, draw order of a renderer within a layer = Tree depth + renderer depth index
92 When using Layer_2D mode depth testing is disabled (depth buffer not used).
94 With LAYER_2D, the draw order of the renderers is defined by both:
96 - Renderer depth index.
97 - Position of actor in the actor tree
102 We have two layers below. Everything in the root layer is drawn first.
103 If we did dali.stage.getRootLayer().raiseToTop(), then the root layer would be drawn last.
109 The formula for calculating the draw order of a renderer is: depthIndex + ( TREE_DEPTH_MULTIPLIER * tree depth ).
110 Currently Layer::TREE_DEPTH_MULTIPLIER == 1000:
112 Root (root layer) ( depth index offset of 0)
113 +-> Actor1 ( depth index offset of 1000)
114 ++-> Actor2 ( depth Index offset of 2000)
115 +++-> Actor3 ( depth Index offset of 3000)
116 +++-> Actor4 ( depth Index offset of 3000)
117 +++-> Actor5 ( depth Index offset of 3000)
118 +++-> Layer1 ( depth Index has no meaning for layers, layer draw order is independent of the hierarchy).
119 ++++-> Actor6 ( depth Index offset of 4000)
120 ++++-> Actor7 ( depth Index offset of 4000)
121 ++++-> Actor8 ( depth Index offset of 4000)
124 Renderers with higher depth indices are rendered in front of renderers with smaller values.
126 Everything in the root layer gets rendered first, actors 1..5
127 Then layer 1, actors 6..8
129 If we want to determine draw order of actors 6..8, we set the depthIndex on their renderers.
130 For example if we want the render draw order to be 8, 7, 6, with 6 being drawn last.
133 var rendererForActor6 = new dali.Renderer( geometry, material );
134 var rendererForActor7 = new dali.Renderer( geometry, material );
135 var rendererForActor8 = new dali.Renderer( geometry, material );
137 rendererForActor6.depthIndex = 2; // drawn on top ( last)
138 rendererForActor7.depthIndex = 1; // draw in the middle
139 rendererForActor8.depthIndex = 0; // drawn on bottom ( first)
141 daliactor6.addRenderer( rendererForActor6 ); // renderer 6 drawn with index of 2 + 4000 = 4002
142 daliactor7.addRenderer( rendererForActor7 ); // renderer 7 drawn with index of 1 + 4000 = 4001
143 daliactor8.addRenderer( rendererForActor8 ); // renderer 8 drawn with depth index of 0 + 4000 = 4000
151 layer.SetBehavior( Layer::LAYER_3D );
154 When using this mode depth testing will be used ( depth buffer enabled ).
156 Opaque renderers are drawn first and write to the depth buffer.
158 Then transparent renderers are drawn with depth test enabled but depth write switched off.
163 Transparent renderers are drawn in order of distance
164 from the camera ( painter's algorithm ).
171 - In LAYER_3D mode, actor tree hierarchy makes no difference to draw order
172 - When 2 transparent renderers are the same distance from the camera, you can use depth index to adjust which renderer is drawn first.
175 ### Actor drawMode OVERLAY_2D
177 Inside a layer it is possible to force a tree actors to be drawn on top everything else in the layer.
179 The draw order of the actors inside the tree marked OVERLAY_2D, the draw order is defined by the renderers depth index.
180 Depth testing is not used.
183 ### Layer Actor Specific Properties
185 | Name | Type | Writable | Animatable|
186 |------------------------|------------|--------------|-----------|
187 | clippingEnable |BOOLEAN | 0 | X |
188 | clippingBox | ARRAY [0,0,400,600]) | 0 | X|
189 | behaviour | STRING ( "LAYER_2D" or "LAYER_3D") | 0 | X|