docs/content/shared-javascript-and-cpp-documentation/layer.md

   1 <!--
   2 /**-->
   3 # Layer ( Layer inherits from Actor) {#layer}
   4
   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.
   7
   8  ![ ](../assets/img/layer/layers.png)
   9  ![ ](layers.png)
  10
  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.
  12
  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.
  17
  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.
  20
  21 ~~~{.js}
  22 // JavaScript Example of adding an actor to the root layer
  23
  24 //  using stage.add() will automatically add actor to the root layer
  25 dali.stage.add( myActor );
  26
  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
  30
  31 // rootLayer.getDepth() == 0
  32
  33 ~~~
  34
  35
  36 ~~~{.cpp}
  37 // C++ example of adding an actor to the root layer
  38
  39 //  using stage.add() will automatically add actor to the root layer
  40 Stage stage = Stage::GetCurrent();
  41 stage.add( myActor );
  42
  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
  46
  47 // rootLayer.getDepth() == 0
  48
  49 ~~~
  50
  51 Example To create two new layers on top of the root layer.
  52
  53
  54 ~~~{.js}
  55 // JavaScript
  56
  57 var layer1 = new dali.Layer();
  58 var layer2 = new dali.Layer();
  59
  60 // the initially depth order of each layer, depends on the order
  61 // it is added to the stage.
  62
  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
  65
  66 dali.stage.add( myActor1);
  67 layer1.add( myActor2);
  68 layer2.add( myActor3);
  69
  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 )
  73 ~~~
  74
  75 ### Layer clipping
  76
  77 Clips the contents of the layer to a rectangle.
  78
  79 ~~~{.js}
  80 // JavaScript
  81
  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
  86 ~~~
  87
  88 ~~~{.cpp}
  89 // C++
  90
  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
  95
  96 ~~~
  97
  98 ### Re-ordering layers
  99
 100 The following functions can be used to change the draw order of the layers.
 101
 102
 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.
 111
 112 Note:
 113  - The root layer can be moved above and below other layers. However, stage.add( actor ), will always use the root layer object.
 114
 115 ### Rendering order of actors inside of a layer
 116
 117 Layers have two behaviour modes:
 118
 119  - LAYER_2D ( Default )
 120  - LAYER_3D
 121
 122 ### Layer_2D
 123
 124 ~~~{.js}
 125 // JavaScript
 126 layer.behaviour = "LAYER_2D";
 127 ~~~
 128
 129 ~~~{.cpp}
 130 // C++
 131 layer.SetBehavior( Layer::LAYER_2D );
 132 ~~~
 133
 134 #### Background
 135
 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
 141
 142  When using  Layer_2D mode depth testing is disabled (depth buffer not used).
 143
 144   With LAYER_2D, the draw order of the renderers is defined by both:
 145
 146  - Renderer depth index.
 147  - Position of actor in the actor tree
 148
 149
 150 Example:
 151
 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.
 154
 155
 156 ![ ](../assets/img/layer/layer2d.png)
 157 ![ ](layer2d.png)
 158
 159
 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:
 162 ~~~
 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)
 173 ~~~
 174
 175 Renderers with higher depth indices are rendered in front of renderers with smaller values.
 176
 177 Everything in the root layer gets rendered first, actors 1..5
 178 Then layer 1, actors 6..8
 179
 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.
 182
 183 ~~~{.js}
 184   var rendererForActor6 = new dali.Renderer( geometry, material );
 185   var rendererForActor7 = new dali.Renderer( geometry, material );
 186   var rendererForActor8 = new dali.Renderer( geometry, material );
 187
 188   rendererForActor6.depthIndex = 2;   // drawn on top ( last)
 189   rendererForActor7.depthIndex = 1;   // draw in the middle
 190   rendererForActor8.depthIndex = 0;   // drawn on bottom ( first)
 191
 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
 195
 196 ~~~
 197
 198 ### Layer_3D
 199
 200 ~~~{.js}
 201 // JavaScript
 202 layer.behaviour = "LAYER_3D";
 203 ~~~
 204
 205 ~~~{.cpp}
 206 // C++
 207 layer.SetBehavior( Layer::LAYER_3D );
 208 ~~~
 209
 210 When using this mode depth testing will be used ( depth buffer enabled ).
 211
 212 Opaque renderers are drawn first and write to the depth buffer.
 213
 214 Then transparent renderers are drawn with depth test enabled but depth write switched off.
 215
 216  ![ ](../assets/img/layer/layers3d.png)
 217  ![ ](layers3d.png)
 218
 219
 220 Transparent renderers are drawn in order of distance
 221 from the camera ( painter's algorithm ).
 222
 223  ![ ](../assets/img/layer/transSort.png)
 224  ![ ](transSort.png)
 225
 226
 227 Note:
 228
 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.
 231
 232
 233 ### Actor drawMode OVERLAY_2D
 234
 235 Inside a layer it is possible to force a tree actors to be drawn on top everything else in the layer.
 236
 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.
 239
 240
 241 Example:
 242
 243 ~~~{.js}
 244 // JavaScript
 245 var layer = new dali.Layer();
 246
 247 layer.behaviour = "LAYER_3D"
 248
 249 dali.stage.add( layer );
 250
 251 layer.add( myActor1 );
 252 layer.add( myActor2 );
 253
 254 myActor3.drawMode = "OVERLAY_2D";
 255
 256 layer.add( myActor3 );   // actor 3 is drawn on top of actor 1 and 2 as it's in the OVERLAY.
 257
 258 myActor3.add( myActor4 ); // actor 4 is drawn on top of actor 3, which is drawn on top of actor 1 and 2.
 259
 260 myActor3.add( myActor5);  // the depth index of actor 4 and 5 renderers will determine which is drawn first
 261 ~~~
 262
 263
 264
 265
 266
 267 ### Layer Actor Specific Properties
 268
 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|
 274
 275   @class Layer
 276   @extends Actor
 277
 278 */