capi/dali/public-api/actors/layer.h

   1 #ifndef __DALI_LAYER_H__
   2 #define __DALI_LAYER_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_FRAMEWORK
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/object/ref-object.h>
  27 #include <dali/public-api/actors/actor.h>
  28 #include <dali/public-api/math/rect.h>
  29 #include <dali/public-api/math/vector3.h>
  30 #include <dali/public-api/images/frame-buffer-image.h>
  31
  32 namespace Dali DALI_IMPORT_API
  33 {
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37 class Layer;
  38 }
  39
  40 typedef Rect<int> ClippingBox;
  41
  42 /**
  43  * Layers provide a mechanism for overlaying groups of actors on-top of each other.
  44  *
  45  * When added to the stage, a layer can be ordered relative to other layers. The bottom
  46  * layer is at depth zero. The stage provides a default layer for it's children.
  47  *
  48  * Layered actors inherit position etc. as normal, but are drawn in an order determined
  49  * by the layers. The depth buffer is cleared before each layer is rendered unless depth
  50  * test is disabled or there's no need for it based on the layers contents;
  51  * actors in lower layers cannot obscure actors in higher layers.
  52  *
  53  * If depth test is disabled, there is no performance overhead from clearing the depth buffer.
  54  */
  55 class DALI_IMPORT_API Layer : public Actor
  56 {
  57 public:
  58
  59   // Default Properties additional to Actor
  60   static const Property::Index CLIPPING_ENABLE; ///< name "clipping-enable",  type BOOLEAN
  61   static const Property::Index CLIPPING_BOX;    ///< name "clipping-box",     type RECTANGLE
  62
  63   // Action Names
  64   static const char* const ACTION_RAISE;
  65   static const char* const ACTION_LOWER;
  66   static const char* const ACTION_RAISE_TO_TOP;
  67   static const char* const ACTION_LOWER_TO_BOTTOM;
  68
  69   /**
  70    * The sort function type
  71    *
  72    * The position value is the actor translation from camera.
  73    * The sortModifier is the user value that can be used to sort coplanar actors/nodes. This value is
  74    * the one set by calling RenderableActor::SetSortModifier().
  75    *
  76    * A high return value means that the actor will be positioned further away by the sort algorithm.
  77    * @see RenderableActor::SetSortModifier
  78    */
  79   typedef float (*SortFunctionType)(const Vector3& position, float sortModifier);
  80
  81   /**
  82    * Create an empty Layer handle. This can be initialised with Layer::New(...)
  83    */
  84   Layer();
  85
  86   /**
  87    * Create a Layer object
  88    * @return A handle to a newly allocated Layer
  89    */
  90   static Layer New();
  91
  92   /**
  93    * Downcast an Object handle to Layer. If handle points to a Layer the
  94    * downcast produces valid handle. If not the returned handle is left uninitialized.
  95    * @param[in] handle to An object
  96    * @return handle to a Layer or an uninitialized handle
  97    */
  98   static Layer DownCast( BaseHandle handle );
  99
 100   /**
 101    * Virtual destructor.
 102    * Dali::Object derived classes typically do not contain member data.
 103    */
 104   virtual ~Layer();
 105
 106   /**
 107    * @copydoc Dali::BaseHandle::operator=
 108    */
 109   using BaseHandle::operator=;
 110
 111   /**
 112    * Query the depth of the layer
 113    * 0 is bottom most layer, higher number is on top
 114    * @pre layer is on the stage
 115    * If layer is not added to the stage, returns 0.
 116    * @return the current depth of the layer.
 117    */
 118   unsigned int GetDepth() const;
 119
 120   /**
 121    * Increment the depth of the layer.
 122    * @pre layer is on the stage
 123    */
 124   void Raise();
 125
 126   /**
 127    * Decrement the depth of the layer.
 128    * @pre layer is on the stage
 129    */
 130   void Lower();
 131
 132   /**
 133    * Ensures the layers depth is greater than the target layer
 134    * If the layer already is above target layer its depth is not changed
 135    * If the layer was below target, its new depth will be immediately above target
 136    * Note! All layers between this layer and target get new depth values
 137    * @pre layer is on the stage
 138    * @pre target layer is on the stage
 139    * @param target layer to get above of
 140    */
 141   void RaiseAbove( Layer target );
 142
 143   /**
 144    * Ensures the layers depth is less than the target layer
 145    * If the layer already is below the layer its depth is not changed
 146    * If the layer was above target, its new depth will be immediately below target
 147    * Note! All layers between this layer and target get new depth values
 148    * @pre layer is on the stage
 149    * @pre target layer is on the stage
 150    * @param target layer to get below of
 151    */
 152   void LowerBelow( Layer target );
 153
 154   /**
 155    * Raises the layer to the top.
 156    * @pre layer is on the stage
 157    */
 158   void RaiseToTop();
 159
 160   /**
 161    * Lowers the layer to the bottom.
 162    * @pre layer is on the stage
 163    */
 164   void LowerToBottom();
 165
 166   /**
 167    * Moves the layer directly above the given layer
 168    * After the call this layers depth will be immediately above target
 169    * Note! All layers between this layer and target get new depth values
 170    * @pre layer is on the stage
 171    * @pre target layer is on the stage
 172    * @param target layer to get on top of
 173    */
 174   void MoveAbove( Layer target );
 175
 176   /**
 177    * Moves the layer directly below the given layer
 178    * After the call this layers depth will be immediately below target
 179    * Note! All layers between this layer and target get new depth values
 180    * @pre layer is on the stage
 181    * @pre target layer is on the stage
 182    * @param target layer to get below of
 183    */
 184   void MoveBelow( Layer target );
 185
 186   /**
 187    * Sets whether clipping is enabled for a layer.
 188    * Clipping is initially disabled; see also SetClippingBox().
 189    * @param [in] enabled True if clipping is enabled.
 190    */
 191   void SetClipping(bool enabled);
 192
 193   /**
 194    * Query whether clipping is enabled for a layer.
 195    * @return True if clipping is enabled.
 196    */
 197   bool IsClipping() const;
 198
 199   /**
 200    * Sets the clipping box of a layer, in window coordinates.
 201    * The contents of the layer will not be visible outside this box, when clipping is
 202    * enabled. The default clipping box is empty (0,0,0,0).
 203    * @param [in] x The X-coordinate of the lower-left corner.
 204    * @param [in] y The Y-coordinate of the lower-left corner.
 205    * @param [in] width  The width of the box.
 206    * @param [in] height The height of the box.
 207    */
 208   void SetClippingBox(int x, int y, int width, int height);
 209
 210   /**
 211    * Sets the clipping box of a layer, in window coordinates.
 212    * The contents of the layer will not be visible outside this box, when clipping is
 213    * enabled. The default clipping box is empty (0,0,0,0).
 214    * @param [in] box The clipping box
 215    */
 216   void SetClippingBox(ClippingBox box);
 217
 218   /**
 219    * Retrieves the clipping box of a layer, in window coordinates.
 220    * @return The clipping box
 221    */
 222   ClippingBox GetClippingBox() const;
 223
 224   // Depth test
 225
 226   /**
 227    * Whether to disable the depth test.
 228    *
 229    * 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.
 230    * However, it's possible to disable the depth test by calling this method.
 231    *
 232    * @param[in] disable \e true disables depth test. \e false sets the default behaviour.
 233    */
 234   void SetDepthTestDisabled( bool disable );
 235
 236   /**
 237    * Retrieves whether depth test is disabled.
 238    *
 239    * @return \e true if depth test is disabled.
 240    */
 241   bool IsDepthTestDisabled() const;
 242
 243   // Sorting
 244
 245   /**
 246    * This sort function sorts according to the sum of the displacement (x,y,z) from camera.
 247    */
 248   static float SumOfDisplacements( const Vector3& position, float sortModifier )
 249   {
 250     return fabsf(position.x) + fabsf(position.y) + fabsf(position.z) + sortModifier;
 251   }
 252
 253   /**
 254    * This sort function sorts according to the distance from camera.
 255    *
 256    * Distance = Length of position vector, + modifier (to help order transparent objects that are very close)
 257    */
 258   static float DistanceFromOrigin(const Vector3& position, float sortModifier)
 259   {
 260     return position.Length() + sortModifier;
 261   }
 262
 263   /**
 264    * This sort function sorts actors according to the Z-value in the camera coordinate system.
 265    *
 266    * This is useful for 2D user interfaces.
 267    *
 268    * This is the default sorting function.
 269    *
 270    * We return a negative z value as in our translation, a low z means that it should
 271    * be sorted further away and a high z means that it should be closer.
 272    */
 273   static float ZValue(const Vector3& position, float sortModifier)
 274   {
 275     return -position.z + sortModifier;
 276   }
 277
 278   /**
 279    * This allows the user to specify the sort function that the layer should use.
 280    * The sort function is used to determine the order in which the actors are drawn
 281    * and input is processed on the actors in the layer.
 282    *
 283    * A function of the following type should be used:
 284    * @code
 285    *  float YourSortFunction(const Vector3& position, float sortModifier);
 286    * @endcode
 287    *
 288    * @note If the sort function returns a low number, the actor the data applies to will be
 289    * drawn in front of an actor whose data yields a high value from the sort function.
 290    *
 291    * @note All child layers use the same sort function.  If a child layer is added to this
 292    * layer then the sort function used by the child layer will also be the same.
 293    *
 294    * @param[in]  function  The sort function pointer
 295   */
 296   void SetSortFunction( SortFunctionType function );
 297
 298 public: // Not intended for application developers
 299
 300   /**
 301    * This constructor is used by Dali New() methods
 302    * @param [in] Layer A pointer to a newly allocated Dali resource
 303    */
 304   explicit DALI_INTERNAL Layer(Internal::Layer* Layer);
 305 };
 306
 307 } // namespace Dali
 308
 309 /**
 310  * @}
 311  */
 312 #endif //__DALI_LAYER_H__