dali/integration-api/scene.h

   1 #ifndef DALI_SCENE_H
   2 #define DALI_SCENE_H
   3
   4 /*
   5  * Copyright (c) 2021 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/common/vector-wrapper.h>
  26 #include <dali/public-api/math/vector2.h>
  27 #include <dali/public-api/math/vector4.h>
  28 #include <dali/public-api/object/handle.h>
  29
  30 namespace Dali
  31 {
  32 class Actor;
  33 class KeyEvent;
  34 class Layer;
  35 class RenderTaskList;
  36 class TouchEvent;
  37 class WheelEvent;
  38
  39 namespace Internal DALI_INTERNAL
  40 {
  41 class Scene;
  42 }
  43
  44 namespace Graphics
  45 {
  46 class RenderTarget;
  47 }
  48
  49 namespace Integration
  50 {
  51 struct Event;
  52
  53 /**
  54  * @brief
  55  *
  56  * Scene creates a "world" that can be bound to a surface for rendering.
  57  *
  58  */
  59 class DALI_CORE_API Scene : public BaseHandle
  60 {
  61 public:
  62   using EventProcessingFinishedSignalType = Signal<void()>;                        ///< Event Processing finished signal type
  63   using KeyEventSignalType                = Signal<void(const Dali::KeyEvent&)>;   ///< Key event signal type
  64   using KeyEventGeneratedSignalType       = Signal<bool(const Dali::KeyEvent&)>;   ///< key event generated signal type
  65   using TouchEventSignalType              = Signal<void(const Dali::TouchEvent&)>; ///< Touch signal type
  66   using WheelEventSignalType              = Signal<void(const Dali::WheelEvent&)>; ///< WheelEvent signal type
  67
  68   using FrameCallbackContainer = std::vector<std::pair<std::unique_ptr<CallbackBase>, int32_t> >;
  69
  70   /**
  71    * @brief Create an initialized Scene handle.
  72    *
  73    * @param[in] size The size of the set surface for this scene
  74    * @param[in] orientation The rotated angle 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, int32_t orientation = 0);
  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    */
 213   void SurfaceResized(float width, float height);
 214
 215   /**
 216    * @brief Informs the scene that the surface has been replaced.
 217    */
 218   void SurfaceReplaced();
 219
 220   /**
 221    * @brief Discards this Scene from the Core.
 222    */
 223   void Discard();
 224
 225   /**
 226    * @brief Sets the render target for the surface.
 227    *
 228    * @param[in] renderTarget The render target for the surface
 229    */
 230   void SetSurfaceRenderTarget(Graphics::RenderTarget* renderTarget);
 231
 232   /**
 233    * @brief Retrieve the Scene that the given actor belongs to.
 234    * @return The Scene.
 235    */
 236   static Integration::Scene Get(Actor actor);
 237
 238   /**
 239    * This function is called when an event is queued.
 240    * @param[in] event A event to queue.
 241    */
 242   void QueueEvent(const Integration::Event& event);
 243
 244   /**
 245    * This function is called by Core when events are processed.
 246    */
 247   void ProcessEvents();
 248
 249   /**
 250    * @brief Adds a callback that is called when the frame rendering is done by the graphics driver.
 251    *
 252    * @param[in] callback The function to call
 253    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 254    *
 255    * @note A callback of the following type may be used:
 256    * @code
 257    *   void MyFunction( int32_t frameId );
 258    * @endcode
 259    * This callback will be deleted once it is called.
 260    *
 261    * @note Ownership of the callback is passed onto this class.
 262    */
 263   void AddFrameRenderedCallback(std::unique_ptr<CallbackBase> callback, int32_t frameId);
 264
 265   /**
 266    * @brief Adds a callback that is called when the frame is displayed on the display.
 267    *
 268    * @param[in] callback The function to call
 269    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 270    *
 271    * @note A callback of the following type may be used:
 272    * @code
 273    *   void MyFunction( int32_t frameId );
 274    * @endcode
 275    * This callback will be deleted once it is called.
 276    *
 277    * @note Ownership of the callback is passed onto this class.
 278    */
 279   void AddFramePresentedCallback(std::unique_ptr<CallbackBase> callback, int32_t frameId);
 280
 281   /**
 282    * @brief Gets the callback list that is called when the frame rendering is done by the graphics driver.
 283    *
 284    * @param[out] callbacks The callback list
 285    *
 286    * @note This is called in the update thread.
 287    */
 288   void GetFrameRenderedCallback(FrameCallbackContainer& callbacks);
 289
 290   /**
 291    * @brief Gets the callback list that is called when the frame is displayed on the display.
 292    *
 293    * @param[out] callbacks The callback list
 294    *
 295    * @note This is called in the update thread.
 296    */
 297   void GetFramePresentedCallback(FrameCallbackContainer& callbacks);
 298
 299   /**
 300    * @brief Informs the scene that the set surface has been rotated.
 301    *
 302    * @param[in] width The width of rotated surface
 303    * @param[in] height The height of rotated surface
 304    * @param[in] orientation The orientation of rotated surface
 305    */
 306   void SurfaceRotated(float width, float height, int32_t orientation);
 307
 308   /**
 309    * @brief Gets the current surface orientation. It gets the value from the scene object.
 310    *
 311    * @return The current surface orientation.
 312    */
 313   int32_t GetCurrentSurfaceOrientation() const;
 314
 315   /**
 316    * @brief Gets the current surface rectangle. It gets the value from the scene object.
 317    *
 318    * @return The current surface rectangle
 319    */
 320   const Rect<int32_t>& GetCurrentSurfaceRect() const;
 321
 322   /**
 323    * Query wheter the surface rect is changed or not.
 324    * @return true if the surface rect is changed.
 325    */
 326   bool IsSurfaceRectChanged() const;
 327
 328   /**
 329    * @brief This signal is emitted just after the event processing is finished.
 330    *
 331    * @return The signal to connect to
 332    */
 333   EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
 334
 335   /**
 336    * @brief This signal is emitted when key event is received.
 337    *
 338    * A callback of the following type may be connected:
 339    * @code
 340    *   void YourCallbackName(const KeyEvent& event);
 341    * @endcode
 342    * @return The signal to connect to
 343    */
 344   KeyEventSignalType& KeyEventSignal();
 345
 346   /**
 347    * @brief The user would connect to this signal to get a KeyEvent when KeyEvent is generated.
 348    *
 349    * If the control already consumed key event, KeyEventProcessor do not need to Emit keyEvent.
 350    * Therefore, KeyinputManager first checks whether KeyEvent is generated as KeyEventGeneratedSignal.
 351    * After that keyEventProcessor must invoke KeyEvent only if KeyEventGeneratedSignal () is not consumed.
 352    *
 353    * A callback of the following type may be connected:
 354    * @code
 355    *   bool YourCallbackName(const KeyEvent& event);
 356    * @endcode
 357    *
 358    * @return The return is true if KeyEvent is consumed, otherwise false.
 359    */
 360   KeyEventGeneratedSignalType& KeyEventGeneratedSignal();
 361
 362   /**
 363    * @brief This signal is emitted when the screen is touched and when the touch ends
 364    * (i.e. the down & up touch events only).
 365    *
 366    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 367    * then when the last finger is lifted.
 368    * An interrupted event will also be emitted (if it occurs).
 369    * A callback of the following type may be connected:
 370    * @code
 371    *   void YourCallbackName( TouchEvent event );
 372    * @endcode
 373    *
 374    * @return The touch signal to connect to
 375    * @note Motion events are not emitted.
 376    */
 377   TouchEventSignalType& TouchedSignal();
 378
 379   /**
 380    * @brief This signal is emitted when wheel event is received.
 381    *
 382    * A callback of the following type may be connected:
 383    * @code
 384    *   void YourCallbackName(const WheelEvent& event);
 385    * @endcode
 386    * @return The signal to connect to
 387    */
 388   WheelEventSignalType& WheelEventSignal();
 389
 390 public: // Not intended for application developers
 391   /**
 392    * @brief This constructor is used by Dali::New() methods.
 393    *
 394    * @param[in] scene A pointer to an internal Scene resource
 395    */
 396   explicit DALI_INTERNAL Scene(Internal::Scene* scene);
 397 };
 398
 399 } // namespace Integration
 400
 401 } // namespace Dali
 402
 403 #endif // DALI_SCENE_H