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.
8 ![ ](../assets/img/layer/layers.png)
11 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.
13 Layers are actors and inherit position, orientation and scale of their parent actor.
14 They are drawn in an order determined by a layer depth value.
15 The depth buffer is cleared before each layer is rendered, unless depth
16 test is disabled or there's no need for it based on the layers contents.
18 **Note: Layers work independently of the actor hierarchy.**
19 They can be positioned anywhere in the actor tree, but their draw order is always defined by their layer.getDepth() value.
22 // JavaScript Example of adding an actor to the root layer
24 // using stage.add() will automatically add actor to the root layer
25 dali.stage.add( myActor );
27 // Or you can explicitly add actor to the root layer.
28 var rootLayer = dali.stage.getRootLayer();
29 rootLayer.add( myActor ); // adds an actor to the root layer
31 // rootLayer.getDepth() == 0
37 // C++ example of adding an actor to the root layer
39 // using stage.add() will automatically add actor to the root layer
40 Stage stage = Stage::GetCurrent();
43 // Or you can explicitly add actor to the root layer.
44 Layer rootLayer = stage.GetRootLayer();
45 rootLayer.add( myActor ); // adds an actor to the root layer
47 // rootLayer.getDepth() == 0
51 Example To create two new layers on top of the root layer.
57 var layer1 = new dali.Layer();
58 var layer2 = new dali.Layer();
60 // the initially depth order of each layer, depends on the order
61 // it is added to the stage.
63 dali.stage.add( layer1 ); // will be drawn on top of root layer
64 dali.stage.add( layer2 ); // will be drawn on top of layer 1
66 dali.stage.add( myActor1);
67 layer1.add( myActor2);
68 layer2.add( myActor3);
70 // dali.stage.getRootLayer().getDepth = 0 myActor1 drawn first ( on bottom )
71 // layer1.getDepth() == 1 myActor2 drawn second ( in middle )
72 // layer2.getDepth() == 2 myActor3 drawn last ( on top )
77 Clips the contents of the layer to a rectangle.
82 layer1.anchorPoint = dali.CENTER;
83 layer1.parentOrigin = dali.CENTER;
84 layer1.clippingEnable = true;
85 layer1.clippingBox = [20,20,100,100]; // X, Y, Width, Height
91 layer1.SetAnchorPoint( AnchorPoint::CENTER );
92 layer1.SetParentOrigin( ParentOrigin::CENTER );
93 layer1.SetClipping( true );
94 layer1.SetClippingBox( 20, 20, 100, 100 ); // X, Y, Width, Height
98 ### Re-ordering layers
100 The following functions can be used to change the draw order of the layers.
103 - Raise() Raise the layer up by 1
104 - Lower() Lower the layer down by 1
105 - RaiseAbove( layer ) Ensures the layers depth is greater than the target layer
106 - LowerBelow( layer ) Ensures the layers depth is less than the target layer
107 - RaiseToTop() raise the layer to the top
108 - LowerToBottom() lower the layer to the bottom
109 - MoveAbove( layer ) Moves the layer directly above the given layer.
110 - MoveBelow( layer ) Moves the layer directly below the given layer.
113 - The root layer can be moved above and below other layers. However, stage.add( actor ), will always use the root layer object.
115 ### Rendering order of actors inside of a layer
117 Layers have two behaviour modes:
119 - LAYER_2D ( Default )
126 layer.behaviour = "LAYER_2D";
131 layer.SetBehavior( Layer::LAYER_2D );
136 - Graphics are drawn in DALi using renderers
137 - Actors can have zero or many renderers
138 - Renderers can be shared by actors
139 - Renderers have a depth index property
140 - In LAYER_2D mode, draw order of a renderer within a layer = Tree depth + renderer depth index
142 When using Layer_2D mode depth testing is disabled (depth buffer not used).
144 With LAYER_2D, the draw order of the renderers is defined by both:
146 - Renderer depth index.
147 - Position of actor in the actor tree
152 We have two layers below. Everything in the root layer is drawn first.
153 If we did dali.stage.getRootLayer().raiseToTop(), then the root layer would be drawn last.
156 ![ ](../assets/img/layer/layer2d.png)
160 The formula for calculating the draw order of a renderer is: depthIndex + ( TREE_DEPTH_MULTIPLIER * tree depth ).
161 Currently Layer::TREE_DEPTH_MULTIPLIER == 1000:
163 Root (root layer) ( depth index offset of 0)
164 +-> Actor1 ( depth index offset of 1000)
165 ++-> Actor2 ( depth Index offset of 2000)
166 +++-> Actor3 ( depth Index offset of 3000)
167 +++-> Actor4 ( depth Index offset of 3000)
168 +++-> Actor5 ( depth Index offset of 3000)
169 +++-> Layer1 ( depth Index has no meaning for layers, layer draw order is independent of the hierarchy).
170 ++++-> Actor6 ( depth Index offset of 4000)
171 ++++-> Actor7 ( depth Index offset of 4000)
172 ++++-> Actor8 ( depth Index offset of 4000)
175 Renderers with higher depth indices are rendered in front of renderers with smaller values.
177 Everything in the root layer gets rendered first, actors 1..5
178 Then layer 1, actors 6..8
180 If we want to determine draw order of actors 6..8, we set the depthIndex on their renderers.
181 For example if we want the render draw order to be 8, 7, 6, with 6 being drawn last.
184 var rendererForActor6 = new dali.Renderer( geometry, material );
185 var rendererForActor7 = new dali.Renderer( geometry, material );
186 var rendererForActor8 = new dali.Renderer( geometry, material );
188 rendererForActor6.depthIndex = 2; // drawn on top ( last)
189 rendererForActor7.depthIndex = 1; // draw in the middle
190 rendererForActor8.depthIndex = 0; // drawn on bottom ( first)
192 daliactor6.addRenderer( rendererForActor6 ); // renderer 6 drawn with index of 2 + 4000 = 4002
193 daliactor7.addRenderer( rendererForActor7 ); // renderer 7 drawn with index of 1 + 4000 = 4001
194 daliactor8.addRenderer( rendererForActor8 ); // renderer 8 drawn with depth index of 0 + 4000 = 4000
202 layer.behaviour = "LAYER_3D";
207 layer.SetBehavior( Layer::LAYER_3D );
210 When using this mode depth testing will be used ( depth buffer enabled ).
212 Opaque renderers are drawn first and write to the depth buffer.
214 Then transparent renderers are drawn with depth test enabled but depth write switched off.
216 ![ ](../assets/img/layer/layers3d.png)
220 Transparent renderers are drawn in order of distance
221 from the camera ( painter's algorithm ).
223 ![ ](../assets/img/layer/transSort.png)
229 - In LAYER_3D mode, actor tree hierarchy makes no difference to draw order
230 - When 2 transparent renderers are the same distance from the camera, you can use depth index to adjust which renderer is drawn first.
233 ### Actor drawMode OVERLAY_2D
235 Inside a layer it is possible to force a tree actors to be drawn on top everything else in the layer.
237 The draw order of the actors inside the tree marked OVERLAY_2D, the draw order is defined by the renderers depth index.
238 Depth testing is not used.
245 var layer = new dali.Layer();
247 layer.behaviour = "LAYER_3D"
249 dali.stage.add( layer );
251 layer.add( myActor1 );
252 layer.add( myActor2 );
254 myActor3.drawMode = "OVERLAY_2D";
256 layer.add( myActor3 ); // actor 3 is drawn on top of actor 1 and 2 as it's in the OVERLAY.
258 myActor3.add( myActor4 ); // actor 4 is drawn on top of actor 3, which is drawn on top of actor 1 and 2.
260 myActor3.add( myActor5); // the depth index of actor 4 and 5 renderers will determine which is drawn first
267 ### Layer Actor Specific Properties
269 | Name | Type | Writable | Animatable|
270 |------------------------|------------|--------------|-----------|
271 | clippingEnable |BOOLEAN | 0 | X |
272 | clippingBox | ARRAY [0,0,400,600]) | 0 | X|
273 | behaviour | STRING ( "LAYER_2D" or "LAYER_3D") | 0 | X|