dali/public-api/actors/layer.h

   1 #ifndef DALI_LAYER_H
   2 #define DALI_LAYER_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <cstdint> // uint32_t
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/actors/actor.h>
  26 #include <dali/public-api/math/rect.h>
  27 #include <dali/public-api/math/vector3.h>
  28 #include <dali/public-api/object/ref-object.h>
  29
  30 namespace Dali
  31 {
  32 /**
  33  * @addtogroup dali_core_actors
  34  * @{
  35  */
  36
  37 namespace Internal DALI_INTERNAL
  38 {
  39 class Layer;
  40 }
  41
  42 /**
  43  * @brief Rectangle describing area on screen that a layer can draw to.
  44  *
  45  * @SINCE_1_0.0
  46  * @see Dali::Layer::SetClippingBox()
  47  */
  48 using ClippingBox = Rect<int32_t>;
  49
  50 /**
  51  * @brief Layers provide a mechanism for overlaying groups of actors on top of each other.
  52  *
  53  * When added to a scene, a layer can be ordered relative to other
  54  * layers. The bottom layer is at depth zero. A scene provides a default
  55  * layer for its children.
  56  *
  57  * Layered actors inherit position etc. as normal, but are drawn in an order
  58  * determined by the layers. In case of LAYER_3D, the depth buffer is cleared
  59  * before each layer is rendered unless depth test is disabled or there's no
  60  * need for it based on the layer's contents; actors in lower layers cannot
  61  * obscure actors in higher layers.
  62  *
  63  * A layer has either LAYER_UI or LAYER_3D mode. LAYER_UI has better
  64  * performance, the depth test is disabled, and a child actor hides its
  65  * parent actor.  LAYER_3D uses the depth test, thus a close actor hides a
  66  * farther one.  LAYER_UI is the default mode and recommended for general
  67  * cases.  See Layer::Behavior and SetBehavior() for more information.
  68  *
  69  * Layer is a type of Actor, thus can have parent or children actors.  A
  70  * layer influences rendering of its all descendant actors, until another
  71  * layer appears in the actor tree and manages its own subtree.
  72  *
  73  * If depth test is disabled, there is no performance overhead from clearing
  74  * the depth buffer.
  75  *
  76  * Actions
  77  * | %Action Name    | %Layer method called |
  78  * |-----------------|----------------------|
  79  * | raise           | @ref Raise()         |
  80  * | lower           | @ref Lower()         |
  81  * | raiseToTop      | @ref RaiseToTop()    |
  82  * | lowerToBottom   | @ref LowerToBottom() |
  83  * @SINCE_1_0.0
  84  */
  85 class DALI_CORE_API Layer : public Actor
  86 {
  87 public:
  88   /**
  89    * @brief Enumeration for the instance of properties belonging to the Layer class.
  90    *
  91    * Properties additional to Actor.
  92    * @SINCE_1_0.0
  93    */
  94   struct Property
  95   {
  96     /**
  97      * @brief Enumeration for the instance of properties belonging to the Layer class.
  98      *
  99      * Properties additional to Actor.
 100      * @SINCE_1_0.0
 101      */
 102     enum
 103     {
 104       CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clippingEnable",   type bool @SINCE_1_0.0
 105       CLIPPING_BOX,                                                 ///< name "clippingBox",      type Rect<int32_t> @SINCE_1_0.0
 106       BEHAVIOR,                                                     ///< name "behavior",         type integer or string @SINCE_1_0.0
 107
 108       /**
 109        * @brief The current depth of the layer.
 110        * @details Name "depth", type Property::INTEGER. Read-only
 111        * @note 0 is the bottom most layer, higher number is on top.
 112        * @note Layer should be on the stage. If layer is not added to the stage, the depth is 0.
 113        * @SINCE_1_9.16
 114        */
 115       DEPTH,
 116
 117       /**
 118        * @brief Whether to enable the depth test.
 119        * @details Name "depthTest", type Property::BOOLEAN.
 120        * @note By default a layer enables depth test if there is more than one opaque actor
 121        * or if there is one opaque actor and one, or more, transparent actors in LAYER_3D mode.
 122        * However, it's possible to disable the depth test by setting this property to False.
 123        * @SINCE_1_9.16
 124        */
 125       DEPTH_TEST,
 126
 127       /**
 128        * @brief Whether this layer should consume touch (including gestures).
 129        * @details Name "consumesTouch", type Property::BOOLEAN.
 130        * @note When this is True, any layers behind this layer will not be hit-test.
 131        * @SINCE_1_9.16
 132        */
 133       CONSUMES_TOUCH,
 134
 135       /**
 136        * @brief Whether this layer should consume hover (including gestures).
 137        * @details Name "consumesHover", type Property::BOOLEAN.
 138        * @note When this is True, any layers behind this layer will not be hit-test.
 139        * @SINCE_1_9.16
 140        */
 141       CONSUMES_HOVER,
 142     };
 143   };
 144
 145   /**
 146    * @brief Enumeration for the behavior of the layer.
 147    *
 148    * Check each value to see how it affects the layer.
 149    * @SINCE_1_0.0
 150    */
 151   enum Behavior
 152   {
 153     /**
 154      * @brief UI control rendering mode (default mode).
 155      *
 156      * This mode is designed for UI controls that can overlap. In this
 157      * mode renderer order will be respective to the tree hierarchy of
 158      * Actors.
 159      *
 160      * The rendering order is depth first, so for the following actor tree,
 161      * A will be drawn first, then B, D, E, then C, F.  This ensures that
 162      * overlapping actors are drawn as expected (whereas, with breadth first
 163      * traversal, the actors would interleave).
 164      *
 165      * @code
 166      *
 167      *     Layer1 (parent)
 168      *       |
 169      *       A
 170      *      / \
 171      *     B   C
 172      *    / \   \
 173      *   D   E   F
 174      *
 175      * @endcode
 176      *
 177      * To change the order of sibling actors, use the Actor::Raise and
 178      * Actor::Lower APIs. Within an actor, the Renderer depth index dictates
 179      * the order the renderers are drawn.
 180      *
 181      * @SINCE_1_1.45
 182      */
 183     LAYER_UI,
 184
 185     /**
 186      * @brief Layer will use depth test.
 187      *
 188      * This mode is designed for a 3 dimensional scene where actors in front
 189      * of other actors will obscure them, i.e. the actors are sorted by the
 190      * distance from the camera.
 191      *
 192      * When using this mode, a depth test will be used. A depth clear will
 193      * happen for each layer, which means actors in a layer "above" other
 194      * layers will be rendered in front of actors in those layers regardless
 195      * of their Z positions (see Layer::Raise() and Layer::Lower()).
 196      *
 197      * Opaque renderers are drawn first and write to the depth buffer.  Then
 198      * transparent renderers are drawn with depth test enabled but depth
 199      * write switched off.  Transparent renderers are drawn based on their
 200      * distance from the camera.  A renderer's DEPTH_INDEX property is used to
 201      * offset the distance to the camera when ordering transparent renderers.
 202      *
 203      * This is useful if you want to define the draw order of two or more
 204      * transparent renderers that are equal distance from the camera.  Unlike
 205      * LAYER_UI, parent-child relationship does not affect rendering order at
 206      * all.
 207      *
 208      * @SINCE_1_0.0
 209      */
 210     LAYER_3D
 211
 212   };
 213
 214   /**
 215    * @brief The sort function type.
 216    *
 217    * @SINCE_1_0.0
 218    * @param[in] position This is the actor translation from camera
 219    */
 220   using SortFunctionType = float (*)(const Vector3&);
 221
 222   /**
 223    * @brief Creates an empty Layer handle.
 224    *
 225    * This can be initialized with Layer::New(...).
 226    * @SINCE_1_0.0
 227    */
 228   Layer();
 229
 230   /**
 231    * @brief Creates a Layer object.
 232    *
 233    * @SINCE_1_0.0
 234    * @return A handle to a newly allocated Layer
 235    */
 236   static Layer New();
 237
 238   /**
 239    * @brief Downcasts a handle to Layer handle.
 240    *
 241    * If handle points to a Layer, the downcast produces valid handle.
 242    * If not, the returned handle is left uninitialized.
 243    * @SINCE_1_0.0
 244    * @param[in] handle Handle to an object
 245    * @return Handle to a Layer or an uninitialized handle
 246    */
 247   static Layer DownCast(BaseHandle handle);
 248
 249   /**
 250    * @brief Destructor.
 251    *
 252    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 253    * @SINCE_1_0.0
 254    */
 255   ~Layer();
 256
 257   /**
 258    * @brief Copy constructor.
 259    *
 260    * @SINCE_1_0.0
 261    * @param[in] copy The actor to copy
 262    */
 263   Layer(const Layer& copy);
 264
 265   /**
 266    * @brief Assignment operator.
 267    *
 268    * @SINCE_1_0.0
 269    * @param[in] rhs The actor to copy
 270    * @return A reference to this
 271    */
 272   Layer& operator=(const Layer& rhs);
 273
 274   /**
 275    * @brief Move constructor.
 276    *
 277    * @SINCE_1_9.22
 278    * @param[in] rhs The layer to move
 279    */
 280   Layer(Layer&& rhs);
 281
 282   /**
 283    * @brief Move assignment operator.
 284    *
 285    * @SINCE_1_9.22
 286    * @param[in] rhs The layer to move
 287    * @return A reference to this
 288    */
 289   Layer& operator=(Layer&& rhs);
 290
 291   /**
 292    * @brief Increments the depth of the layer.
 293    *
 294    * @SINCE_1_0.0
 295    * @pre Layer is on the stage.
 296    */
 297   void Raise();
 298
 299   /**
 300    * @brief Decrements the depth of the layer.
 301    *
 302    * @SINCE_1_0.0
 303    * @pre Layer is on the stage.
 304    */
 305   void Lower();
 306
 307   /**
 308    * @brief Ensures the layers depth is greater than the target layer.
 309    *
 310    * If the layer already is above the target layer, its depth is not changed.
 311    * If the layer was below target, its new depth will be immediately above target.
 312    * @SINCE_1_0.0
 313    * @param target Layer to get above of
 314    * @pre Layer is on the stage.
 315    * @pre Target layer is on the stage.
 316    * @note All layers between this layer and target get new depth values.
 317    */
 318   void RaiseAbove(Layer target);
 319
 320   /**
 321    * @brief Ensures the layers depth is less than the target layer.
 322    *
 323    * If the layer already is below the target layer, its depth is not changed.
 324    * If the layer was above target, its new depth will be immediately below target.
 325    * @SINCE_1_0.0
 326    * @param target Layer to get below of
 327    * @pre Layer is on the stage.
 328    * @pre Target layer is on the stage.
 329    * @note All layers between this layer and target get new depth values.
 330    */
 331   void LowerBelow(Layer target);
 332
 333   /**
 334    * @brief Raises the layer to the top.
 335    * @SINCE_1_0.0
 336    * @pre Layer is on the stage.
 337    */
 338   void RaiseToTop();
 339
 340   /**
 341    * @brief Lowers the layer to the bottom.
 342    * @SINCE_1_0.0
 343    * @pre layer is on the stage.
 344    */
 345   void LowerToBottom();
 346
 347   /**
 348    * @brief Moves the layer directly above the given layer.
 349    *
 350    * After the call, this layers depth will be immediately above target.
 351    * @SINCE_1_0.0
 352    * @param target Layer to get on top of
 353    * @pre Layer is on the stage.
 354    * @pre Target layer is on the stage.
 355    * @note All layers between this layer and target get new depth values.
 356    */
 357   void MoveAbove(Layer target);
 358
 359   /**
 360    * @brief Moves the layer directly below the given layer.
 361    *
 362    * After the call, this layers depth will be immediately below target.
 363    * @SINCE_1_0.0
 364    * @param target Layer to get below of
 365    * @pre Layer is on the stage.
 366    * @pre Target layer is on the stage.
 367    * @note All layers between this layer and target get new depth values.
 368    */
 369   void MoveBelow(Layer target);
 370
 371   // Sorting
 372
 373   /**
 374    * @brief This allows the user to specify the sort function that the layer should use.
 375    *
 376    * The sort function is used to determine the order in which the actors are drawn
 377    * and input is processed on the actors in the layer.
 378    *
 379    * A function of the following type should be used:
 380    * @code
 381    *  float YourSortFunction(const Vector3& position);
 382    * @endcode
 383    *
 384    * @SINCE_1_0.0
 385    * @param[in] function The sort function pointer
 386    * @note If the sort function returns a low number, the actor with the data will be
 387    * drawn in front of an actor whose data yields a high value from the sort function.
 388    *
 389    * @note All child layers use the same sort function. If a child layer is added to this
 390    * layer, then the sort function used by the child layer will also be the same.
 391    *
 392   */
 393   void SetSortFunction(SortFunctionType function);
 394
 395   /**
 396    * @brief Retrieves whether the layer consumes hover.
 397    *
 398    * @SINCE_1_0.0
 399    * @return @c True if consuming hover, @c false otherwise
 400    */
 401   bool IsHoverConsumed() const;
 402
 403 public: // Not intended for application developers
 404   /// @cond internal
 405   /**
 406    * @brief This constructor is used by Layer::New() methods.
 407    *
 408    * @SINCE_1_0.0
 409    * @param[in] Layer A pointer to a newly allocated Dali resource
 410    */
 411   explicit DALI_INTERNAL Layer(Internal::Layer* Layer);
 412   /// @endcond
 413 };
 414
 415 /**
 416  * @}
 417  */
 418 } // namespace Dali
 419
 420 #endif // DALI_LAYER_H