* @brief Layers provide a mechanism for overlaying groups of actors on top of each other.
*
* When added to the stage, a layer can be ordered relative to other layers. The bottom
- * layer is at depth zero. The stage provides a default layer for it's children.
+ * layer is at depth zero. The stage provides a default layer for it's children (see Stage::GetRootLayer()).
*
* Layered actors inherit position etc. as normal, but are drawn in an order determined
* by the layers. The depth buffer is cleared before each layer is rendered unless depth
* test is disabled or there's no need for it based on the layers contents;
* actors in lower layers cannot obscure actors in higher layers.
*
+ * A layer has either LAYER_2D or LAYER_3D mode. LAYER_2D has better performance,
+ * the depth test is disabled, and a child actor hides its parent actor.
+ * LAYER_3D uses the depth test, thus a close actor hides a farther one.
+ * LAYER_2D is the default mode and recommended for general cases.
+ * See Layer::Behavior and SetBehavior() for more information.
+ *
+ * Layer is a type of Actor, thus can have parent or children actors.
+ * A layer influences rendering of its all descendant actors,
+ * until another layer appears in the actor tree and manages its own subtree.
+ *
* If depth test is disabled, there is no performance overhead from clearing the depth buffer.
*
- * Actions
- * | %Action Name | %Layer method called |
- * |-----------------|----------------------|
- * | raise | @ref Raise() |
- * | lower | @ref Lower() |
- * | raise-to-top | @ref RaiseToTop() |
- * | lower-to-bottom | @ref LowerToBottom() |
* @since_tizen 2.4
*/
class DALI_IMPORT_API Layer : public Actor
/**
* @brief An enumeration of properties belonging to the Layer class.
+ *
* Properties additional to Actor.
+ *
* @since_tizen 2.4
*/
struct Property
{
enum
{
- CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clipping-enable", type bool
- CLIPPING_BOX, ///< name "clipping-box", type Rect<int>
- BEHAVIOR, ///< name "behavior", type String
+ CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< type bool @since_tizen 2.4
+ CLIPPING_BOX, ///< type Rect<int> @since_tizen 2.4
+ BEHAVIOR, ///< type String @since_tizen 2.4
};
};
enum Behavior
{
/**
- * @brief Layer doesn't make use of the depth test.
+ * @brief Layer doesn't make use of the depth test (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 depth-index property of Renderers.
+ * When using this mode any ordering would be with respect to depth-index property of Actors.
+ *
+ * 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 not determined.
+ * If you have two overlapped actors, just make them parent-child, not siblings.
+ *
+ * @code
+ *
+ * Layer1 (parent)
+ * |
+ * A
+ * / \
+ * B C
+ * / \ \
+ * D E F
+ *
+ * @endcode
+ *
+ * @since_tizen 2.4
*/
LAYER_2D,
/**
* @brief Layer will use depth test and do several clears.
*
- * When using this mode depth depth test will be used. A depth clear will happen for each distinct
+ * When using this mode depth test will be used. A depth clear will happen for each distinct
* depth-index value in the layer, 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.
+ * Unlike LAYER_2D, parent-child relationship does not affect rendering order at all.
+ *
+ * @since_tizen 2.4
+ * @remarks This is an experimental feature. Using 2D UI components of DALi Toolkit
+ * in LAYER_3D mode has not been enoughly tested yet
+ * because they are orginally designed for 2D use cases.
+ * Simple controls such as Toolkit::Control or Toolkit::ImageView might not have any problem with LAYER_3D,
+ * but more complex one like Toolkit::PushButton, you might get unexpected rendered order in LAYER_3D.
+ * Although we'll support 2D controls in LAYER_3D soon, we recommend to use 2D controls with LAYER_2D only at this moment.
+ * Of course, controls rendered in 3D space, such as SpiralLayout of Toolkit::ItemView
+ * (see Toolkit::DefaultItemLayout::New), should be used with LAYER_3D.
*/
LAYER_3D,
};
- /*
- * TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first.
+ /**
+ * @brief TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first.
* For 2D layers, this value will be multiplied to the actor depth in the tree and added to the depth index
* to obtain the value which will be used for ordering
+ * @since_tizen 2.4
*/
enum TreeDepthMultiplier
{
* @brief The sort function type.
*
* @since_tizen 2.4
- * @param[in] position this is the actor translation from camera.
+ * @param[in] position This is the actor translation from camera.
*/
typedef float (*SortFunctionType)( const Vector3& position );
static Layer New();
/**
- * @brief Downcast an Object handle to Layer.
+ * @brief Downcast a handle to Layer handle.
*
* If handle points to a Layer the downcast produces valid
* handle. If not the returned handle is left uninitialized.
* @since_tizen 2.4
- * @param[in] handle to An object
- * @return handle to a Layer or an uninitialized handle
+ * @param[in] handle Handle to An object
+ * @return Handle to a Layer or an uninitialized handle
*/
static Layer DownCast( BaseHandle handle );
*
* @since_tizen 2.4
* @param [in] rhs The actor to copy.
+ * @return A reference to this
*/
Layer& operator=(const Layer& rhs);
*
* 0 is bottom most layer, higher number is on top
* @since_tizen 2.4
- * @return the current depth of the layer.
- * @pre layer is on the stage
+ * @return The current depth of the layer.
+ * @pre Layer is on the stage
* If layer is not added to the stage, returns 0.
*/
unsigned int GetDepth() const;
* @brief Increment the depth of the layer.
*
* @since_tizen 2.4
- * @pre layer is on the stage
+ * @pre Layer is on the stage
*/
void Raise();
* @brief Decrement the depth of the layer.
*
* @since_tizen 2.4
- * @pre layer is on the stage
+ * @pre Layer is on the stage
*/
void Lower();
*
* If the layer already is above target layer its depth is not changed
* If the layer was below target, its new depth will be immediately above target
- * Note! All layers between this layer and target get new depth values
* @since_tizen 2.4
- * @param target layer to get above of
- * @pre layer is on the stage
- * @pre target layer is on the stage
+ * @param target Layer to get above of
+ * @pre Layer is on the stage
+ * @pre Target layer is on the stage
+ * @note All layers between this layer and target get new depth values
*/
void RaiseAbove( Layer target );
*
* If the layer already is below the layer its depth is not changed
* If the layer was above target, its new depth will be immediately below target
- * Note! All layers between this layer and target get new depth values
* @since_tizen 2.4
- * @param target layer to get below of
- * @pre layer is on the stage
- * @pre target layer is on the stage
+ * @param target Layer to get below of
+ * @pre Layer is on the stage
+ * @pre Target layer is on the stage
+ * @note All layers between this layer and target get new depth values
*/
void LowerBelow( Layer target );
/**
* @brief Raises the layer to the top.
* @since_tizen 2.4
- * @pre layer is on the stage
+ * @pre Layer is on the stage
*/
void RaiseToTop();
* @brief Moves the layer directly above the given layer.
*
* After the call this layers depth will be immediately above target
- * Note! All layers between this layer and target get new depth values
* @since_tizen 2.4
- * @param target layer to get on top of
- * @pre layer is on the stage
- * @pre target layer is on the stage
+ * @param target Layer to get on top of
+ * @pre Layer is on the stage
+ * @pre Target layer is on the stage
+ * @note All layers between this layer and target get new depth values
*/
void MoveAbove( Layer target );
* @brief Moves the layer directly below the given layer.
*
* After the call this layers depth will be immediately below target
- * Note! All layers between this layer and target get new depth values
* @since_tizen 2.4
- * @param target layer to get below of
- * @pre layer is on the stage
- * @pre target layer is on the stage
+ * @param target Layer to get below of
+ * @pre Layer is on the stage
+ * @pre Target layer is on the stage
+ * @note All layers between this layer and target get new depth values
*/
void MoveBelow( Layer target );
* However, it's possible to disable the depth test by calling this method.
*
* @since_tizen 2.4
- * @param[in] disable \e true disables depth test. \e false sets the default behavior.
+ * @param[in] disable \e True disables depth test. \e false sets the default behavior.
*/
void SetDepthTestDisabled( bool disable );
* @brief Retrieves whether depth test is disabled.
*
* @since_tizen 2.4
- * @return \e true if depth test is disabled.
+ * @return \e True if depth test is disabled.
*/
bool IsDepthTestDisabled() const;
*
* @since_tizen 2.4
* @param[in] function The sort function pointer
- * @note If the sort function returns a low number, the actor the data applies to will be
+ * @note If the sort function returns a low number, the actor with the data will be
* drawn in front of an actor whose data yields a high value from the sort function.
*
* @note All child layers use the same sort function. If a child layer is added to this
* @brief Retrieves whether the layer consumes touch (including gestures).
*
* @since_tizen 2.4
- * @return true if consuming touch, false otherwise.
+ * @return True if consuming touch, false otherwise.
*/
bool IsTouchConsumed() const;
* @brief Retrieves whether the layer consumes hover.
*
* @since_tizen 2.4
- * @return true if consuming hover, false otherwise.
+ * @return True if consuming hover, false otherwise.
*/
bool IsHoverConsumed() const;
public: // Not intended for application developers
/**
- * @brief This constructor is used by Dali New() methods.
+ * @brief This constructor is used by Layer::New() methods.
*
* @since_tizen 2.4
* @param [in] Layer A pointer to a newly allocated Dali resource
projects / framework / graphics / dali.git / blobdiff