X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Factors%2Flayer.h;h=15683cff90cb0de8fcdf95aae529563f8ab55b19;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=1e7ad4a50702a772eda8a47faa2143d8a0d5d5e1;hpb=4805f154c85adcf71716d9aa6746b6ba1b44a19e;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/actors/layer.h b/dali/public-api/actors/layer.h index 1e7ad4a..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) 2015 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 @@ -38,35 +41,38 @@ class Layer; } /** - * @brief Rectangle describing area on screen that a layer can draw to + * @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 (see Stage::GetRootLayer()). + * 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 layers contents; - * actors in lower layers cannot obscure actors in higher layers. + * 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. + * 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. + * 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 | @@ -77,23 +83,28 @@ typedef Rect ClippingBox; * | 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 { 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 + CLIPPING_BOX, ///< name "clippingBox", type Rect @SINCE_1_0.0 BEHAVIOR, ///< name "behavior", type String @SINCE_1_0.0 }; }; @@ -107,15 +118,24 @@ 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 that can overlap. In this + * mode renderer order will be respective to the tree hierarchy 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. + * 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 * @@ -129,63 +149,72 @@ public: * * @endcode * - * @SINCE_1_0.0 + * 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_2D, + LAYER_UI = LAYER_2D, /** * @brief Layer will use depth test. * - * When using this mode 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 (painter's algorithm). - * 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. + * 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 - * @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, + LAYER_3D + }; /** - * @brief TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first. + * @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 + * @brief The sort function type. * * @SINCE_1_0.0 - * @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 ); /** - * @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 @@ -193,18 +222,18 @@ public: static Layer New(); /** - * @brief Downcast a handle to Layer handle. + * @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. + * 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 + * @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 @@ -212,35 +241,35 @@ public: ~Layer(); /** - * @brief Copy constructor + * @brief Copy constructor. * * @SINCE_1_0.0 - * @param [in] copy The actor to copy + * @param[in] copy The actor to copy */ Layer(const Layer& copy); /** - * @brief Assignment operator + * @brief Assignment operator. * * @SINCE_1_0.0 - * @param [in] rhs The actor to copy + * @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. + * 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. */ - unsigned int GetDepth() const; + uint32_t GetDepth() const; /** - * @brief Increment the depth of the layer. + * @brief Increments the depth of the layer. * * @SINCE_1_0.0 * @pre Layer is on the stage. @@ -248,7 +277,7 @@ public: void Raise(); /** - * @brief Decrement the depth of the layer. + * @brief Decrements the depth of the layer. * * @SINCE_1_0.0 * @pre Layer is on the stage. @@ -258,7 +287,7 @@ public: /** * @brief Ensures the layers depth is greater than the target layer. * - * If the layer already is above the target layer its depth is not changed. + * 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 @@ -271,7 +300,7 @@ public: /** * @brief Ensures the layers depth is less than the target layer. * - * If the layer already is below the target layer its depth is not changed. + * 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 @@ -298,7 +327,7 @@ public: /** * @brief Moves the layer directly above the given layer. * - * After the call this layers depth will be immediately above target. + * 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. @@ -310,7 +339,7 @@ public: /** * @brief Moves the layer directly below the given layer. * - * After the call this layers depth will be immediately below target. + * 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. @@ -320,7 +349,7 @@ public: void MoveBelow( Layer target ); /** - * @brief Set the behavior of the layer. + * @brief Sets the behavior of the layer. * * @SINCE_1_0.0 * @param[in] behavior The desired behavior @@ -328,7 +357,7 @@ public: void SetBehavior( Behavior behavior ); /** - * @brief Get the behavior of the layer. + * @brief Gets the behavior of the layer. * * @SINCE_1_0.0 * @return The behavior of the layer @@ -340,16 +369,16 @@ public: * * Clipping is initially disabled; see also SetClippingBox(). * @SINCE_1_0.0 - * @param [in] enabled True if clipping is enabled. + * @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. + * @brief Queries whether clipping is enabled for a layer. * @SINCE_1_0.0 - * @return True if clipping is enabled. + * @return True if clipping is enabled */ bool IsClipping() const; @@ -359,27 +388,26 @@ 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 - * @param [in] width The width of the box - * @param [in] height The height of the box + * @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). * @SINCE_1_0.0 - * @param [in] box The clipping box + * @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 @@ -395,7 +423,7 @@ public: * However, it's possible to disable the depth test by calling this method. * * @SINCE_1_0.0 - * @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 ); @@ -403,7 +431,7 @@ public: * @brief Retrieves whether depth test is disabled. * * @SINCE_1_0.0 - * @return \e True if depth test is disabled. + * @return \e True if depth test is disabled */ bool IsDepthTestDisabled() const; @@ -421,12 +449,12 @@ public: * @endcode * * @SINCE_1_0.0 - * @param[in] function The sort function pointer + * @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. * */ void SetSortFunction( SortFunctionType function ); @@ -437,7 +465,7 @@ public: * If set, any layers behind this layer will not be hit-test. * * @SINCE_1_0.0 - * @param[in] consume Whether the layer should consume touch (including gestures). + * @param[in] consume Whether the layer should consume touch (including gestures) */ void SetTouchConsumed( bool consume ); @@ -445,7 +473,7 @@ public: * @brief Retrieves whether the layer consumes touch (including gestures). * * @SINCE_1_0.0 - * @return True if consuming touch, false otherwise. + * @return @c True if consuming touch, @c false otherwise */ bool IsTouchConsumed() const; @@ -455,7 +483,7 @@ public: * If set, any layers behind this layer will not be hit-test. * * @SINCE_1_0.0 - * @param[in] consume Whether the layer should consume hover. + * @param[in] consume Whether the layer should consume hover */ void SetHoverConsumed( bool consume ); @@ -463,19 +491,21 @@ public: * @brief Retrieves whether the layer consumes hover. * * @SINCE_1_0.0 - * @return True if consuming hover, false otherwise. + * @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 Layer::New() methods. * * @SINCE_1_0.0 - * @param [in] Layer A pointer to a newly allocated Dali resource + * @param[in] Layer A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Layer(Internal::Layer* Layer); + /// @endcond }; /** @@ -483,4 +513,4 @@ public: // Not intended for application developers */ } // namespace Dali -#endif //__DALI_LAYER_H__ +#endif // DALI_LAYER_H