Merge branch 'devel/master (1.2.18)' into tizen

[platform/core/uifw/dali-core.git] / dali / public-api / actors / layer.h

diff --git a/dali/public-api/actors/layer.h b/dali/public-api/actors/layer.h
index 81b43a9..1480db4 100644 (file)
--- a/dali/public-api/actors/layer.h
+++ b/dali/public-api/actors/layer.h
@@ -1,8 +1,8 @@
-#ifndef __DALI_LAYER_H__
-#define __DALI_LAYER_H__
+#ifndef DALI_LAYER_H
+#define DALI_LAYER_H
 
 /*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -85,11 +85,16 @@ public:
    * @brief An enumeration of properties belonging to the Layer class.
    *
    * Properties additional to Actor.
-   *
    * @SINCE_1_0.0
    */
   struct Property
   {
+    /**
+     * @brief An enumeration of properties belonging to the Layer class.
+     *
+     * Properties additional to Actor.
+     * @SINCE_1_0.0
+     */
     enum
     {
       CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clippingEnable",   type bool @SINCE_1_0.0
@@ -107,15 +112,23 @@ public:
   enum Behavior
   {
     /**
-     * @brief Layer doesn't make use of the depth test (default mode).
+     * @DEPRECATED_1_1.45, use LAYER_UI instead
+     * @brief UI control rendering mode
+     * @SINCE_1_0.0
+     * @see LAYER_UI
+     */
+    LAYER_2D,
+
+    /**
+     * @brief UI control rendering mode (default mode).
      *
-     * This mode is expected to have better performance than the 3D mode.
-     * When using this mode any ordering would be with respect to tree level of each Actor.
+     * This mode is designed for UI controls. In this mode renderer order will be respective to tree hierarchy of Actors.
+     * This mode is expected to have better performance than LAYER_3D as renderers can be sorted more efficiently.
      *
-     * For the following actor tree of the Layer1 object, D and E hide B, B and C hides A,
-     * and F hides C, regardless of their Z positions.
-     * Rendering order between siblings, such as D & E or B & C, is determined based on the depth index.
-     * If you have two overlapped actors, just make them parent-child, not siblings.
+     * For the following actor tree the rendering order will be A first, then B & C and finally D,E,F regardless of their
+     * Z positions.
+     * Rendering order between siblings, such as D, E & F or B & C, is determined based on the renderers depth index.
+     * In UI we don't normally expect overlap. If you have two overlapped actors, make them parent-child to guarantee order of all renderers.
      *
      * @code
      *
@@ -129,9 +142,9 @@ public:
      *
      * @endcode
      *
-     * @SINCE_1_0.0
+     * @SINCE_1_1.45
      */
-    LAYER_2D,
+    LAYER_UI = LAYER_2D,
 
     /**
      * @brief Layer will use depth test.
@@ -141,15 +154,16 @@ public:
      * those layers regardless of their Z positions (see Layer::Raise() and Layer::Lower()).
      * Opaque renderers are drawn first and write to the depth buffer.
      * Then transparent renderers are drawn with depth test enabled but depth write switched off.
-     * Transparent renderers are drawn based on their distance from the camera (painter's algorithm).
+     * Transparent renderers are drawn based on their distance from the camera.
      * A renderers DEPTH_INDEX property is used to offset the distance to the camera when ordering transparent renderers.
      * This is useful if you want to define the draw order of two or more transparent renderers that are
      * equal distance from the camera.
-     * Unlike LAYER_2D, parent-child relationship does not affect rendering order at all.
+     * Unlike LAYER_UI, parent-child relationship does not affect rendering order at all.
      *
      * @SINCE_1_0.0
      */
-    LAYER_3D,
+    LAYER_3D
+
   };
 
   /**
@@ -351,7 +365,6 @@ public:
    * The contents of the layer will not be visible outside this box, when clipping is
    * enabled. The default clipping box is empty (0,0,0,0) which means everything is clipped.
    * You can only do rectangular clipping using this API in window coordinates.
-   * For other kinds of clipping, see Dali::Actor::SetDrawMode().
    * @SINCE_1_0.0
    * @param [in] x The X-coordinate of the top-left corner of the box
    * @param [in] y The Y-coordinate of the top-left corner of the box
@@ -461,6 +474,7 @@ public:
 
 public: // Not intended for application developers
 
+  /// @cond internal
   /**
    * @brief This constructor is used by Layer::New() methods.
    *
@@ -468,6 +482,7 @@ public: // Not intended for application developers
    * @param [in] Layer A pointer to a newly allocated Dali resource
    */
   explicit DALI_INTERNAL Layer(Internal::Layer* Layer);
+  /// @endcond
 };
 
 /**
@@ -475,4 +490,4 @@ public: // Not intended for application developers
  */
 } // namespace Dali
 
-#endif //__DALI_LAYER_H__
+#endif // DALI_LAYER_H