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) 2022 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
  24 // EXTERNAL INCLUDES
  25 #include <dali-toolkit/public-api/controls/control.h>
  26 #include <dali/public-api/actors/camera-actor.h>
  27 #include <dali/public-api/common/dali-common.h>
  28
  29 namespace Dali
  30 {
  31 namespace Scene3D
  32 {
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class SceneView;
  36 }
  37
  38 /**
  39  * @addtogroup dali_toolkit_controls_scene_view
  40  * @{
  41  */
  42
  43 /**
  44  * @brief SceneView is a Dali::Toolkit::Control to show multiple 3D objects in a single 3D scene.
  45  * Each SceneView has its own 3D space, and 3D objects added to SceneView are positioned in the space.
  46  * SceneView has a 3D root layer internally to trigger the depth test in the rendering process.
  47  * When an Actor is added to the SceneView with Add() method,
  48  * the Actor and its children are actually become child of the 3D layer automatically.
  49  *
  50  *  SceneView
  51  *      |
  52  * Dali::Layer(Layer::LAYER_3D)
  53  *      |
  54  *    Actor
  55  *
  56  * The children of the 3D root layer will be rendered with the SceneView's own CameraActor.
  57  *
  58  * SceneView can have multiple CameraActor and one of them is used to render the multiple objects as a Scene.
  59  * AddCamera(), RemoveCamera(), GetCamera(), and SelectCamera() are methods to manage CameraActors of the SceneView.
  60  * Users can place multiple cameras in a scene, either to show the entire scene or to show individual objects.
  61  * And the user can select the currently needed camera by using the SelectCamera() method.
  62  *
  63  * SceneView makes one built-in CameraActor by default.
  64  * The default CameraActor has index 0 and is not removed by using RemoveCamera() method.
  65  * Therefore, the minimum value returned by GetCameraCount() method is 1.
  66  *
  67  * If the size of SceneView is changed, Some properties of CameraActor that depend on the size can be changed too.
  68  * The changing properties are as follows: projectionMode, aspectRatio, leftPlaneDistance, rightPlaneDistance, topPlaneDistance, and bottomPlaneDistance.
  69  * Position, near/farPlaneDistance, and FieldOfView are maintained even if the size of the SceneView is changed.
  70  * The FieldOfView of Dali::CameraActor is for vertical fov. The horizontal fov is internally updated according to the SceneView size.
  71  *
  72  * The same light source is set for all Models added to SceneView, if SceneView has light source.
  73  * The SetImageBasedLightSource() method sets the same IBL to all Models added to the SceneView.
  74  * If any Model already has an IBL, it is replaced with the SceneView's IBL.
  75  *
  76  * SceneView provides an option to use FBO for rendering result with UseFramebuffer() method.
  77  * If it is false, SceneView is always drawn in the form of a rectangle on the default window surface directly.
  78  * It improves performance, but the SceneView is always drawn on top of other 2D objects regardless of Actor tree order.
  79  * And it will show wrong result in case the window's default CameraActor is transformed.
  80  * So, it is recommended not to change window's CameraActor.
  81  *
  82  * If FBO is used, the rendering result of SceneView is drawn on the FBO and it is mapped on the plane of the SceneView.
  83  * It decreases performance, but it is useful to show SceneView according to the rendering order with other Actors.
  84  * And it can be used in case window's CameraActor is transformed.
  85  *
  86  * And since SceneView is a Control, it can be placed together with other 2D UI components in the DALi window.
  87  *
  88  * @SINCE_2_1.38
  89  * @code
  90  *
  91  * Dali::Scene3D::SceneView sceneView = Dali::Scene3D::SceneView::New();
  92  * sceneView.SetProperty(Dali::Actor::Property::SIZE, Vector2(400, 400));
  93  * mWindow.Add(sceneView);
  94  *
  95  * Dali::Scene3D::Model model = Dali::Scene3D::Model::New(...);
  96  * sceneView.Add(model);
  97  *
  98  * CameraActor cameraActor = CameraActor::New();
  99  * sceneView.AddCamera(cameraActor);
 100  *
 101  * @endcode
 102  */
 103 class DALI_SCENE3D_API SceneView : public Dali::Toolkit::Control
 104 {
 105 public:
 106   /**
 107    * @brief Create an initialized SceneView.
 108    *
 109    * @SINCE_2_1.38
 110    * @return A handle to a newly allocated Dali resource
 111    */
 112   static SceneView New();
 113
 114   /**
 115    * @brief Creates an uninitialized SceneView.
 116    *
 117    * Only derived versions can be instantiated. Calling member
 118    * functions with an uninitialized Dali::Object is not allowed.
 119    *
 120    * @SINCE_2_1.38
 121    */
 122   SceneView();
 123
 124   /**
 125    * @brief Destructor.
 126    *
 127    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 128    *
 129    * @SINCE_2_1.38
 130    */
 131   ~SceneView();
 132
 133   /**
 134    * @brief Copy constructor.
 135    *
 136    * @SINCE_2_1.38
 137    * @param[in] sceneView Handle to an object
 138    */
 139   SceneView(const SceneView& sceneView);
 140
 141   /**
 142    * @brief Move constructor
 143    *
 144    * @SINCE_2_1.38
 145    * @param[in] rhs A reference to the moved handle
 146    */
 147   SceneView(SceneView&& rhs);
 148
 149   /**
 150    * @brief Assignment operator.
 151    *
 152    * @SINCE_2_1.38
 153    * @param[in] sceneView Handle to an object
 154    * @return reference to this
 155    */
 156   SceneView& operator=(const SceneView& sceneView);
 157
 158   /**
 159    * @brief Move assignment
 160    *
 161    * @SINCE_2_1.38
 162    * @param[in] rhs A reference to the moved handle
 163    * @return A reference to this
 164    */
 165   SceneView& operator=(SceneView&& rhs);
 166
 167   /**
 168    * @brief Downcasts an Object handle to SceneView.
 169    *
 170    * If handle points to a SceneView, the downcast produces valid handle.
 171    * If not, the returned handle is left uninitialized.
 172    *
 173    * @SINCE_2_1.38
 174    * @param[in] handle Handle to an object
 175    * @return Handle to a SceneView or an uninitialized handle
 176    */
 177   static SceneView DownCast(BaseHandle handle);
 178
 179   /**
 180    * @brief Adds a CameraActor to the SceneView
 181    * The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
 182    *
 183    * @SINCE_2_1.38
 184    * @note
 185    * AspectRatio property of CameraActor will be changed depending on the Size of this SceneView.
 186    *
 187    * For Perspective camera
 188    * The FieldOfView of Dali::CameraActor is for vertical fov.
 189    * When the size of the SceneView is changed, the vertical fov is maintained
 190    * and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
 191    *
 192    * For Orthographic camera
 193    * leftPlaneDistance, rightPlaneDistance, and bottomPlaneDistance properties are defined according to the topPlaneDistance and aspectRatio.
 194    *
 195    * @param[in] camera CameraActor added on this scene view.
 196    */
 197   void AddCamera(Dali::CameraActor camera);
 198
 199   /**
 200    * @brief Removes a CameraActor from this SceneView.
 201    *
 202    * @SINCE_2_1.38
 203    * @note If removed CameraActor is selected CameraActor,
 204    * first camera in the list is set to selected CameraActor.
 205    *
 206    * @param[in] camera CameraActor to be removed from this SceneView
 207    */
 208   void RemoveCamera(CameraActor camera);
 209
 210   /**
 211    * @brief Retrieves the number of cameras.
 212    *
 213    * @SINCE_2_1.38
 214    * @return Number of cameras those currently the SceneView contains.
 215    */
 216   uint32_t GetCameraCount() const;
 217
 218   /**
 219    * @brief Retrieves selected CameraActor.
 220    *
 221    * @SINCE_2_1.38
 222    * @return CameraActor currently used in SceneView as a selected CameraActor
 223    */
 224   CameraActor GetSelectedCamera() const;
 225
 226   /**
 227    * @brief Retrieves a CameraActor of the index.
 228    *
 229    * @SINCE_2_1.38
 230    * @param[in] index Index of CameraActor to be retrieved.
 231    *
 232    * @return CameraActor of the index
 233    */
 234   CameraActor GetCamera(uint32_t index) const;
 235
 236   /**
 237    * @brief Retrieves a CameraActor of the name.
 238    *
 239    * @SINCE_2_1.38
 240    * @param[in] name string keyword of CameraActor to be retrieved.
 241    *
 242    * @return CameraActor that has the name as a Dali::Actor::Property::NAME
 243    */
 244   CameraActor GetCamera(const std::string& name) const;
 245
 246   /**
 247    * @brief Makes SceneView use a CameraActor of index as a selected camera.
 248    *
 249    * @SINCE_2_1.38
 250    * @param[in] index Index of CameraActor to be used as a selected camera.
 251    */
 252   void SelectCamera(uint32_t index);
 253
 254   /**
 255    * @brief Makes SceneView use a CameraActor of a name as a selected camera.
 256    *
 257    * @SINCE_2_1.38
 258    * @param[in] name string keyword of CameraActor to be used as a selected camera.
 259    */
 260   void SelectCamera(const std::string& name);
 261
 262   /**
 263    * @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
 264    *
 265    * @SINCE_2_1.38
 266    * @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
 267    * If SceneView has IBL, IBL of newly added Model is also overridden.
 268    * To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
 269    *
 270    * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
 271    * @param[in] specularUrl cube map that can be used as a specular IBL source.
 272    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 273    */
 274   void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
 275
 276   /**
 277    * @brief Sets Scale Factor of Image Based Light Source.
 278    *
 279    * @SINCE_2_1.41
 280    * @note If SetImageBasedLightSource() or SetImageBasedLightTexture() method is called after this method, scaleFactor is overriden.
 281    * @note Default value is 1.0f.
 282    *
 283    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 284    */
 285   void SetImageBasedLightScaleFactor(float scaleFactor);
 286
 287   /**
 288    * @brief Gets Scale Factor of Image Based Light Source.
 289    * Default value is 1.0f.
 290    *
 291    * @SINCE_2_1.41
 292    * @return scale factor that controls light source intensity.
 293    */
 294   float GetImageBasedLightScaleFactor() const;
 295
 296   /**
 297    * @brief Sets whether to use FBO or not for the SceneView.
 298    * If useFramebuffer is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
 299    * If useFramebuffer is false, each item in SceneView is rendered on window directly.
 300    * Default is false.
 301    *
 302    * @SINCE_2_1.38
 303    * @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
 304    * If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
 305    *
 306    * @param[in] useFramebuffer True to use FBO for SceneView.
 307    */
 308   void UseFramebuffer(bool useFramebuffer);
 309
 310   /**
 311    * @brief Gets whether this SceneView uses Framebuffer or not.
 312    *
 313    * @SINCE_2_1.38
 314    * @return bool True if this SceneView uses Framebuffer.
 315    */
 316   bool IsUsingFramebuffer() const;
 317
 318   /**
 319    * @brief Sets Skybox for this scene.
 320    * Skybox texture is asynchronously loaded. When loading is finished, ResourceReady is emitted.
 321    *
 322    * @SINCE_2_2.0
 323    * @param[in] skyboxUrl Cube map image url for skybox.
 324    */
 325   void SetSkybox(const std::string& skyboxUrl);
 326
 327   /**
 328    * @brief Sets Skybox intensity.
 329    * The skybox intensity is multiplied to the color of skybox texture.
 330    * Default value is 1.0f.
 331    *
 332    * @SINCE_2_2.0
 333    * @note Intensity should be positive value.
 334    * @param[in] intensity Intensity value to be multiplied to the cube map color
 335    */
 336   void SetSkyboxIntensity(float intensity);
 337
 338   /**
 339    * @brief Gets Skybox intensity.
 340    * Default value is 1.0f.
 341    *
 342    * @SINCE_2_2.0
 343    * @return skybox intensity
 344    */
 345   float GetSkyboxIntensity() const;
 346
 347   /**
 348    * @brief Sets Orientation of Skybox.
 349    *
 350    * @SINCE_2_2.0
 351    * @param[in] orientation Quaternion for orientation of Skybox.
 352    */
 353   void SetSkyboxOrientation(const Quaternion& orientation);
 354
 355   /**
 356    * @brief Gets Skybox orientation.
 357    *
 358    * @SINCE_2_2.0
 359    * @return skybox orientation
 360    */
 361   Quaternion GetSkyboxOrientation() const;
 362
 363 public: // Not intended for application developers
 364   /// @cond internal
 365   /**
 366    * @brief Creates a handle using the Toolkit::Internal implementation.
 367    *
 368    * @param[in] implementation The Control implementation
 369    */
 370   DALI_INTERNAL SceneView(Internal::SceneView& implementation);
 371
 372   /**
 373    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 374    *
 375    * @param[in] internal A pointer to the internal CustomActor
 376    */
 377   DALI_INTERNAL SceneView(Dali::Internal::CustomActor* internal);
 378   /// @endcond
 379 };
 380
 381 /**
 382  * @}
 383  */
 384 } // namespace Scene3D
 385
 386 } // namespace Dali
 387
 388 #endif // DALI_SCENE3D_SCENE_VIEW_H