dali/integration-api/scene.h

   1 #ifndef DALI_SCENE_H
   2 #define DALI_SCENE_H
   3
   4 /*
   5  * Copyright (c) 2023 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/graphics-api/graphics-controller.h>
  26 #include <dali/graphics-api/graphics-render-target-create-info.h>
  27 #include <dali/public-api/common/vector-wrapper.h>
  28 #include <dali/public-api/math/vector2.h>
  29 #include <dali/public-api/math/vector4.h>
  30 #include <dali/public-api/object/handle.h>
  31
  32 namespace Dali
  33 {
  34 class Actor;
  35 class KeyEvent;
  36 class Layer;
  37 class RenderTaskList;
  38 class TouchEvent;
  39 class WheelEvent;
  40
  41 namespace Internal DALI_INTERNAL
  42 {
  43 class Scene;
  44 }
  45
  46 namespace Graphics
  47 {
  48 class RenderTarget;
  49 }
  50
  51 namespace Integration
  52 {
  53 struct Event;
  54
  55 /**
  56  * @brief
  57  *
  58  * Scene creates a "world" that can be bound to a surface for rendering.
  59  *
  60  */
  61 class DALI_CORE_API Scene : public BaseHandle
  62 {
  63
  64 public:
  65
  66   /**
  67    * @brief Touch event propagation way
  68    */
  69   enum TouchPropagationType
  70   {
  71     PARENT,     ///< events are propagated to parents in the traditional way
  72     GEOMETRY    ///< events are propagated based on geometry.
  73   };
  74
  75   using EventProcessingFinishedSignalType = Signal<void()>;                        ///< Event Processing finished signal type
  76   using KeyEventSignalType                = Signal<void(const Dali::KeyEvent&)>;   ///< Key event signal type
  77   using KeyEventGeneratedSignalType       = Signal<bool(const Dali::KeyEvent&)>;   ///< key event generated signal type
  78   using TouchEventSignalType              = Signal<void(const Dali::TouchEvent&)>; ///< Touch signal type
  79   using WheelEventSignalType              = Signal<void(const Dali::WheelEvent&)>; ///< WheelEvent signal type
  80   using WheelEventGeneratedSignalType     = Signal<bool(const Dali::WheelEvent&)>; ///< WheelEvent generated signal type
  81
  82   using FrameCallbackContainer = std::vector<std::pair<std::unique_ptr<CallbackBase>, int32_t> >;
  83
  84   /**
  85    * @brief Create an initialized Scene handle.
  86    *
  87    * @param[in] size The size of the set surface for this scene
  88    * @param[in] windowOrientation The rotated angle of the set surface for this scene
  89    * @param[in] screenOrientation The rotated angle of the screen
  90    *
  91    * @return a handle to a newly allocated Dali resource.
  92    */
  93   static Scene New(Size size, int32_t windowOrientation = 0, int32_t screenOrientation = 0);
  94
  95   /**
  96    * @brief Downcast an Object handle to Scene handle.
  97    *
  98    * If handle points to a Scene object the downcast produces
  99    * valid handle. If not the returned handle is left uninitialized.
 100    * @param[in] handle to An object
 101    * @return handle to a Scene object or an uninitialized handle
 102    */
 103   static Scene DownCast(BaseHandle handle);
 104
 105   /**
 106    * @brief Create an uninitialized Scene handle.
 107    *
 108    * This can be initialized with Scene::New(). Calling member
 109    * functions with an uninitialized Dali::Object is not allowed.
 110    */
 111   Scene();
 112
 113   /**
 114    * @brief Destructor
 115    *
 116    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 117    */
 118   ~Scene();
 119
 120   /**
 121    * @brief This copy constructor is required for (smart) pointer semantics.
 122    *
 123    * @param [in] handle A reference to the copied handle
 124    */
 125   Scene(const Scene& handle);
 126
 127   /**
 128    * @brief This assignment operator is required for (smart) pointer semantics.
 129    *
 130    * @param [in] rhs  A reference to the copied handle
 131    * @return A reference to this
 132    */
 133   Scene& operator=(const Scene& rhs);
 134
 135   /**
 136    * @brief This move constructor is required for (smart) pointer semantics.
 137    *
 138    * @param [in] handle A reference to the moved handle
 139    */
 140   Scene(Scene&& handle) noexcept;
 141
 142   /**
 143    * @brief This move assignment operator is required for (smart) pointer semantics.
 144    *
 145    * @param [in] rhs  A reference to the moved handle
 146    * @return A reference to this
 147    */
 148   Scene& operator=(Scene&& rhs) noexcept;
 149
 150   /**
 151    * @brief Adds a child Actor to the Scene.
 152    *
 153    * The child will be referenced.
 154    * @param[in] actor The child
 155    * @pre The actor has been initialized.
 156    * @pre The actor does not have a parent.
 157    */
 158   void Add(Actor actor);
 159
 160   /**
 161    * @brief Removes a child Actor from the Scene.
 162    *
 163    * The child will be unreferenced.
 164    * @param[in] actor The child
 165    * @pre The actor has been added to the stage.
 166    */
 167   void Remove(Actor actor);
 168
 169   /**
 170    * @brief Returns the size of the Scene in pixels as a Vector.
 171    *
 172    * The x component will be the width of the Scene in pixels.
 173    * The y component will be the height of the Scene in pixels.
 174    *
 175    * @return The size of the Scene as a Vector
 176    */
 177   Size GetSize() const;
 178
 179   /**
 180    * Sets horizontal and vertical pixels per inch value that is used by the display
 181    * @param[in] dpi Horizontal and vertical dpi value
 182    */
 183   void SetDpi(Vector2 dpi);
 184
 185   /**
 186    * @brief Retrieves the DPI of the display device to which the scene is connected.
 187    *
 188    * @return The horizontal and vertical DPI
 189    */
 190   Vector2 GetDpi() const;
 191
 192   /**
 193    * @brief Sets the background color.
 194    *
 195    * @param[in] color The new background color
 196    */
 197   void SetBackgroundColor(const Vector4& color);
 198
 199   /**
 200    * @brief Gets the background color of the render　surface.
 201    *
 202    * @return The background color
 203    */
 204   Vector4 GetBackgroundColor() const;
 205
 206   /**
 207    * @brief Retrieves the list of render-tasks.
 208    *
 209    * @return A valid handle to a RenderTaskList
 210    */
 211   Dali::RenderTaskList GetRenderTaskList() const;
 212
 213   /**
 214    * @brief Returns the Scene's Root Layer.
 215    *
 216    * @return The root layer
 217    */
 218   Layer GetRootLayer() const;
 219
 220   /**
 221    * @brief Returns the Scene's Overlay Layer.
 222    * If there is no overlay layer yet, this creates the layer and an associated render task.
 223    *
 224    * @return The overlay layer
 225    */
 226   Layer GetOverlayLayer();
 227
 228   /**
 229    * @brief Queries the number of on-stage layers.
 230    *
 231    * Note that a default layer is always provided (count >= 1).
 232    * @return The number of layers
 233    */
 234   uint32_t GetLayerCount() const;
 235
 236   /**
 237    * @brief Retrieves the layer at a specified depth.
 238    *
 239    * @param[in] depth The depth
 240    * @return The layer found at the given depth
 241    * @pre Depth is less than layer count; see GetLayerCount().
 242    */
 243   Layer GetLayer(uint32_t depth) const;
 244
 245   /**
 246    * @brief Informs the scene that the set surface has been resized.
 247    *
 248    * @param[in] width The new width of the set surface
 249    * @param[in] height The new height of the set surface
 250    */
 251   void SurfaceResized(float width, float height);
 252
 253   /**
 254    * @brief Informs the scene that the surface has been replaced.
 255    */
 256   void SurfaceReplaced();
 257
 258   /**
 259    * @brief Removes the scene graph object.
 260    */
 261   void RemoveSceneObject();
 262
 263   /**
 264    * @brief Discards this Scene from the Core.
 265    */
 266   void Discard();
 267
 268   /**
 269    * @brief Sets the render target for the surface.
 270    *
 271    * @param[in] renderTarget The render target create info for the surface
 272    */
 273   void SetSurfaceRenderTarget(const Graphics::RenderTargetCreateInfo& createInfo);
 274
 275   /**
 276    * @brief Retrieve the Scene that the given actor belongs to.
 277    * @return The Scene.
 278    */
 279   static Integration::Scene Get(Actor actor);
 280
 281   /**
 282    * This function is called when an event is queued.
 283    * @param[in] event A event to queue.
 284    */
 285   void QueueEvent(const Integration::Event& event);
 286
 287   /**
 288    * This function is called by Core when events are processed.
 289    */
 290   void ProcessEvents();
 291
 292   /**
 293    * @brief Adds a callback that is called when the frame rendering is done by the graphics driver.
 294    *
 295    * @param[in] callback The function to call
 296    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 297    *
 298    * @note A callback of the following type may be used:
 299    * @code
 300    *   void MyFunction( int32_t frameId );
 301    * @endcode
 302    * This callback will be deleted once it is called.
 303    *
 304    * @note Ownership of the callback is passed onto this class.
 305    */
 306   void AddFrameRenderedCallback(std::unique_ptr<CallbackBase> callback, int32_t frameId);
 307
 308   /**
 309    * @brief Adds a callback that is called when the frame is displayed on the display.
 310    *
 311    * @param[in] callback The function to call
 312    * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 313    *
 314    * @note A callback of the following type may be used:
 315    * @code
 316    *   void MyFunction( int32_t frameId );
 317    * @endcode
 318    * This callback will be deleted once it is called.
 319    *
 320    * @note Ownership of the callback is passed onto this class.
 321    */
 322   void AddFramePresentedCallback(std::unique_ptr<CallbackBase> callback, int32_t frameId);
 323
 324   /**
 325    * @brief Gets the callback list that is called when the frame rendering is done by the graphics driver.
 326    *
 327    * @param[out] callbacks The callback list
 328    *
 329    * @note This is called in the update thread.
 330    */
 331   void GetFrameRenderedCallback(FrameCallbackContainer& callbacks);
 332
 333   /**
 334    * @brief Gets the callback list that is called when the frame is displayed on the display.
 335    *
 336    * @param[out] callbacks The callback list
 337    *
 338    * @note This is called in the update thread.
 339    */
 340   void GetFramePresentedCallback(FrameCallbackContainer& callbacks);
 341
 342   /**
 343    * @brief Informs the scene that the set surface has been rotated.
 344    *
 345    * @param[in] width The width of rotated surface
 346    * @param[in] height The height of rotated surface
 347    * @param[in] windowOrientation the current window orientation
 348    * @param[in] screenOrientation the current screen orientation
 349    */
 350   void SurfaceRotated(float width, float height, int32_t windowOrientation, int32_t screenOrientation);
 351
 352   /**
 353    * @brief Gets the current surface orientation. It gets the value from the scene object.
 354    *
 355    * @return The current surface orientation.
 356    */
 357   int32_t GetCurrentSurfaceOrientation() const;
 358
 359   /**
 360    * @brief Gets the current screen orientation. It gets the value from the scene object.
 361    *
 362    * @return The current screen orientation.
 363    */
 364   int32_t GetCurrentScreenOrientation() const;
 365
 366   /**
 367    * @brief Gets the current surface rectangle. It gets the value from the scene object.
 368    *
 369    * @return The current surface rectangle
 370    */
 371   const Rect<int32_t>& GetCurrentSurfaceRect() const;
 372
 373   /**
 374    * Query how many times the surface rect changed.
 375    * @note It will reset surface rect changed count.
 376    * @return The count of the surface rect changed.
 377    */
 378   uint32_t GetSurfaceRectChangedCount() const;
 379
 380   /**
 381    * @brief Send message to acknowledge for completing window rotation with current window orientation.
 382    *
 383    * If this function is called, the message is sent to render thread, then mSurfaceRectChanged in scene-graph-scene is set with true.
 384    * After that, render thread checks whether window rotation event is received, mSurfaceRectChanged and the neccessary flag are set.
 385    * If they are all true, rotation done function is called to complete window rotation.
 386    */
 387   void SetRotationCompletedAcknowledgement();
 388
 389   /**
 390    * @brief Query wheter is set to acknowledge for completing surface rotation.
 391    * @return true it should be acknowledged.
 392    *
 393    * If SetRotationCompletedAcknowledgement() is called and the related message is received to scene-graph-scene,
 394    * then mSurfaceRectChanged in scene-graph-scene is set with true.
 395    *
 396    * When this function is called, the mSurfaceRectChanged in scene-graph-scene is return.
 397    * Then, the flag will be reset.
 398    *
 399    * @note This function should be not called the application's main thread.
 400    * Because this function should be called in windwow surface's postrender() function to complete window rotation manually.
 401    */
 402   bool IsRotationCompletedAcknowledgementSet() const;
 403
 404   /**
 405    * @brief Keep rendering for at least the given amount of time.
 406    *
 407    * By default, Dali will stop rendering when no Actor positions are being set, and when no animations are running etc.
 408    * This method is useful to force screen refreshes.
 409    *
 410    * @param[in] durationSeconds Time to keep rendering, 0 means render at least one more frame
 411    */
 412   void KeepRendering(float durationSeconds);
 413
 414   /**
 415    * @brief Sets whether the scene will update partial area or full area.
 416    *
 417    * @param[in] enabled True if the scene should update partial area
 418    * @note This doesn't change the global value which is set by the environment variable.
 419    * This works when partial update is enabled by the environment variable. If the partial update is disabled by the environment variable, it changes nothing.
 420    */
 421   void SetPartialUpdateEnabled(bool enabled);
 422
 423   /**
 424    * @brief Queries whether the scene will update partial area.
 425    *
 426    * @return True if the scene should update partial area
 427    */
 428   bool IsPartialUpdateEnabled() const;
 429
 430   /**
 431    * @brief Sets whether the processes using geometry event propagation touch and hover events.
 432    *
 433    * @param[in] enabled True if the processes using geometry event propagation touch and hover events.
 434    */
 435   void SetGeometryHittestEnabled(bool enabled);
 436
 437   /**
 438    * @brief Queries whether the scene using geometry event propagation touch and hover events.
 439    *
 440    * @return True if the scene using geometry event propagation touch and hover events.
 441    */
 442   bool IsGeometryHittestEnabled();
 443
 444   /**
 445    * @brief Get the Touch Propagation Type
 446    *
 447    * @return TouchPropagationType
 448    */
 449   TouchPropagationType GetTouchPropagationType();
 450
 451   /**
 452    * @brief Sets the native window id
 453    *
 454    * @param nativeId The native window id
 455    */
 456   void SetNativeId(int32_t nativeId);
 457
 458   /**
 459    * @brief Gets the native window id
 460    *
 461    * @return The native window id
 462    */
 463   int32_t GetNativeId() const;
 464
 465   /**
 466    * @brief This signal is emitted just after the event processing is finished.
 467    *
 468    * @return The signal to connect to
 469    */
 470   EventProcessingFinishedSignalType& EventProcessingFinishedSignal();
 471
 472   /**
 473    * @brief This signal is emitted when key event is received.
 474    *
 475    * A callback of the following type may be connected:
 476    * @code
 477    *   void YourCallbackName(const KeyEvent& event);
 478    * @endcode
 479    * @return The signal to connect to
 480    */
 481   KeyEventSignalType& KeyEventSignal();
 482
 483   /**
 484    * @brief The user would connect to this signal to get a KeyEvent when KeyEvent is generated.
 485    *
 486    * If the control already consumed key event, KeyEventProcessor do not need to Emit keyEvent.
 487    * Therefore, KeyinputManager first checks whether KeyEvent is generated as KeyEventGeneratedSignal.
 488    * After that keyEventProcessor must invoke KeyEvent only if KeyEventGeneratedSignal () is not consumed.
 489    *
 490    * A callback of the following type may be connected:
 491    * @code
 492    *   bool YourCallbackName(const KeyEvent& event);
 493    * @endcode
 494    *
 495    * @return The return is true if KeyEvent is consumed, otherwise false.
 496    */
 497   KeyEventGeneratedSignalType& KeyEventGeneratedSignal();
 498
 499   /**
 500    * @brief The user would connect to this signal to intercept a KeyEvent at window.
 501    *
 502    * Intercepts KeyEvents in the window before dispatching KeyEvents to the control.
 503    * If a KeyEvent is consumed, no KeyEvent is delivered to the control.
 504    *
 505    * A callback of the following type may be connected:
 506    * @code
 507    *   bool YourCallbackName(const KeyEvent& event);
 508    * @endcode
 509    *
 510    * @return The return is true if KeyEvent is consumed, otherwise false.
 511    */
 512   KeyEventGeneratedSignalType& InterceptKeyEventSignal();
 513
 514   /**
 515    * @brief This signal is emitted when the screen is touched and when the touch ends
 516    * (i.e. the down & up touch events only).
 517    *
 518    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 519    * then when the last finger is lifted.
 520    * An interrupted event will also be emitted (if it occurs).
 521    * A callback of the following type may be connected:
 522    * @code
 523    *   void YourCallbackName( TouchEvent event );
 524    * @endcode
 525    *
 526    * @return The touch signal to connect to
 527    * @note Motion events are not emitted.
 528    */
 529   TouchEventSignalType& TouchedSignal();
 530
 531   /**
 532    * @brief This signal is emitted when wheel event is received.
 533    *
 534    * A callback of the following type may be connected:
 535    * @code
 536    *   void YourCallbackName(const WheelEvent& event);
 537    * @endcode
 538    * @return The signal to connect to
 539    */
 540   WheelEventSignalType& WheelEventSignal();
 541
 542   /**
 543    * @brief When a custom wheel event occurs, it need to process the focused actor first.
 544    *
 545    * Therefore, KeyboardFocusManager first checks whether WheelEvent is generated as WheelEventGeneratedSignal.
 546    * After that wheelEventProcessor must invoke WheelEvent only if wheelEventGeneratedSignal () is not consumed.
 547    *
 548    * This is only valid for custom wheel events.
 549    *
 550    * A callback of the following type may be connected:
 551    * @code
 552    *   bool YourCallbackName(const WheelEvent& event);
 553    * @endcode
 554    *
 555    * @return The return is true if WheelEvent is consumed, otherwise false.
 556    */
 557   WheelEventGeneratedSignalType& WheelEventGeneratedSignal();
 558
 559 public: // Not intended for application developers
 560   /**
 561    * @brief This constructor is used by Dali::New() methods.
 562    *
 563    * @param[in] scene A pointer to an internal Scene resource
 564    */
 565   explicit DALI_INTERNAL Scene(Internal::Scene* scene);
 566 };
 567
 568 } // namespace Integration
 569
 570 } // namespace Dali
 571
 572 #endif // DALI_SCENE_H