docs/content/programming-guide/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  ![ ](layers.png)
   9
  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.
  11
  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.
  16
  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.
  19
  20
  21 ~~~{.cpp}
  22 // C++ example of adding an actor to the root layer
  23
  24 //  using stage.add() will automatically add actor to the root layer
  25 Stage stage = Stage::GetCurrent();
  26 stage.add( myActor );
  27
  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
  31
  32 // rootLayer.getDepth() == 0
  33
  34 ~~~
  35
  36 Example To create two new layers on top of the root layer.
  37
  38
  39 ### Layer clipping
  40
  41 Clips the contents of the layer to a rectangle.
  42
  43 ~~~{.cpp}
  44 // C++
  45
  46 layer1.SetAnchorPoint( AnchorPoint::CENTER );
  47 layer1.SetParentOrigin( ParentOrigin::CENTER );
  48 layer1.SetClipping( true );
  49 layer1.SetClippingBox( 20, 20, 100, 100 ); // X, Y, Width, Height
  50
  51 ~~~
  52
  53 ### Re-ordering layers
  54
  55 The following functions can be used to change the draw order of the layers.
  56
  57
  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.
  66
  67 Note:
  68  - The root layer can be moved above and below other layers. However, stage.add( actor ), will always use the root layer object.
  69
  70 ### Rendering order of actors inside of a layer
  71
  72 Layers have two behaviour modes:
  73
  74  - LAYER_2D ( Default )
  75  - LAYER_3D
  76
  77 ### Layer_2D
  78
  79 ~~~{.cpp}
  80 // C++
  81 layer.SetBehavior( Layer::LAYER_2D );
  82 ~~~
  83
  84 #### Background
  85
  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
  91
  92  When using  Layer_2D mode depth testing is disabled (depth buffer not used).
  93
  94   With LAYER_2D, the draw order of the renderers is defined by both:
  95
  96  - Renderer depth index.
  97  - Position of actor in the actor tree
  98
  99
 100 Example:
 101
 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.
 104
 105
 106 ![ ](layer2d.png)
 107
 108
 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:
 111 ~~~
 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)
 122 ~~~
 123
 124 Renderers with higher depth indices are rendered in front of renderers with smaller values.
 125
 126 Everything in the root layer gets rendered first, actors 1..5
 127 Then layer 1, actors 6..8
 128
 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.
 131
 132 ~~~{.js}
 133   var rendererForActor6 = new dali.Renderer( geometry, material );
 134   var rendererForActor7 = new dali.Renderer( geometry, material );
 135   var rendererForActor8 = new dali.Renderer( geometry, material );
 136
 137   rendererForActor6.depthIndex = 2;   // drawn on top ( last)
 138   rendererForActor7.depthIndex = 1;   // draw in the middle
 139   rendererForActor8.depthIndex = 0;   // drawn on bottom ( first)
 140
 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
 144
 145 ~~~
 146
 147 ### Layer_3D
 148
 149 ~~~{.cpp}
 150 // C++
 151 layer.SetBehavior( Layer::LAYER_3D );
 152 ~~~
 153
 154 When using this mode depth testing will be used ( depth buffer enabled ).
 155
 156 Opaque renderers are drawn first and write to the depth buffer.
 157
 158 Then transparent renderers are drawn with depth test enabled but depth write switched off.
 159
 160  ![ ](layers3d.png)
 161
 162
 163 Transparent renderers are drawn in order of distance
 164 from the camera ( painter's algorithm ).
 165
 166  ![ ](transSort.png)
 167
 168
 169 Note:
 170
 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.
 173
 174
 175 ### Actor drawMode OVERLAY_2D
 176
 177 Inside a layer it is possible to force a tree actors to be drawn on top everything else in the layer.
 178
 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.
 181
 182
 183 ### Layer Actor Specific Properties
 184
 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|
 190
 191   @extends Actor
 192
 193 */