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