X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Factors%2Flayer.h;h=15683cff90cb0de8fcdf95aae529563f8ab55b19;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=6daef8f58f2e6478b7a94e8ffee82d824cc6f324;hpb=933b6c4b896da1ae0fd81e8e7d12aba75b6b8c4c;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/actors/layer.h b/dali/public-api/actors/layer.h index 6daef8f..15683cf 100644 --- 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) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2018 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. @@ -18,6 +18,9 @@ * */ +// EXTERNAL INCLUDES +#include // uint32_t + // INTERNAL INCLUDES #include #include @@ -27,6 +30,10 @@ namespace Dali { +/** + * @addtogroup dali_core_actors + * @{ + */ namespace Internal DALI_INTERNAL { @@ -36,200 +43,342 @@ class Layer; /** * @brief Rectangle describing area on screen that a layer can draw to. * + * @SINCE_1_0.0 * @see Dali::Layer::SetClippingBox() */ -typedef Rect ClippingBox; +typedef Rect ClippingBox; /** * @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. + * 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 (see Stage::GetRootLayer()). + * + * Layered actors inherit position etc. as normal, but are drawn in an order + * determined by the layers. In case of LAYER_3D, 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 layer's 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. * - * 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. + * 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. + * 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() | + * | raiseToTop | @ref RaiseToTop() | + * | lowerToBottom | @ref LowerToBottom() | + * @SINCE_1_0.0 */ -class DALI_IMPORT_API Layer : public Actor +class DALI_CORE_API Layer : public Actor { public: /** - * @brief An enumeration of properties belonging to the Layer class. + * @brief Enumeration for the instance of properties belonging to the Layer class. + * * Properties additional to Actor. + * @SINCE_1_0.0 */ struct Property { + /** + * @brief Enumeration for the instance of properties belonging to the Layer class. + * + * Properties additional to Actor. + * @SINCE_1_0.0 + */ enum { - ClippingEnable = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clipping-enable", type Boolean - ClippingBox, ///< name "clipping-box", type Rectangle + CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clippingEnable", type bool @SINCE_1_0.0 + CLIPPING_BOX, ///< name "clippingBox", type Rect @SINCE_1_0.0 + BEHAVIOR, ///< name "behavior", type String @SINCE_1_0.0 }; }; /** - * @brief The sort function type. + * @brief Enumeration for the behavior of the layer. * - * The position value is the actor translation from camera. - * The sortModifier is the user value that can be used to sort coplanar actors/nodes. This value is - * the one set by calling RenderableActor::SetSortModifier(). + * Check each value to see how it affects the layer. + * @SINCE_1_0.0 + */ + enum Behavior + { + /** + * @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 designed for UI controls that can overlap. In this + * mode renderer order will be respective to the tree hierarchy of + * Actors. + * + * The rendering order is depth first, so for the following actor tree, + * A will be drawn first, then B, D, E, then C, F. This ensures that + * overlapping actors are drawn as expected (whereas, with breadth first + * traversal, the actors would interleave). + * + * @code + * + * Layer1 (parent) + * | + * A + * / \ + * B C + * / \ \ + * D E F + * + * @endcode + * + * To change the order of sibling actors, use the Actor::Raise and + * Actor::Lower APIs. Within an actor, the Renderer depth index dictates + * the order the renderers are drawn. + * + * @SINCE_1_1.45 + */ + LAYER_UI = LAYER_2D, + + /** + * @brief Layer will use depth test. + * + * This mode is designed for a 3 dimensional scene where actors in front + * of other actors will obscure them, i.e. the actors are sorted by the + * distance from the camera. + * + * When using this mode, a depth test will be used. A depth clear will + * happen for each layer, which means actors in a layer "above" other + * layers will be rendered in front of actors in 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. A renderer's 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_UI, parent-child relationship does not affect rendering order at + * all. + * + * @SINCE_1_0.0 + */ + LAYER_3D + + }; + + /** + * @DEPRECATED_1_2.26. Not intended for application use. + * + * @brief Enumeration for TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first. + * @SINCE_1_0.0 + */ + enum TreeDepthMultiplier + { + TREE_DEPTH_MULTIPLIER = 10000, + }; + + /** + * @brief The sort function type. * - * A high return value means that the actor will be positioned further away by the sort algorithm. - * @see RenderableActor::SetSortModifier + * @SINCE_1_0.0 + * @param[in] position This is the actor translation from camera */ - typedef float (*SortFunctionType)(const Vector3& position, float sortModifier); + typedef float (*SortFunctionType)( const Vector3& position ); /** - * @brief Create an empty Layer handle. + * @brief Creates an empty Layer handle. * - * This can be initialised with Layer::New(...) + * This can be initialized with Layer::New(...). + * @SINCE_1_0.0 */ Layer(); /** - * @brief Create a Layer object. + * @brief Creates a Layer object. * + * @SINCE_1_0.0 * @return A handle to a newly allocated Layer */ static Layer New(); /** - * @brief Downcast an Object handle to Layer. + * @brief Downcasts a handle to Layer handle. * - * If handle points to a Layer the downcast produces valid - * handle. If not the returned handle is left uninitialized. - * @param[in] handle to An object - * @return handle to a Layer or an uninitialized handle + * If handle points to a Layer, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return Handle to a Layer or an uninitialized handle */ static Layer DownCast( BaseHandle handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Layer(); /** - * @brief Copy constructor + * @brief Copy constructor. * - * @param [in] copy The actor to copy. + * @SINCE_1_0.0 + * @param[in] copy The actor to copy */ Layer(const Layer& copy); /** - * @brief Assignment operator + * @brief Assignment operator. * - * @param [in] rhs The actor to copy. + * @SINCE_1_0.0 + * @param[in] rhs The actor to copy + * @return A reference to this */ Layer& operator=(const Layer& rhs); /** - * @brief Query the depth of the layer + * @brief Queries the depth of the layer. * - * 0 is bottom most layer, higher number is on top - * @pre layer is on the stage + * 0 is the bottom most layer, higher number is on top. + * @SINCE_1_0.0 + * @return The current depth of the layer + * @pre Layer is on the stage. * If layer is not added to the stage, returns 0. - * @return the current depth of the layer. */ - unsigned int GetDepth() const; + uint32_t GetDepth() const; /** - * @brief Increment the depth of the layer. + * @brief Increments the depth of the layer. * - * @pre layer is on the stage + * @SINCE_1_0.0 + * @pre Layer is on the stage. */ void Raise(); /** - * @brief Decrement the depth of the layer. + * @brief Decrements the depth of the layer. * - * @pre layer is on the stage + * @SINCE_1_0.0 + * @pre Layer is on the stage. */ void Lower(); /** * @brief Ensures the layers depth is greater than the target layer. * - * 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 - * @pre layer is on the stage - * @pre target layer is on the stage - * @param target layer to get above of + * If the layer already is above the target layer, its depth is not changed. + * If the layer was below target, its new depth will be immediately above target. + * @SINCE_1_0.0 + * @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 ); /** * @brief Ensures the layers depth is less than the target layer. * - * 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 - * @pre layer is on the stage - * @pre target layer is on the stage - * @param target layer to get below of + * If the layer already is below the target layer, its depth is not changed. + * If the layer was above target, its new depth will be immediately below target. + * @SINCE_1_0.0 + * @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. - * @pre layer is on the stage + * @SINCE_1_0.0 + * @pre Layer is on the stage. */ void RaiseToTop(); /** * @brief Lowers the layer to the bottom. - * @pre layer is on the stage + * @SINCE_1_0.0 + * @pre layer is on the stage. */ void LowerToBottom(); /** * @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 - * @pre layer is on the stage - * @pre target layer is on the stage - * @param target layer to get on top of + * After the call, this layers depth will be immediately above target. + * @SINCE_1_0.0 + * @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 - * @pre layer is on the stage - * @pre target layer is on the stage - * @param target layer to get below of + * After the call, this layers depth will be immediately below target. + * @SINCE_1_0.0 + * @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 ); /** + * @brief Sets the behavior of the layer. + * + * @SINCE_1_0.0 + * @param[in] behavior The desired behavior + */ + void SetBehavior( Behavior behavior ); + + /** + * @brief Gets the behavior of the layer. + * + * @SINCE_1_0.0 + * @return The behavior of the layer + */ + Behavior GetBehavior() const; + + /** * @brief Sets whether clipping is enabled for a layer. * * Clipping is initially disabled; see also SetClippingBox(). - * @param [in] enabled True if clipping is enabled. + * @SINCE_1_0.0 + * @param[in] enabled True if clipping is enabled * - * @note When clipping is enabled, the default clipping box is empty (0,0,0,0) which means everything is clipped. + * @note When clipping is enabled, the default clipping box is empty (0,0,0,0), which means everything is clipped. */ void SetClipping(bool enabled); /** - * @brief Query whether clipping is enabled for a layer. - * @return True if clipping is enabled. + * @brief Queries whether clipping is enabled for a layer. + * @SINCE_1_0.0 + * @return True if clipping is enabled */ bool IsClipping() const; @@ -239,26 +388,28 @@ 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(). - * @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. - * @param [in] width The width of the box. - * @param [in] height The height of the box. + * @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 + * @param[in] width The width of the box + * @param[in] height The height of the box */ - void SetClippingBox(int x, int y, int width, int height); + void SetClippingBox(int32_t x, int32_t y, int32_t width, int32_t height); /** - * @brief Sets the clipping box of a layer, in window coordinates. + * @brief Sets the clipping box of a layer in window coordinates. * - * The contents of the layer will not be visible outside this box, when clipping is + * 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). - * @param [in] box The clipping box + * @SINCE_1_0.0 + * @param[in] box The clipping box */ void SetClippingBox(ClippingBox box); /** - * @brief Retrieves the clipping box of a layer, in window coordinates. + * @brief Retrieves the clipping box of a layer in window coordinates. * + * @SINCE_1_0.0 * @return The clipping box */ ClippingBox GetClippingBox() const; @@ -268,38 +419,25 @@ public: /** * @brief Whether to disable the depth test. * - * 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. + * 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 in LAYER_3D mode. * However, it's possible to disable the depth test by calling this method. * - * @param[in] disable \e true disables depth test. \e false sets the default behaviour. + * @SINCE_1_0.0 + * @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. * - * @return \e true if depth test is disabled. + * @SINCE_1_0.0 + * @return \e True if depth test is disabled */ bool IsDepthTestDisabled() const; // Sorting /** - * @brief This sort function sorts translucent actors according to the Z-value in view space. - * - * This is useful for 2D user interfaces. - * - * This is the default sorting function. - * - * We return a negative z value as in our translation, a low z means that it should - * be sorted further away and a high z means that it should be closer. - * @param[in] position position of actor in view space - * @param[in] sortModifier additional sort modifer - * @return depth - */ - static float ZValue(const Vector3& position, float sortModifier); - - /** * @brief This allows the user to specify the sort function that the layer should use. * * The sort function is used to determine the order in which the actors are drawn @@ -307,16 +445,17 @@ public: * * A function of the following type should be used: * @code - * float YourSortFunction(const Vector3& position, float sortModifier); + * float YourSortFunction(const Vector3& position); * @endcode * - * @note If the sort function returns a low number, the actor the data applies to will be + * @SINCE_1_0.0 + * @param[in] function The sort function pointer + * @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 - * layer then the sort function used by the child layer will also be the same. + * @note All child layers use the same sort function. If a child layer is added to this + * layer, then the sort function used by the child layer will also be the same. * - * @param[in] function The sort function pointer */ void SetSortFunction( SortFunctionType function ); @@ -325,14 +464,16 @@ public: * * If set, any layers behind this layer will not be hit-test. * - * @param[in] consume Whether the layer should consume touch (including gestures). + * @SINCE_1_0.0 + * @param[in] consume Whether the layer should consume touch (including gestures) */ void SetTouchConsumed( bool consume ); /** * @brief Retrieves whether the layer consumes touch (including gestures). * - * @return true if consuming touch, false otherwise. + * @SINCE_1_0.0 + * @return @c True if consuming touch, @c false otherwise */ bool IsTouchConsumed() const; @@ -341,27 +482,35 @@ public: * * If set, any layers behind this layer will not be hit-test. * - * @param[in] consume Whether the layer should consume hover. + * @SINCE_1_0.0 + * @param[in] consume Whether the layer should consume hover */ void SetHoverConsumed( bool consume ); /** * @brief Retrieves whether the layer consumes hover. * - * @return true if consuming hover, false otherwise. + * @SINCE_1_0.0 + * @return @c True if consuming hover, @c false otherwise */ bool IsHoverConsumed() const; public: // Not intended for application developers + /// @cond internal /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by Layer::New() methods. * - * @param [in] Layer A pointer to a newly allocated Dali resource + * @SINCE_1_0.0 + * @param[in] Layer A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Layer(Internal::Layer* Layer); + /// @endcond }; +/** + * @} + */ } // namespace Dali -#endif //__DALI_LAYER_H__ +#endif // DALI_LAYER_H