dali/integration-api/scene.h

   1 #ifndef DALI_SCENE_H
   2 #define DALI_SCENE_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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 // EXTERNAL INCLUDES
  22 #include <memory>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/object/handle.h>
  26 #include <dali/public-api/math/vector2.h>
  27 #include <dali/public-api/math/vector4.h>
  28 #include <dali/public-api/common/vector-wrapper.h>
  29
  30 namespace Dali
  31 {
  32
  33 class Actor;
  34 struct KeyEvent;
  35 class Layer;
  36 class RenderTaskList;
  37 class TouchData;
  38 struct WheelEvent;
  39
  40 namespace Internal DALI_INTERNAL
  41 {
  42   class Scene;
  43 }
  44
  45 namespace Integration
  46 {
  47
  48 struct Event;
  49
  50 /**
  51  * @DEPRECATED_1_5.19
  52  *
  53  * @brief
  54  *
  55  * Scene creates a "world" that can be bound to a surface for rendering.
  56  *
  57  */
  58 class DALI_CORE_API Scene : public BaseHandle
  59 {
  60 public:
  61   typedef Signal< void () > EventProcessingFinishedSignalType; ///< Event Processing finished signal type
  62   typedef Signal< void (const Dali::KeyEvent&) > KeyEventSignalType; ///< Key event signal type
  63   typedef Signal< bool (const Dali::KeyEvent&) > KeyEventGeneratedSignalType; ///< key event generated signal type
  64   typedef Signal< void (const Dali::TouchData&) > TouchSignalType; ///< Touch signal type
  65   typedef Signal< void (const Dali::WheelEvent&) > WheelEventSignalType; ///< Touched signal type
  66
  67   using FrameCallbackContainer = std::vector< std::pair< std::unique_ptr< CallbackBase >, int32_t > >;
  68
  69   /**
  70    * @DEPRECATED_1_5.19
  71    *
  72    * @brief Create an initialized Scene handle.
  73    *
  74    * @param[in] size The size of the set surface for this scene
  75    *
  76    * @return a handle to a newly allocated Dali resource.
  77    */
  78   static Scene New( Size size );
  79
  80   /**
  81    * @brief Downcast an Object handle to Scene handle.
  82    *
  83    * If handle points to a Scene object the downcast produces
  84    * valid handle. If not the returned handle is left uninitialized.
  85    * @param[in] handle to An object
  86    * @return handle to a Scene object or an uninitialized handle
  87    */
  88   static Scene DownCast( BaseHandle handle );
  89
  90   /**
  91    * @brief Create an uninitialized Scene handle.
  92    *
  93    * This can be initialized with Scene::New(). Calling member
  94    * functions with an uninitialized Dali::Object is not allowed.
  95    */
  96   Scene();
  97
  98   /**
  99    * @brief Destructor
 100    *
 101    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 102    */
 103   ~Scene();
 104
 105   /**
 106    * @brief This copy constructor is required for (smart) pointer semantics.
 107    *
 108    * @param [in] handle A reference to the copied handle
 109    */
 110   Scene(const Scene& handle);
 111
 112   /**
 113    * @brief This assignment operator is required for (smart) pointer semantics.
 114    *
 115    * @param [in] rhs  A reference to the copied handle
 116    * @return A reference to this
 117    */
 118   Scene& operator=(const Scene& rhs);
 119
 120   /**
 121    * @brief Adds a child Actor to the Scene.
 122    *
 123    * The child will be referenced.
 124    * @param[in] actor The child
 125    * @pre The actor has been initialized.
 126    * @pre The actor does not have a parent.
 127    */
 128   void Add(Actor actor);
 129
 130   /**
 131    * @brief Removes a child Actor from the Scene.
 132    *
 133    * The child will be unreferenced.
 134    * @param[in] actor The child
 135    * @pre The actor has been added to the stage.
 136    */
 137   void Remove(Actor actor);
 138
 139   /**
 140    * @brief Returns the size of the Scene in pixels as a Vector.
 141    *
 142    * The x component will be the width of the Scene in pixels.
 143    * The y component will be the height of the Scene in pixels.
 144    *
 145    * @return The size of the Scene as a Vector
 146    */
 147   Size GetSize() const;
 148
 149   /**
 150    * Sets horizontal and vertical pixels per inch value that is used by the display
 151    * @param[in] dpi Horizontal and vertical dpi value
 152    */
 153   void SetDpi( Vector2 dpi );
 154
 155   /**
 156    * @brief Retrieves the DPI of the display device to which the scene is connected.
 157    *
 158    * @return The horizontal and vertical DPI
 159    */
 160   Vector2 GetDpi() const;
 161
 162   /**
 163    * @brief Sets the background color.
 164    *
 165    * @param[in] color The new background color
 166    */
 167   void SetBackgroundColor( const Vector4& color );
 168
 169   /**
 170    * @brief Gets the background color of the render　surface.
 171    *
 172    * @return The background color
 173    */
 174   Vector4 GetBackgroundColor() const;
 175
 176   /**
 177    * @brief Retrieves the list of render-tasks.
 178    *
 179    * @return A valid handle to a RenderTaskList
 180    */
 181   Dali::RenderTaskList GetRenderTaskList() const;
 182
 183   /**
 184    * @brief Returns the Scene's Root Layer.
 185    *
 186    * @return The root layer
 187    */
 188   Layer GetRootLayer() const;
 189
 190   /**
 191    * @brief Queries the number of on-stage layers.
 192    *
 193    * Note that a default layer is always provided (count >= 1).
 194    * @return The number of layers
 195    */
 196   uint32_t GetLayerCount() const;
 197
 198   /**
 199    * @brief Retrieves the layer at a specified depth.
 200    *
 201    * @param[in] depth The depth
 202    * @return The layer found at the given depth
 203    * @pre Depth is less than layer count; see GetLayerCount().
 204    */
 205   Layer GetLayer( uint32_t depth ) const;
 206
 207   /**
 208    * @brief Informs the scene that the set surface has been resized.
 209    *
 210    * @param[in] width The new width of the set surface
 211    * @param[in] height The new height of the set surface
 212    * @param[in] orientation The orientation of the surface
 213    * @param[in] forceUpdate The flag to update force
 214    */
 215   void SurfaceResized( float width, float height, int orientation, bool forceUpdate );
 216
 217   /**
 218    * @brief Informs the scene that the surface has been replaced.
 219    */
 220   void SurfaceReplaced();
 221
 222   /**
 223    * @brief Discards this Scene from the Core.
 224    */
 225   void Discard();
 226
 227   /**
 228    * @brief Retrieve the Scene that the given actor belongs to.
 229    * @return The Scene.
 230    */
 231   static Integration::Scene Get( Actor actor );
 232
 233   /**
 234    * This function is called when an event is queued.
 235    * @param[in] event A event to queue.
 236    */
 237   void QueueEvent( const Integration::Event& event );
 238
 239   /**
 240    * This function is called by Core when events are processed.
 241    */
 242   void ProcessEvents();
 243
 244   /**
 245    * @brief Adds a callback that is called when the frame rendering is done by the graphics driver.
 246    *
 247    * @param[in] callback The function to call
 248    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 249    *
 250    * @note A callback of the following type may be used:
 251    * @code
 252    *   void MyFunction( int frameId );
 253    * @endcode
 254    * This callback will be deleted once it is called.
 255    *
 256    * @note Ownership of the callback is passed onto this class.
 257    */
 258   void AddFrameRenderedCallback( std::unique_ptr< CallbackBase > callback, int32_t frameId );
 259
 260   /**
 261    * @brief Adds a callback that is called when the frame is displayed on the display.
 262    *
 263    * @param[in] callback The function to call
 264    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 265    *
 266    * @note A callback of the following type may be used:
 267    * @code
 268    *   void MyFunction( int frameId );
 269    * @endcode
 270    * This callback will be deleted once it is called.
 271    *
 272    * @note Ownership of the callback is passed onto this class.
 273    */
 274   void AddFramePresentedCallback( std::unique_ptr< CallbackBase > callback, int32_t frameId );
 275
 276   /**
 277    * @brief Gets the callback list that is called when the frame rendering is done by the graphics driver.
 278    *
 279    * @param[out] callbacks The callback list
 280    *
 281    * @note This is called in the update thread.
 282    */
 283   void GetFrameRenderedCallback( FrameCallbackContainer& callbacks );
 284
 285   /**
 286    * @brief Gets the callback list that is called when the frame is displayed on the display.
 287    *
 288    * @param[out] callbacks The callback list
 289    *
 290    * @note This is called in the update thread.
 291    */
 292   void GetFramePresentedCallback( FrameCallbackContainer& callbacks );
 293
 294   /**
 295    * @brief This signal is emitted just after the event processing is finished.
 296    *
 297    * @return The signal to connect to
 298    */
 299   EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
 300
 301   /**
 302    * @brief This signal is emitted when key event is received.
 303    *
 304    * A callback of the following type may be connected:
 305    * @code
 306    *   void YourCallbackName(const KeyEvent& event);
 307    * @endcode
 308    * @return The signal to connect to
 309    */
 310   KeyEventSignalType& KeyEventSignal();
 311
 312   /**
 313    * @brief The user would connect to this signal to get a KeyEvent when KeyEvent is generated.
 314    *
 315    * If the control already consumed key event, KeyEventProcessor do not need to Emit keyEvent.
 316    * Therefore, KeyinputManager first checks whether KeyEvent is generated as KeyEventGeneratedSignal.
 317    * After that keyEventProcessor must invoke KeyEvent only if KeyEventGeneratedSignal () is not consumed.
 318    *
 319    * A callback of the following type may be connected:
 320    * @code
 321    *   bool YourCallbackName(const KeyEvent& event);
 322    * @endcode
 323    *
 324    * @return The return is true if KeyEvent is consumed, otherwise false.
 325    */
 326   KeyEventGeneratedSignalType& KeyEventGeneratedSignal();
 327
 328   /**
 329    * @brief This signal is emitted when the screen is touched and when the touch ends
 330    * (i.e. the down & up touch events only).
 331    *
 332    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 333    * then when the last finger is lifted.
 334    * An interrupted event will also be emitted (if it occurs).
 335    * A callback of the following type may be connected:
 336    * @code
 337    *   void YourCallbackName( TouchData event );
 338    * @endcode
 339    *
 340    * @return The touch signal to connect to
 341    * @note Motion events are not emitted.
 342    */
 343   TouchSignalType& TouchSignal();
 344
 345   /**
 346    * @brief This signal is emitted when wheel event is received.
 347    *
 348    * A callback of the following type may be connected:
 349    * @code
 350    *   void YourCallbackName(const WheelEvent& event);
 351    * @endcode
 352    * @return The signal to connect to
 353    */
 354   WheelEventSignalType& WheelEventSignal();
 355
 356 public: // Not intended for application developers
 357
 358   /**
 359    * @brief This constructor is used by Dali::New() methods.
 360    *
 361    * @param[in] scene A pointer to an internal Scene resource
 362    */
 363   explicit DALI_INTERNAL Scene(Internal::Scene* scene);
 364 };
 365
 366 } // namespace Integration
 367
 368 } // namespace Dali
 369
 370 #endif // DALI_SCENE_H