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) 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 <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  * @SINCE_2_1.38
  90  * @code
  91  *
  92  * Dali::Scene3D::SceneView sceneView = Dali::Scene3D::SceneView::New();
  93  * sceneView.SetProperty(Dali::Actor::Property::SIZE, Vector2(400, 400));
  94  * mWindow.Add(sceneView);
  95  *
  96  * Dali::Scene3D::Model model = Dali::Scene3D::Model::New(...);
  97  * sceneView.Add(model);
  98  *
  99  * CameraActor cameraActor = CameraActor::New();
 100  * sceneView.AddCamera(cameraActor);
 101  *
 102  * @endcode
 103  */
 104 class DALI_SCENE3D_API SceneView : public Dali::Toolkit::Control
 105 {
 106 public:
 107   /**
 108    * @brief The start and end property ranges for this control.
 109    * @SINCE_2_3.1
 110    */
 111   enum PropertyRange
 112   {
 113     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
 114     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000
 115   };
 116
 117   struct Property
 118   {
 119     enum
 120     {
 121       /**
 122        * @brief URL of a masking image
 123        * @details Name "alphaMaskUrl", type Property::STRING, URL of image to apply as
 124        * a mask after SceneView is drawn.
 125        * @note Alpha masking is only available when framebuffer is used.
 126        * @note Optional.
 127        */
 128       ALPHA_MASK_URL = PROPERTY_START_INDEX,
 129
 130       /**
 131        * @brief The scale factor to apply to the content image before masking
 132        * @details Name "maskContentScale", type Property::FLOAT, The scale factor
 133        * to apply to the content before masking. Note, scaled result is cropped to
 134        * the same size as the alpha mask.
 135        * @note Optional.
 136        */
 137       MASK_CONTENT_SCALE,
 138
 139       /**
 140        * @brief Whether to crop rendered result to mask or scale mask to fit result
 141        * @details Name "cropToMask", type Property::BOOLEAN, True if the rendered result should
 142        * be cropped to match the mask size, or false if the result should remain the same size.
 143        * @note Optional, Default true
 144        * @note If this is false, then the mask is scaled to fit the rendered result before being applied.
 145        */
 146       CROP_TO_MASK,
 147     };
 148   };
 149
 150 public:
 151   /**
 152    * @brief Create an initialized SceneView.
 153    *
 154    * @SINCE_2_1.38
 155    * @return A handle to a newly allocated Dali resource
 156    */
 157   static SceneView New();
 158
 159   /**
 160    * @brief Creates an uninitialized SceneView.
 161    *
 162    * Only derived versions can be instantiated. Calling member
 163    * functions with an uninitialized Dali::Object is not allowed.
 164    *
 165    * @SINCE_2_1.38
 166    */
 167   SceneView();
 168
 169   /**
 170    * @brief Destructor.
 171    *
 172    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 173    *
 174    * @SINCE_2_1.38
 175    */
 176   ~SceneView();
 177
 178   /**
 179    * @brief Copy constructor.
 180    *
 181    * @SINCE_2_1.38
 182    * @param[in] sceneView Handle to an object
 183    */
 184   SceneView(const SceneView& sceneView);
 185
 186   /**
 187    * @brief Move constructor
 188    *
 189    * @SINCE_2_1.38
 190    * @param[in] rhs A reference to the moved handle
 191    */
 192   SceneView(SceneView&& rhs) noexcept;
 193
 194   /**
 195    * @brief Assignment operator.
 196    *
 197    * @SINCE_2_1.38
 198    * @param[in] sceneView Handle to an object
 199    * @return reference to this
 200    */
 201   SceneView& operator=(const SceneView& sceneView);
 202
 203   /**
 204    * @brief Move assignment
 205    *
 206    * @SINCE_2_1.38
 207    * @param[in] rhs A reference to the moved handle
 208    * @return A reference to this
 209    */
 210   SceneView& operator=(SceneView&& rhs) noexcept;
 211
 212   /**
 213    * @brief Downcasts an Object handle to SceneView.
 214    *
 215    * If handle points to a SceneView, the downcast produces valid handle.
 216    * If not, the returned handle is left uninitialized.
 217    *
 218    * @SINCE_2_1.38
 219    * @param[in] handle Handle to an object
 220    * @return Handle to a SceneView or an uninitialized handle
 221    */
 222   static SceneView DownCast(BaseHandle handle);
 223
 224   /**
 225    * @brief Adds a CameraActor to the SceneView
 226    * The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
 227    *
 228    * @SINCE_2_1.38
 229    * @note
 230    * AspectRatio property of CameraActor will be changed depending on the Size of this SceneView.
 231    *
 232    * For Perspective camera
 233    * The FieldOfView of Dali::CameraActor is for vertical fov.
 234    * When the size of the SceneView is changed, the vertical fov is maintained
 235    * and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
 236    *
 237    * For Orthographic camera
 238    * leftPlaneDistance, rightPlaneDistance, and bottomPlaneDistance properties are defined according to the topPlaneDistance and aspectRatio.
 239    *
 240    * @param[in] camera CameraActor added on this scene view.
 241    */
 242   void AddCamera(Dali::CameraActor camera);
 243
 244   /**
 245    * @brief Removes a CameraActor from this SceneView.
 246    *
 247    * @SINCE_2_1.38
 248    * @note If removed CameraActor is selected CameraActor,
 249    * first camera in the list is set to selected CameraActor.
 250    *
 251    * @param[in] camera CameraActor to be removed from this SceneView
 252    */
 253   void RemoveCamera(CameraActor camera);
 254
 255   /**
 256    * @brief Retrieves the number of cameras.
 257    *
 258    * @SINCE_2_1.38
 259    * @return Number of cameras those currently the SceneView contains.
 260    */
 261   uint32_t GetCameraCount() const;
 262
 263   /**
 264    * @brief Retrieves selected CameraActor.
 265    *
 266    * @SINCE_2_1.38
 267    * @return CameraActor currently used in SceneView as a selected CameraActor
 268    */
 269   CameraActor GetSelectedCamera() const;
 270
 271   /**
 272    * @brief Retrieves a CameraActor of the index.
 273    *
 274    * @SINCE_2_1.38
 275    * @param[in] index Index of CameraActor to be retrieved.
 276    *
 277    * @return CameraActor of the index
 278    */
 279   CameraActor GetCamera(uint32_t index) const;
 280
 281   /**
 282    * @brief Retrieves a CameraActor of the name.
 283    *
 284    * @SINCE_2_1.38
 285    * @param[in] name string keyword of CameraActor to be retrieved.
 286    *
 287    * @return CameraActor that has the name as a Dali::Actor::Property::NAME
 288    */
 289   CameraActor GetCamera(const std::string& name) const;
 290
 291   /**
 292    * @brief Makes SceneView use a CameraActor of index as a selected camera.
 293    *
 294    * @SINCE_2_1.38
 295    * @param[in] index Index of CameraActor to be used as a selected camera.
 296    */
 297   void SelectCamera(uint32_t index);
 298
 299   /**
 300    * @brief Makes SceneView use a CameraActor of a name as a selected camera.
 301    *
 302    * @SINCE_2_1.38
 303    * @param[in] name string keyword of CameraActor to be used as a selected camera.
 304    */
 305   void SelectCamera(const std::string& name);
 306
 307   /**
 308    * @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
 309    *
 310    * @SINCE_2_1.38
 311    * @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
 312    * If SceneView has IBL, IBL of newly added Model is also overridden.
 313    * To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
 314    *
 315    * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
 316    * @param[in] specularUrl cube map that can be used as a specular IBL source.
 317    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 318    */
 319   void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
 320
 321   /**
 322    * @brief Sets Scale Factor of Image Based Light Source.
 323    *
 324    * @SINCE_2_1.41
 325    * @note If SetImageBasedLightSource() method is called after this method, scaleFactor is overriden.
 326    * @note Default value is 1.0f.
 327    *
 328    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 329    */
 330   void SetImageBasedLightScaleFactor(float scaleFactor);
 331
 332   /**
 333    * @brief Gets Scale Factor of Image Based Light Source.
 334    * Default value is 1.0f.
 335    *
 336    * @SINCE_2_1.41
 337    * @return scale factor that controls light source intensity.
 338    */
 339   float GetImageBasedLightScaleFactor() const;
 340
 341   /**
 342    * @brief Gets Enabled Light Count of this SceneView
 343    *
 344    * @SINCE_2_2.32
 345    * @return The number of enabled light count;
 346    */
 347   uint32_t GetActivatedLightCount() const;
 348
 349   /**
 350    * @brief Sets whether to use FBO or not for the SceneView.
 351    * If useFramebuffer is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
 352    * If useFramebuffer is false, each item in SceneView is rendered on window directly.
 353    * Default is false.
 354    *
 355    * @SINCE_2_1.38
 356    * @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
 357    * If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
 358    *
 359    * @param[in] useFramebuffer True to use FBO for SceneView.
 360    */
 361   void UseFramebuffer(bool useFramebuffer);
 362
 363   /**
 364    * @brief Gets whether this SceneView uses Framebuffer or not.
 365    *
 366    * @SINCE_2_1.38
 367    * @return bool True if this SceneView uses Framebuffer.
 368    */
 369   bool IsUsingFramebuffer() const;
 370
 371   /**
 372    * @brief Sets Multisampling level when we use Framebuffer.
 373    * Default is 0.
 374    *
 375    * @SINCE_2_2.12
 376    * @note Only applied if SceneView is using Framebuffer and Framebuffer Multisampling extension is supported.
 377    *
 378    * @param[in] multiSamplingLevel Level of multisampling if we use Framebuffer.
 379    */
 380   void SetFramebufferMultiSamplingLevel(uint8_t multiSamplingLevel);
 381
 382   /**
 383    * @brief Gets Multisampling level that user set.
 384    * Default is 0.
 385    *
 386    * @SINCE_2_2.12
 387    * @note This API doesn't check whether Multisampling extension is supported or not.
 388    *
 389    * @return MultisamplingLevel that user set.
 390    */
 391   uint8_t GetFramebufferMultiSamplingLevel() const;
 392
 393   /**
 394    * @brief Sets Skybox for this scene.
 395    * Skybox texture starts to be loaded when SceneView is onScene.
 396    * And Skybox texture is asynchronously loaded. When loading is finished, ResourceReady is emitted.
 397    *
 398    * @SINCE_2_2.0
 399    * @param[in] skyboxUrl image url for skybox.
 400    * @note Default SkyboxEnvironmentMapType is Cube Map. Use SetSkyboxEnvironmentMapType method to set type explicitly.
 401    */
 402   void SetSkybox(const std::string& skyboxUrl);
 403
 404   /**
 405    * @brief Sets Skybox environment map type for this skybox.
 406    * 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.
 407    *
 408    * @SINCE_2_2.11
 409    * @param[in] skyboxEnvironmentMapType The environment type of skybox (by default it is cubemap).
 410    */
 411   void SetSkyboxEnvironmentMapType(Scene3D::EnvironmentMapType skyboxEnvironmentMapType);
 412
 413   /**
 414    * @brief Sets Skybox intensity.
 415    * The skybox intensity is multiplied to the color of skybox texture.
 416    * Default value is 1.0f.
 417    *
 418    * @SINCE_2_2.0
 419    * @note Intensity should be positive value.
 420    * @param[in] intensity Intensity value to be multiplied to the cube map color
 421    */
 422   void SetSkyboxIntensity(float intensity);
 423
 424   /**
 425    * @brief Gets Skybox intensity.
 426    * Default value is 1.0f.
 427    *
 428    * @SINCE_2_2.0
 429    * @return skybox intensity
 430    */
 431   float GetSkyboxIntensity() const;
 432
 433   /**
 434    * @brief Sets Orientation of Skybox.
 435    *
 436    * @SINCE_2_2.0
 437    * @param[in] orientation Quaternion for orientation of Skybox.
 438    */
 439   void SetSkyboxOrientation(const Quaternion& orientation);
 440
 441   /**
 442    * @brief Gets Skybox orientation.
 443    *
 444    * @SINCE_2_2.0
 445    * @return skybox orientation
 446    */
 447   Quaternion GetSkyboxOrientation() const;
 448
 449 public: // Not intended for application developers
 450   /// @cond internal
 451   /**
 452    * @brief Creates a handle using the Toolkit::Internal implementation.
 453    *
 454    * @param[in] implementation The Control implementation
 455    */
 456   DALI_INTERNAL SceneView(Internal::SceneView& implementation);
 457
 458   /**
 459    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 460    *
 461    * @param[in] internal A pointer to the internal CustomActor
 462    */
 463   DALI_INTERNAL SceneView(Dali::Internal::CustomActor* internal);
 464   /// @endcond
 465 };
 466
 467 /**
 468  * @}
 469  */
 470 } // namespace Scene3D
 471
 472 } // namespace Dali
 473
 474 #endif // DALI_SCENE3D_SCENE_VIEW_H