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 // INTERNAL INCLUDES
  22 #include <dali-scene3d/public-api/api.h>
  23 #include <dali-scene3d/public-api/common/environment-map.h>
  24
  25 // EXTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27 #include <dali/public-api/actors/camera-actor.h>
  28 #include <dali/public-api/common/dali-common.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 Create an initialized SceneView.
 109    *
 110    * @SINCE_2_1.38
 111    * @return A handle to a newly allocated Dali resource
 112    */
 113   static SceneView New();
 114
 115   /**
 116    * @brief Creates an uninitialized SceneView.
 117    *
 118    * Only derived versions can be instantiated. Calling member
 119    * functions with an uninitialized Dali::Object is not allowed.
 120    *
 121    * @SINCE_2_1.38
 122    */
 123   SceneView();
 124
 125   /**
 126    * @brief Destructor.
 127    *
 128    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 129    *
 130    * @SINCE_2_1.38
 131    */
 132   ~SceneView();
 133
 134   /**
 135    * @brief Copy constructor.
 136    *
 137    * @SINCE_2_1.38
 138    * @param[in] sceneView Handle to an object
 139    */
 140   SceneView(const SceneView& sceneView);
 141
 142   /**
 143    * @brief Move constructor
 144    *
 145    * @SINCE_2_1.38
 146    * @param[in] rhs A reference to the moved handle
 147    */
 148   SceneView(SceneView&& rhs);
 149
 150   /**
 151    * @brief Assignment operator.
 152    *
 153    * @SINCE_2_1.38
 154    * @param[in] sceneView Handle to an object
 155    * @return reference to this
 156    */
 157   SceneView& operator=(const SceneView& sceneView);
 158
 159   /**
 160    * @brief Move assignment
 161    *
 162    * @SINCE_2_1.38
 163    * @param[in] rhs A reference to the moved handle
 164    * @return A reference to this
 165    */
 166   SceneView& operator=(SceneView&& rhs);
 167
 168   /**
 169    * @brief Downcasts an Object handle to SceneView.
 170    *
 171    * If handle points to a SceneView, the downcast produces valid handle.
 172    * If not, the returned handle is left uninitialized.
 173    *
 174    * @SINCE_2_1.38
 175    * @param[in] handle Handle to an object
 176    * @return Handle to a SceneView or an uninitialized handle
 177    */
 178   static SceneView DownCast(BaseHandle handle);
 179
 180   /**
 181    * @brief Adds a CameraActor to the SceneView
 182    * The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
 183    *
 184    * @SINCE_2_1.38
 185    * @note
 186    * AspectRatio property of CameraActor will be changed depending on the Size of this SceneView.
 187    *
 188    * For Perspective camera
 189    * The FieldOfView of Dali::CameraActor is for vertical fov.
 190    * When the size of the SceneView is changed, the vertical fov is maintained
 191    * and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
 192    *
 193    * For Orthographic camera
 194    * leftPlaneDistance, rightPlaneDistance, and bottomPlaneDistance properties are defined according to the topPlaneDistance and aspectRatio.
 195    *
 196    * @param[in] camera CameraActor added on this scene view.
 197    */
 198   void AddCamera(Dali::CameraActor camera);
 199
 200   /**
 201    * @brief Removes a CameraActor from this SceneView.
 202    *
 203    * @SINCE_2_1.38
 204    * @note If removed CameraActor is selected CameraActor,
 205    * first camera in the list is set to selected CameraActor.
 206    *
 207    * @param[in] camera CameraActor to be removed from this SceneView
 208    */
 209   void RemoveCamera(CameraActor camera);
 210
 211   /**
 212    * @brief Retrieves the number of cameras.
 213    *
 214    * @SINCE_2_1.38
 215    * @return Number of cameras those currently the SceneView contains.
 216    */
 217   uint32_t GetCameraCount() const;
 218
 219   /**
 220    * @brief Retrieves selected CameraActor.
 221    *
 222    * @SINCE_2_1.38
 223    * @return CameraActor currently used in SceneView as a selected CameraActor
 224    */
 225   CameraActor GetSelectedCamera() const;
 226
 227   /**
 228    * @brief Retrieves a CameraActor of the index.
 229    *
 230    * @SINCE_2_1.38
 231    * @param[in] index Index of CameraActor to be retrieved.
 232    *
 233    * @return CameraActor of the index
 234    */
 235   CameraActor GetCamera(uint32_t index) const;
 236
 237   /**
 238    * @brief Retrieves a CameraActor of the name.
 239    *
 240    * @SINCE_2_1.38
 241    * @param[in] name string keyword of CameraActor to be retrieved.
 242    *
 243    * @return CameraActor that has the name as a Dali::Actor::Property::NAME
 244    */
 245   CameraActor GetCamera(const std::string& name) const;
 246
 247   /**
 248    * @brief Makes SceneView use a CameraActor of index as a selected camera.
 249    *
 250    * @SINCE_2_1.38
 251    * @param[in] index Index of CameraActor to be used as a selected camera.
 252    */
 253   void SelectCamera(uint32_t index);
 254
 255   /**
 256    * @brief Makes SceneView use a CameraActor of a name as a selected camera.
 257    *
 258    * @SINCE_2_1.38
 259    * @param[in] name string keyword of CameraActor to be used as a selected camera.
 260    */
 261   void SelectCamera(const std::string& name);
 262
 263   /**
 264    * @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
 265    *
 266    * @SINCE_2_1.38
 267    * @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
 268    * If SceneView has IBL, IBL of newly added Model is also overridden.
 269    * To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
 270    *
 271    * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
 272    * @param[in] specularUrl cube map that can be used as a specular IBL source.
 273    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 274    */
 275   void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
 276
 277   /**
 278    * @brief Sets Scale Factor of Image Based Light Source.
 279    *
 280    * @SINCE_2_1.41
 281    * @note If SetImageBasedLightSource() or SetImageBasedLightTexture() method is called after this method, scaleFactor is overriden.
 282    * @note Default value is 1.0f.
 283    *
 284    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 285    */
 286   void SetImageBasedLightScaleFactor(float scaleFactor);
 287
 288   /**
 289    * @brief Gets Scale Factor of Image Based Light Source.
 290    * Default value is 1.0f.
 291    *
 292    * @SINCE_2_1.41
 293    * @return scale factor that controls light source intensity.
 294    */
 295   float GetImageBasedLightScaleFactor() const;
 296
 297   /**
 298    * @brief Sets whether to use FBO or not for the SceneView.
 299    * If useFramebuffer is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
 300    * If useFramebuffer is false, each item in SceneView is rendered on window directly.
 301    * Default is false.
 302    *
 303    * @SINCE_2_1.38
 304    * @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
 305    * If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
 306    *
 307    * @param[in] useFramebuffer True to use FBO for SceneView.
 308    */
 309   void UseFramebuffer(bool useFramebuffer);
 310
 311   /**
 312    * @brief Gets whether this SceneView uses Framebuffer or not.
 313    *
 314    * @SINCE_2_1.38
 315    * @return bool True if this SceneView uses Framebuffer.
 316    */
 317   bool IsUsingFramebuffer() const;
 318
 319   /**
 320    * @brief Sets Skybox for this scene.
 321    * Skybox texture starts to be loaded when SceneView is onScene.
 322    * And Skybox texture is asynchronously loaded. When loading is finished, ResourceReady is emitted.
 323    *
 324    * @SINCE_2_2.0
 325    * @param[in] skyboxUrl image url for skybox.
 326    * @note Default SkyboxEnvironmentMapType is Cube Map. Use SetSkyboxEnvironmentMapType method to set type explicitly.
 327    */
 328   void SetSkybox(const std::string& skyboxUrl);
 329
 330   /**
 331    * @brief Sets Skybox environment map type for this skybox.
 332    * 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.
 333    *
 334    * @SINCE_2_2.11
 335    * @param[in] skyboxEnvironmentMapType The environment type of skybox (by default it is cubemap).
 336    */
 337   void SetSkyboxEnvironmentMapType(Scene3D::EnvironmentMapType skyboxEnvironmentMapType);
 338
 339   /**
 340    * @brief Sets Skybox intensity.
 341    * The skybox intensity is multiplied to the color of skybox texture.
 342    * Default value is 1.0f.
 343    *
 344    * @SINCE_2_2.0
 345    * @note Intensity should be positive value.
 346    * @param[in] intensity Intensity value to be multiplied to the cube map color
 347    */
 348   void SetSkyboxIntensity(float intensity);
 349
 350   /**
 351    * @brief Gets Skybox intensity.
 352    * Default value is 1.0f.
 353    *
 354    * @SINCE_2_2.0
 355    * @return skybox intensity
 356    */
 357   float GetSkyboxIntensity() const;
 358
 359   /**
 360    * @brief Sets Orientation of Skybox.
 361    *
 362    * @SINCE_2_2.0
 363    * @param[in] orientation Quaternion for orientation of Skybox.
 364    */
 365   void SetSkyboxOrientation(const Quaternion& orientation);
 366
 367   /**
 368    * @brief Gets Skybox orientation.
 369    *
 370    * @SINCE_2_2.0
 371    * @return skybox orientation
 372    */
 373   Quaternion GetSkyboxOrientation() const;
 374
 375 public: // Not intended for application developers
 376   /// @cond internal
 377   /**
 378    * @brief Creates a handle using the Toolkit::Internal implementation.
 379    *
 380    * @param[in] implementation The Control implementation
 381    */
 382   DALI_INTERNAL SceneView(Internal::SceneView& implementation);
 383
 384   /**
 385    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 386    *
 387    * @param[in] internal A pointer to the internal CustomActor
 388    */
 389   DALI_INTERNAL SceneView(Dali::Internal::CustomActor* internal);
 390   /// @endcond
 391 };
 392
 393 /**
 394  * @}
 395  */
 396 } // namespace Scene3D
 397
 398 } // namespace Dali
 399
 400 #endif // DALI_SCENE3D_SCENE_VIEW_H