dali-scene3d/public-api/controls/scene-view/scene-view.h

   1 #ifndef DALI_SCENE3D_SCENE_VIEW_H
   2 #define DALI_SCENE3D_SCENE_VIEW_H
   3
   4 /*
   5  * Copyright (c) 2024 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 <dali-toolkit/public-api/controls/control.h>
  23 #include <dali-toolkit/public-api/image-loader/image-url.h>
  24 #include <dali/public-api/actors/camera-actor.h>
  25 #include <dali/public-api/animation/animation.h>
  26 #include <dali/public-api/common/dali-common.h>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali-scene3d/public-api/api.h>
  30 #include <dali-scene3d/public-api/common/environment-map.h>
  31
  32 namespace Dali
  33 {
  34 namespace Scene3D
  35 {
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class SceneView;
  39 }
  40
  41 /**
  42  * @addtogroup dali_toolkit_controls_scene_view
  43  * @{
  44  */
  45
  46 /**
  47  * @brief SceneView is a Dali::Toolkit::Control to show multiple 3D objects in a single 3D scene.
  48  * Each SceneView has its own 3D space, and 3D objects added to SceneView are positioned in the space.
  49  * SceneView has a 3D root layer internally to trigger the depth test in the rendering process.
  50  * When an Actor is added to the SceneView with Add() method,
  51  * the Actor and its children are actually become child of the 3D layer automatically.
  52  *
  53  *  SceneView
  54  *      |
  55  * Dali::Layer(Layer::LAYER_3D)
  56  *      |
  57  *    Actor
  58  *
  59  * The children of the 3D root layer will be rendered with the SceneView's own CameraActor.
  60  *
  61  * SceneView can have multiple CameraActor and one of them is used to render the multiple objects as a Scene.
  62  * AddCamera(), RemoveCamera(), GetCamera(), and SelectCamera() are methods to manage CameraActors of the SceneView.
  63  * Users can place multiple cameras in a scene, either to show the entire scene or to show individual objects.
  64  * And the user can select the currently needed camera by using the SelectCamera() method.
  65  *
  66  * SceneView makes one built-in CameraActor by default.
  67  * The default CameraActor has index 0 and is not removed by using RemoveCamera() method.
  68  * Therefore, the minimum value returned by GetCameraCount() method is 1.
  69  *
  70  * If the size of SceneView is changed, Some properties of CameraActor that depend on the size can be changed too.
  71  * The changing properties are as follows: projectionMode, aspectRatio, leftPlaneDistance, rightPlaneDistance, topPlaneDistance, and bottomPlaneDistance.
  72  * Position, near/farPlaneDistance, and FieldOfView are maintained even if the size of the SceneView is changed.
  73  * The FieldOfView of Dali::CameraActor is for vertical fov. The horizontal fov is internally updated according to the SceneView size.
  74  *
  75  * The same light source is set for all Models added to SceneView, if SceneView has light source.
  76  * The SetImageBasedLightSource() method sets the same IBL to all Models added to the SceneView.
  77  * If any Model already has an IBL, it is replaced with the SceneView's IBL.
  78  *
  79  * SceneView provides an option to use FBO for rendering result with UseFramebuffer() method.
  80  * If it is false, SceneView is always drawn in the form of a rectangle on the default window surface directly.
  81  * It improves performance, but the SceneView is always drawn on top of other 2D objects regardless of Actor tree order.
  82  * And it will show wrong result in case the window's default CameraActor is transformed.
  83  * So, it is recommended not to change window's CameraActor.
  84  *
  85  * If FBO is used, the rendering result of SceneView is drawn on the FBO and it is mapped on the plane of the SceneView.
  86  * It decreases performance, but it is useful to show SceneView according to the rendering order with other Actors.
  87  * And it can be used in case window's CameraActor is transformed.
  88  *
  89  * And since SceneView is a Control, it can be placed together with other 2D UI components in the DALi window.
  90  *
  91  * @note We support to render model well only if glsl version is higher than 300.
  92  * @note We do not support Toolkit::RenderEffect when UseFrameBuffer(false).
  93  *
  94  * @SINCE_2_1.38
  95  * @code
  96  *
  97  * Dali::Scene3D::SceneView sceneView = Dali::Scene3D::SceneView::New();
  98  * sceneView.SetProperty(Dali::Actor::Property::SIZE, Vector2(400, 400));
  99  * mWindow.Add(sceneView);
 100  *
 101  * Dali::Scene3D::Model model = Dali::Scene3D::Model::New(...);
 102  * sceneView.Add(model);
 103  *
 104  * CameraActor cameraActor = CameraActor::New();
 105  * sceneView.AddCamera(cameraActor);
 106  *
 107  * @endcode
 108  */
 109 class DALI_SCENE3D_API SceneView : public Dali::Toolkit::Control
 110 {
 111 public:
 112   /**
 113    * @brief The start and end property ranges for this control.
 114    * @SINCE_2_3.1
 115    */
 116   enum PropertyRange
 117   {
 118     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
 119     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000
 120   };
 121
 122   struct Property
 123   {
 124     enum
 125     {
 126       /**
 127        * @brief URL of a masking image
 128        * @details Name "alphaMaskUrl", type Property::STRING, URL of image to apply as
 129        * a mask after SceneView is drawn.
 130        * @note Alpha masking is only available when framebuffer is used.
 131        * @note Optional.
 132        */
 133       ALPHA_MASK_URL = PROPERTY_START_INDEX,
 134
 135       /**
 136        * @brief The scale factor to apply to the content image before masking
 137        * @details Name "maskContentScale", type Property::FLOAT, The scale factor
 138        * to apply to the content before masking. Note, scaled result is cropped to
 139        * the same size as the alpha mask.
 140        * @note Optional.
 141        */
 142       MASK_CONTENT_SCALE,
 143
 144       /**
 145        * @brief Whether to crop rendered result to mask or scale mask to fit result
 146        * @details Name "cropToMask", type Property::BOOLEAN, True if the rendered result should
 147        * be cropped to match the mask size, or false if the result should remain the same size.
 148        * @note Optional, Default true
 149        * @note If this is false, then the mask is scaled to fit the rendered result before being applied.
 150        */
 151       CROP_TO_MASK,
 152     };
 153   };
 154
 155 public:
 156
 157   /**
 158    * @brief Typedef for capture finished signals sent by this class.
 159    *
 160    * @SINCE_2_3.37
 161    */
 162   typedef Signal<void(SceneView, int32_t, const Dali::Toolkit::ImageUrl&)> CaptureFinishedSignalType;
 163
 164   /**
 165    * @brief Typedef for camera transition finished signals sent by this class.
 166    *
 167    * @SINCE_2_3.37
 168    */
 169   typedef Signal<void(SceneView)> CameraTransitionFinishedSignalType;
 170
 171   /**
 172    * @brief Create an initialized SceneView.
 173    *
 174    * @SINCE_2_1.38
 175    * @return A handle to a newly allocated Dali resource
 176    */
 177   static SceneView New();
 178
 179   /**
 180    * @brief Creates an uninitialized SceneView.
 181    *
 182    * Only derived versions can be instantiated. Calling member
 183    * functions with an uninitialized Dali::Object is not allowed.
 184    *
 185    * @SINCE_2_1.38
 186    */
 187   SceneView();
 188
 189   /**
 190    * @brief Destructor.
 191    *
 192    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 193    *
 194    * @SINCE_2_1.38
 195    */
 196   ~SceneView();
 197
 198   /**
 199    * @brief Copy constructor.
 200    *
 201    * @SINCE_2_1.38
 202    * @param[in] sceneView Handle to an object
 203    */
 204   SceneView(const SceneView& sceneView);
 205
 206   /**
 207    * @brief Move constructor
 208    *
 209    * @SINCE_2_1.38
 210    * @param[in] rhs A reference to the moved handle
 211    */
 212   SceneView(SceneView&& rhs) noexcept;
 213
 214   /**
 215    * @brief Assignment operator.
 216    *
 217    * @SINCE_2_1.38
 218    * @param[in] sceneView Handle to an object
 219    * @return reference to this
 220    */
 221   SceneView& operator=(const SceneView& sceneView);
 222
 223   /**
 224    * @brief Move assignment
 225    *
 226    * @SINCE_2_1.38
 227    * @param[in] rhs A reference to the moved handle
 228    * @return A reference to this
 229    */
 230   SceneView& operator=(SceneView&& rhs) noexcept;
 231
 232   /**
 233    * @brief Downcasts an Object handle to SceneView.
 234    *
 235    * If handle points to a SceneView, the downcast produces valid handle.
 236    * If not, the returned handle is left uninitialized.
 237    *
 238    * @SINCE_2_1.38
 239    * @param[in] handle Handle to an object
 240    * @return Handle to a SceneView or an uninitialized handle
 241    */
 242   static SceneView DownCast(BaseHandle handle);
 243
 244   /**
 245    * @brief Adds a CameraActor to the SceneView
 246    * The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
 247    *
 248    * @SINCE_2_1.38
 249    * @note
 250    * AspectRatio property of CameraActor will be changed depending on the Size of this SceneView.
 251    *
 252    * For Perspective camera
 253    * The FieldOfView of Dali::CameraActor is for vertical fov.
 254    * When the size of the SceneView is changed, the vertical fov is maintained
 255    * and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
 256    *
 257    * For Orthographic camera
 258    * leftPlaneDistance, rightPlaneDistance, and bottomPlaneDistance properties are defined according to the topPlaneDistance and aspectRatio.
 259    *
 260    * @param[in] camera CameraActor added on this scene view.
 261    */
 262   void AddCamera(Dali::CameraActor camera);
 263
 264   /**
 265    * @brief Removes a CameraActor from this SceneView.
 266    *
 267    * @SINCE_2_1.38
 268    * @note If removed CameraActor is selected CameraActor,
 269    * first camera in the list is set to selected CameraActor.
 270    *
 271    * @param[in] camera CameraActor to be removed from this SceneView
 272    */
 273   void RemoveCamera(CameraActor camera);
 274
 275   /**
 276    * @brief Retrieves the number of cameras.
 277    *
 278    * @SINCE_2_1.38
 279    * @return Number of cameras those currently the SceneView contains.
 280    */
 281   uint32_t GetCameraCount() const;
 282
 283   /**
 284    * @brief Retrieves selected CameraActor.
 285    *
 286    * @SINCE_2_1.38
 287    * @return CameraActor currently used in SceneView as a selected CameraActor
 288    */
 289   CameraActor GetSelectedCamera() const;
 290
 291   /**
 292    * @brief Retrieves a CameraActor of the index.
 293    *
 294    * @SINCE_2_1.38
 295    * @param[in] index Index of CameraActor to be retrieved.
 296    *
 297    * @return CameraActor of the index
 298    */
 299   CameraActor GetCamera(uint32_t index) const;
 300
 301   /**
 302    * @brief Retrieves a CameraActor of the name.
 303    *
 304    * @SINCE_2_1.38
 305    * @param[in] name string keyword of CameraActor to be retrieved.
 306    *
 307    * @return CameraActor that has the name as a Dali::Actor::Property::NAME
 308    */
 309   CameraActor GetCamera(const std::string& name) const;
 310
 311   /**
 312    * @brief Makes SceneView use a CameraActor of index as a selected camera.
 313    *
 314    * @SINCE_2_1.38
 315    * @param[in] index Index of CameraActor to be used as a selected camera.
 316    * @note If the Camera is not added in this Scene, this method adds it on SceneView root.
 317    */
 318   void SelectCamera(uint32_t index);
 319
 320   /**
 321    * @brief Makes SceneView use a CameraActor of a name as a selected camera.
 322    *
 323    * @SINCE_2_1.38
 324    * @param[in] name string keyword of CameraActor to be used as a selected camera.
 325    * @note If the Camera is not added in this Scene, this method adds it on SceneView root.
 326    */
 327   void SelectCamera(const std::string& name);
 328
 329   /**
 330    * @brief Starts camera transition from currently selected camera to a camera of index.
 331    * Camera Position, Orientation and FieldOfView(Orthogrpahic Size) are smoothly animated.
 332    *
 333    * @SINCE_2_3.37
 334    * @param[in] index Index of destination Camera of Camera transition.
 335    * @param[in] durationSeconds The duration in seconds.
 336    * @param[in] alphaFunction The alpha function to apply.
 337    * @note The selected camera is switched to the Camera of the index when the transition is finished.
 338    * During camera transition, Selected Camera should not be changed by using SelectCamera() or StartCameraTransition() method.
 339    * During camera transition, Camera properties of Selected Camera should not be changed.
 340    */
 341   void StartCameraTransition(uint32_t index, float durationSeconds, Dali::AlphaFunction alphaFunction = AlphaFunction::DEFAULT);
 342
 343   /**
 344    * @brief Starts camera transition from currently selected camera to a camera of index.
 345    * Camera Position, Orientation and FieldOfView(Orthogrpahic Size) are smoothly animated.
 346    *
 347    * @SINCE_2_3.37
 348    * @param[in] name string keyword of destination Camera of Camera transition.
 349    * @param[in] durationSeconds The duration in seconds.
 350    * @param[in] alphaFunction The alpha function to apply.
 351    * @note The selected camera is switched to the Camera of the input name when the transition is finished.
 352    * During camera transition, Selected Camera should not be changed by using SelectCamera() or StartCameraTransition() method.
 353    * During camera transition, Camera properties of Selected Camera should not be changed.
 354    */
 355   void StartCameraTransition(std::string name, float durationSeconds, Dali::AlphaFunction alphaFunction = AlphaFunction::DEFAULT);
 356
 357   /**
 358    * @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
 359    *
 360    * @SINCE_2_1.38
 361    * @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
 362    * If SceneView has IBL, IBL of newly added Model is also overridden.
 363    * To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
 364    *
 365    * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
 366    * @param[in] specularUrl cube map that can be used as a specular IBL source.
 367    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 368    */
 369   void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
 370
 371   /**
 372    * @brief Sets Scale Factor of Image Based Light Source.
 373    *
 374    * @SINCE_2_1.41
 375    * @note If SetImageBasedLightSource() method is called after this method, scaleFactor is overriden.
 376    * @note Default value is 1.0f.
 377    *
 378    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 379    */
 380   void SetImageBasedLightScaleFactor(float scaleFactor);
 381
 382   /**
 383    * @brief Gets Scale Factor of Image Based Light Source.
 384    * Default value is 1.0f.
 385    *
 386    * @SINCE_2_1.41
 387    * @return scale factor that controls light source intensity.
 388    */
 389   float GetImageBasedLightScaleFactor() const;
 390
 391   /**
 392    * @brief Gets Enabled Light Count of this SceneView
 393    *
 394    * @SINCE_2_2.32
 395    * @return The number of enabled light count;
 396    */
 397   uint32_t GetActivatedLightCount() const;
 398
 399   /**
 400    * @brief Sets whether to use FBO or not for the SceneView.
 401    * If useFramebuffer is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
 402    * If useFramebuffer is false, each item in SceneView is rendered on window directly.
 403    * Note that Toolkit::RenderEffect is not supported in this case.
 404    * Default is false.
 405    *
 406    * @SINCE_2_1.38
 407    * @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
 408    * If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
 409    *
 410    * @param[in] useFramebuffer True to use FBO for SceneView.
 411    */
 412   void UseFramebuffer(bool useFramebuffer);
 413
 414   /**
 415    * @brief Gets whether this SceneView uses Framebuffer or not.
 416    *
 417    * @SINCE_2_1.38
 418    * @return bool True if this SceneView uses Framebuffer.
 419    */
 420   bool IsUsingFramebuffer() const;
 421
 422   /**
 423    * @brief Sets SceneView's resolution manually.
 424    * @note This manual resolution is only available when the SceneView uses FBO for rendering by using UseFrameBuffer(true).
 425    * @note If the aspect ratio of input width/height is different with SceneView's aspect ratio, the rendered result is stretched to fill SceneView's area.
 426    *
 427    * @SINCE_2_3.2
 428    * @param[in] width The input width.
 429    * @param[in] height The input height.
 430    */
 431   void SetResolution(uint32_t width, uint32_t height);
 432
 433   /**
 434    * @brief Retrieves width of resolution of the SceneView.
 435    * @note If the SceneView not uses FBO, this method returns SceneView's width.
 436    *
 437    * @SINCE_2_3.2
 438    * @return Width value of resolution of the SceneView.
 439    */
 440   uint32_t GetResolutionWidth();
 441
 442   /**
 443    * @brief Retrieves height of resolution of the SceneView.
 444    * @note If the SceneView not uses FBO, this method returns SceneView's height.
 445    *
 446    * @SINCE_2_3.2
 447    * @return Height value of resolution of the SceneView.
 448    */
 449   uint32_t GetResolutionHeight();
 450
 451   /**
 452    * @brief Resets SceneView's resolution to the current size of SceneView.
 453    *
 454    * @SINCE_2_3.2
 455    */
 456   void ResetResolution();
 457
 458   /**
 459    * @brief Sets Multisampling level when we use Framebuffer.
 460    * Default is 0.
 461    *
 462    * @SINCE_2_2.12
 463    * @note Only applied if SceneView is using Framebuffer and Framebuffer Multisampling extension is supported.
 464    *
 465    * @param[in] multiSamplingLevel Level of multisampling if we use Framebuffer.
 466    */
 467   void SetFramebufferMultiSamplingLevel(uint8_t multiSamplingLevel);
 468
 469   /**
 470    * @brief Gets Multisampling level that user set.
 471    * Default is 0.
 472    *
 473    * @SINCE_2_2.12
 474    * @note This API doesn't check whether Multisampling extension is supported or not.
 475    *
 476    * @return MultisamplingLevel that user set.
 477    */
 478   uint8_t GetFramebufferMultiSamplingLevel() const;
 479
 480   /**
 481    * @brief Sets Skybox for this scene.
 482    * Skybox texture starts to be loaded when SceneView is onScene.
 483    * And Skybox texture is asynchronously loaded. When loading is finished, ResourceReady is emitted.
 484    *
 485    * @SINCE_2_2.0
 486    * @param[in] skyboxUrl image url for skybox.
 487    * @note Default SkyboxEnvironmentMapType is Cube Map. Use SetSkyboxEnvironmentMapType method to set type explicitly.
 488    */
 489   void SetSkybox(const std::string& skyboxUrl);
 490
 491   /**
 492    * @brief Sets Skybox environment map type for this skybox.
 493    * If skybox texture already starts to be loaded, when the type is changed, the load request is canceled and re-starts to load with new type.
 494    *
 495    * @SINCE_2_2.11
 496    * @param[in] skyboxEnvironmentMapType The environment type of skybox (by default it is cubemap).
 497    */
 498   void SetSkyboxEnvironmentMapType(Scene3D::EnvironmentMapType skyboxEnvironmentMapType);
 499
 500   /**
 501    * @brief Sets Skybox intensity.
 502    * The skybox intensity is multiplied to the color of skybox texture.
 503    * Default value is 1.0f.
 504    *
 505    * @SINCE_2_2.0
 506    * @note Intensity should be positive value.
 507    * @param[in] intensity Intensity value to be multiplied to the cube map color
 508    */
 509   void SetSkyboxIntensity(float intensity);
 510
 511   /**
 512    * @brief Gets Skybox intensity.
 513    * Default value is 1.0f.
 514    *
 515    * @SINCE_2_2.0
 516    * @return skybox intensity
 517    */
 518   float GetSkyboxIntensity() const;
 519
 520   /**
 521    * @brief Sets Orientation of Skybox.
 522    *
 523    * @SINCE_2_2.0
 524    * @param[in] orientation Quaternion for orientation of Skybox.
 525    */
 526   void SetSkyboxOrientation(const Quaternion& orientation);
 527
 528   /**
 529    * @brief Gets Skybox orientation.
 530    *
 531    * @SINCE_2_2.0
 532    * @return skybox orientation
 533    */
 534   Quaternion GetSkyboxOrientation() const;
 535
 536   /**
 537    * @brief Requests to capture this SceneView with the Camera.
 538    *
 539    * @SINCE_2_3.25
 540    * @param[in] camera CameraActor to be used for capture.
 541    * @param[in] size captured size.
 542    * @note The input camera should not be used for any other purpose during Capture.
 543    * (Simultaneous usage elsewhere may result in incorrect rendering.)
 544    * @note The camera is required to be added in this SceneView. (But should not be a selected camera.)
 545    * @note If the SceneView is disconnected from Scene, the left capture requests are canceled.
 546    * @return capture id that id unique value to distinguish each requiest.
 547    */
 548   int32_t Capture(Dali::CameraActor camera, const Vector2& size);
 549
 550   /**
 551    * @brief Get capture finished signal.
 552    *
 553    * @SINCE_2_3.25
 554    * @return finished signal instance.
 555    */
 556   CaptureFinishedSignalType& CaptureFinishedSignal();
 557
 558   /**
 559    * @brief Get camera transition finished signal.
 560    *
 561    * @SINCE_2_3.37
 562    * @return camera transition finished signal instance.
 563    */
 564   CameraTransitionFinishedSignalType& CameraTransitionFinishedSignal();
 565
 566 public: // Not intended for application developers
 567   /// @cond internal
 568   /**
 569    * @brief Creates a handle using the Toolkit::Internal implementation.
 570    *
 571    * @param[in] implementation The Control implementation
 572    */
 573   DALI_INTERNAL SceneView(Internal::SceneView& implementation);
 574
 575   /**
 576    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 577    *
 578    * @param[in] internal A pointer to the internal CustomActor
 579    */
 580   DALI_INTERNAL SceneView(Dali::Internal::CustomActor* internal);
 581   /// @endcond
 582 };
 583
 584 /**
 585  * @}
 586  */
 587 } // namespace Scene3D
 588
 589 } // namespace Dali
 590
 591 #endif // DALI_SCENE3D_SCENE_VIEW_H