dali/public-api/actors/layer.h

   1 #ifndef __DALI_LAYER_H__
   2 #define __DALI_LAYER_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/ref-object.h>
  23 #include <dali/public-api/actors/actor.h>
  24 #include <dali/public-api/math/rect.h>
  25 #include <dali/public-api/math/vector3.h>
  26 #include <dali/public-api/images/frame-buffer-image.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class Layer;
  34 }
  35
  36 /**
  37  * @brief Rectangle describing area on screen that a layer can draw to.
  38  *
  39  * @see Dali::Layer::SetClippingBox()
  40  */
  41 typedef Rect<int> ClippingBox;
  42
  43 /**
  44  * @brief Layers provide a mechanism for overlaying groups of actors on top of each other.
  45  *
  46  * When added to the stage, a layer can be ordered relative to other layers. The bottom
  47  * layer is at depth zero. The stage provides a default layer for it's children.
  48  *
  49  * Layered actors inherit position etc. as normal, but are drawn in an order determined
  50  * by the layers. The depth buffer is cleared before each layer is rendered unless depth
  51  * test is disabled or there's no need for it based on the layers contents;
  52  * actors in lower layers cannot obscure actors in higher layers.
  53  *
  54  * If depth test is disabled, there is no performance overhead from clearing the depth buffer.
  55  *
  56  * Actions
  57  * | %Action Name    | %Layer method called |
  58  * |-----------------|----------------------|
  59  * | raise           | @ref Raise()         |
  60  * | lower           | @ref Lower()         |
  61  * | raise-to-top    | @ref RaiseToTop()    |
  62  * | lower-to-bottom | @ref LowerToBottom() |
  63  */
  64 class DALI_IMPORT_API Layer : public Actor
  65 {
  66 public:
  67
  68   /**
  69    * @brief An enumeration of properties belonging to the Layer class.
  70    * Properties additional to Actor.
  71    */
  72   struct Property
  73   {
  74     enum
  75     {
  76       CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clipping-enable",  type bool
  77       CLIPPING_BOX,                                                 ///< name "clipping-box",     type Rect<int>
  78       BEHAVIOR,                                                     ///< name "behavior",         type String
  79     };
  80   };
  81
  82   /**
  83    * @brief Enumeration for the behavior of the layer.
  84    *
  85    * Check each value to see how it affects the layer.
  86    */
  87   enum Behavior
  88   {
  89     /**
  90      * @brief Layer doesn't make use of the depth test.
  91      *
  92      * This mode is expected to have better performance than the 3D mode.
  93      * When using this mode any ordering would be with respect to depth-index property of Renderers.
  94      */
  95     LAYER_2D,
  96
  97     /**
  98      * @brief Layer will use depth test and do several clears.
  99      *
 100      * When using this mode depth depth test will be used. A depth clear will happen for each distinct
 101      * depth-index value in the layer, opaque renderers are drawn first and write to the depth buffer.
 102      * Then transparent renderers are drawn with depth test enabled but depth write switched off.
 103      */
 104     LAYER_3D,
 105   };
 106
 107   /**
 108    * @brief The sort function type.
 109    *
 110    * @param[in] position this is the actor translation from camera.
 111    */
 112   typedef float (*SortFunctionType)( const Vector3& position );
 113
 114   /**
 115    * @brief Create an empty Layer handle.
 116    *
 117    * This can be initialised with Layer::New(...)
 118    */
 119   Layer();
 120
 121   /**
 122    * @brief Create a Layer object.
 123    *
 124    * @return A handle to a newly allocated Layer
 125    */
 126   static Layer New();
 127
 128   /**
 129    * @brief Downcast an Object handle to Layer.
 130    *
 131    * If handle points to a Layer the downcast produces valid
 132    * handle. If not the returned handle is left uninitialized.
 133    * @param[in] handle to An object
 134    * @return handle to a Layer or an uninitialized handle
 135    */
 136   static Layer DownCast( BaseHandle handle );
 137
 138   /**
 139    * @brief Destructor
 140    *
 141    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 142    */
 143   ~Layer();
 144
 145   /**
 146    * @brief Copy constructor
 147    *
 148    * @param [in] copy The actor to copy.
 149    */
 150   Layer(const Layer& copy);
 151
 152   /**
 153    * @brief Assignment operator
 154    *
 155    * @param [in] rhs The actor to copy.
 156    */
 157   Layer& operator=(const Layer& rhs);
 158
 159   /**
 160    * @brief Query the depth of the layer
 161    *
 162    * 0 is bottom most layer, higher number is on top
 163    * @pre layer is on the stage
 164    * If layer is not added to the stage, returns 0.
 165    * @return the current depth of the layer.
 166    */
 167   unsigned int GetDepth() const;
 168
 169   /**
 170    * @brief Increment the depth of the layer.
 171    *
 172    * @pre layer is on the stage
 173    */
 174   void Raise();
 175
 176   /**
 177    * @brief Decrement the depth of the layer.
 178    *
 179    * @pre layer is on the stage
 180    */
 181   void Lower();
 182
 183   /**
 184    * @brief Ensures the layers depth is greater than the target layer.
 185    *
 186    * If the layer already is above target layer its depth is not changed
 187    * If the layer was below target, its new depth will be immediately above target
 188    * Note! All layers between this layer and target get new depth values
 189    * @pre layer is on the stage
 190    * @pre target layer is on the stage
 191    * @param target layer to get above of
 192    */
 193   void RaiseAbove( Layer target );
 194
 195   /**
 196    * @brief Ensures the layers depth is less than the target layer.
 197    *
 198    * If the layer already is below the layer its depth is not changed
 199    * If the layer was above target, its new depth will be immediately below target
 200    * Note! All layers between this layer and target get new depth values
 201    * @pre layer is on the stage
 202    * @pre target layer is on the stage
 203    * @param target layer to get below of
 204    */
 205   void LowerBelow( Layer target );
 206
 207   /**
 208    * @brief Raises the layer to the top.
 209    * @pre layer is on the stage
 210    */
 211   void RaiseToTop();
 212
 213   /**
 214    * @brief Lowers the layer to the bottom.
 215    * @pre layer is on the stage
 216    */
 217   void LowerToBottom();
 218
 219   /**
 220    * @brief Moves the layer directly above the given layer.
 221    *
 222    * After the call this layers depth will be immediately above target
 223    * Note! All layers between this layer and target get new depth values
 224    * @pre layer is on the stage
 225    * @pre target layer is on the stage
 226    * @param target layer to get on top of
 227    */
 228   void MoveAbove( Layer target );
 229
 230   /**
 231    * @brief Moves the layer directly below the given layer.
 232    *
 233    * After the call this layers depth will be immediately below target
 234    * Note! All layers between this layer and target get new depth values
 235    * @pre layer is on the stage
 236    * @pre target layer is on the stage
 237    * @param target layer to get below of
 238    */
 239   void MoveBelow( Layer target );
 240
 241   /**
 242    * @brief Set the behavior of the layer
 243    *
 244    * @param[in] behavior The desired behavior
 245    */
 246   void SetBehavior( Behavior behavior );
 247
 248   /**
 249    * @brief Get the behavior of the layer
 250    *
 251    * @return The behavior of the layer
 252    */
 253   Behavior GetBehavior() const;
 254
 255   /**
 256    * @brief Sets whether clipping is enabled for a layer.
 257    *
 258    * Clipping is initially disabled; see also SetClippingBox().
 259    * @param [in] enabled True if clipping is enabled.
 260    *
 261    * @note When clipping is enabled, the default clipping box is empty (0,0,0,0) which means everything is clipped.
 262    */
 263   void SetClipping(bool enabled);
 264
 265   /**
 266    * @brief Query whether clipping is enabled for a layer.
 267    * @return True if clipping is enabled.
 268    */
 269   bool IsClipping() const;
 270
 271   /**
 272    * @brief Sets the clipping box of a layer, in window coordinates.
 273    *
 274    * The contents of the layer will not be visible outside this box, when clipping is
 275    * enabled. The default clipping box is empty (0,0,0,0) which means everything is clipped.
 276    * You can only do rectangular clipping using this API in window coordinates.
 277    * For other kinds of clipping, @see Dali::Actor::SetDrawMode().
 278    * @param [in] x The X-coordinate of the top-left corner of the box.
 279    * @param [in] y The Y-coordinate of the top-left corner of the box.
 280    * @param [in] width  The width of the box.
 281    * @param [in] height The height of the box.
 282    */
 283   void SetClippingBox(int x, int y, int width, int height);
 284
 285   /**
 286    * @brief Sets the clipping box of a layer, in window coordinates.
 287    *
 288    * The contents of the layer will not be visible outside this box, when clipping is
 289    * enabled. The default clipping box is empty (0,0,0,0).
 290    * @param [in] box The clipping box
 291    */
 292   void SetClippingBox(ClippingBox box);
 293
 294   /**
 295    * @brief Retrieves the clipping box of a layer, in window coordinates.
 296    *
 297    * @return The clipping box
 298    */
 299   ClippingBox GetClippingBox() const;
 300
 301   // Depth test
 302
 303   /**
 304    * @brief Whether to disable the depth test.
 305    *
 306    * By default a layer enables depth test if there is more than one opaque actor or if there is one opaque actor and one, or more, transparent actors.
 307    * However, it's possible to disable the depth test by calling this method.
 308    *
 309    * @param[in] disable \e true disables depth test. \e false sets the default behavior.
 310    */
 311   void SetDepthTestDisabled( bool disable );
 312
 313   /**
 314    * @brief Retrieves whether depth test is disabled.
 315    *
 316    * @return \e true if depth test is disabled.
 317    */
 318   bool IsDepthTestDisabled() const;
 319
 320   // Sorting
 321
 322   /**
 323    * @brief This allows the user to specify the sort function that the layer should use.
 324    *
 325    * The sort function is used to determine the order in which the actors are drawn
 326    * and input is processed on the actors in the layer.
 327    *
 328    * A function of the following type should be used:
 329    * @code
 330    *  float YourSortFunction(const Vector3& position);
 331    * @endcode
 332    *
 333    * @note If the sort function returns a low number, the actor the data applies to will be
 334    * drawn in front of an actor whose data yields a high value from the sort function.
 335    *
 336    * @note All child layers use the same sort function.  If a child layer is added to this
 337    * layer then the sort function used by the child layer will also be the same.
 338    *
 339    * @param[in]  function  The sort function pointer
 340   */
 341   void SetSortFunction( SortFunctionType function );
 342
 343   /**
 344    * @brief This allows the user to specify whether this layer should consume touch (including gestures).
 345    *
 346    * If set, any layers behind this layer will not be hit-test.
 347    *
 348    * @param[in]  consume  Whether the layer should consume touch (including gestures).
 349    */
 350   void SetTouchConsumed( bool consume );
 351
 352   /**
 353    * @brief Retrieves whether the layer consumes touch (including gestures).
 354    *
 355    * @return true if consuming touch, false otherwise.
 356    */
 357   bool IsTouchConsumed() const;
 358
 359   /**
 360    * @brief This allows the user to specify whether this layer should consume hover.
 361    *
 362    * If set, any layers behind this layer will not be hit-test.
 363    *
 364    * @param[in]  consume  Whether the layer should consume hover.
 365    */
 366   void SetHoverConsumed( bool consume );
 367
 368   /**
 369    * @brief Retrieves whether the layer consumes hover.
 370    *
 371    * @return true if consuming hover, false otherwise.
 372    */
 373   bool IsHoverConsumed() const;
 374
 375 public: // Not intended for application developers
 376
 377   /**
 378    * @brief This constructor is used by Dali New() methods.
 379    *
 380    * @param [in] Layer A pointer to a newly allocated Dali resource
 381    */
 382   explicit DALI_INTERNAL Layer(Internal::Layer* Layer);
 383 };
 384
 385 } // namespace Dali
 386
 387 #endif //__DALI_LAYER_H__