1 #ifndef DALI_SCENE3D_SCENE_VIEW_H
2 #define DALI_SCENE3D_SCENE_VIEW_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-scene3d/public-api/api.h>
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>
33 namespace Internal DALI_INTERNAL
39 * @addtogroup dali_toolkit_controls_scene_view
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.
52 * Dali::Layer(Layer::LAYER_3D)
56 * The children of the 3D root layer will be rendered with the SceneView's own CameraActor.
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.
63 * SceneView has one CameraActor built-in by default at the (0, 0, -z).
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.
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.
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.
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.
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.
86 * And since SceneView is a Control, it can be placed together with other 2D UI components in the DALi window.
90 * Dali::Scene3D::SceneView sceneView = Dali::Scene3D::SceneView::New();
91 * sceneView.SetProperty(Dali::Actor::Property::SIZE, Vector2(400, 400));
92 * mWindow.Add(sceneView);
94 * Dali::Scene3D::ModelView model = Dali::Scene3D::ModelView::New(...);
95 * sceneView.Add(model);
97 * CameraActor cameraActor = CameraActor::New();
98 * // Setting CameraActor.
99 * sceneView.AddCamera(cameraActor);
103 class DALI_SCENE3D_API SceneView : public Dali::Toolkit::Control
107 * @brief Create an initialized SceneView.
108 * @return A handle to a newly allocated Dali resource
110 static SceneView New();
113 * @brief Creates an uninitialized SceneView.
115 * Only derived versions can be instantiated. Calling member
116 * functions with an uninitialized Dali::Object is not allowed.
123 * This is non-virtual since derived Handle types must not contain data or virtual methods.
128 * @brief Copy constructor.
129 * @param[in] sceneView Handle to an object
131 SceneView(const SceneView& sceneView);
134 * @brief Move constructor
136 * @param[in] rhs A reference to the moved handle
138 SceneView(SceneView&& rhs);
141 * @brief Assignment operator.
142 * @param[in] sceneView Handle to an object
143 * @return reference to this
145 SceneView& operator=(const SceneView& sceneView);
148 * @brief Move assignment
150 * @param[in] rhs A reference to the moved handle
151 * @return A reference to this
153 SceneView& operator=(SceneView&& rhs);
156 * @brief Downcasts an Object handle to SceneView.
158 * If handle points to a SceneView, the downcast produces valid handle.
159 * If not, the returned handle is left uninitialized.
161 * @param[in] handle Handle to an object
162 * @return Handle to a SceneView or an uninitialized handle
164 static SceneView DownCast(BaseHandle handle);
167 * @brief Adds a CameraActor to the SceneView
168 * The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
170 * @note Some properties of the CameraActor will be change depending on the Size of this SceneView.
171 * Those properties are as follows:
172 * projectionMode, aspectRatio, nearPlaneDistance, farPlaneDistance, leftPlaneDistance, rightPlaneDistance, topPlaneDistance, and bottomPlaneDistance.
174 * The FieldOfView of Dali::CameraActor is for vertical fov.
175 * When the size of the SceneView is changed, the vertical fov is maintained
176 * and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
178 * @param[in] camera CameraActor added on this scene view.
180 void AddCamera(Dali::CameraActor camera);
183 * @brief Removes a CameraActor from this SceneView.
184 * @note If removed CameraActor is selected CameraActor,
185 * first camera in the list is set to selected CameraActor.
187 * @param[in] camera CameraActor to be removed from this SceneView
189 void RemoveCamera(CameraActor camera);
192 * @brief Retrieves the number of cameras.
194 * @return Number of cameras those currently the SceneView contains.
196 uint32_t GetCameraCount();
199 * @brief Retrieves selected CameraActor.
201 * @return CameraActor currently used in SceneView as a selected CameraActor
203 CameraActor GetSelectedCamera();
206 * @brief Retrieves a CameraActor of the index.
208 * @param[in] index Index of CameraActor to be retrieved.
210 * @return CameraActor of the index
212 CameraActor GetCamera(uint32_t index);
215 * @brief Retrieves a CameraActor of the name.
217 * @param[in] name string keyword of CameraActor to be retrieved.
219 * @return CameraActor that has the name as a Dali::Actor::Property::NAME
221 CameraActor GetCamera(const std::string& name);
224 * @brief Makes SceneView use a CameraActor of index as a selected camera.
226 * @param[in] index Index of CameraActor to be used as a selected camera.
228 void SelectCamera(uint32_t index);
231 * @brief Makes SceneView use a CameraActor of a name as a selected camera.
233 * @param[in] name string keyword of CameraActor to be used as a selected camera.
235 void SelectCamera(const std::string& name);
238 * @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
240 * @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
241 * If SceneView has IBL, IBL of newly added Model is also overridden.
242 * To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
244 * @param[in] diffuse cube map that can be used as a diffuse IBL source.
245 * @param[in] specular cube map that can be used as a specular IBL source.
246 * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
248 void SetImageBasedLightSource(const std::string& diffuse, const std::string& specular, float scaleFactor = 1.0f);
251 * @brief Sets whether to use FBO or not for the SceneView.
252 * If useFramebuffer is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
253 * If useFramebuffer is false, each item in SceneView is rendered on window directly.
256 * @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
257 * If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
259 * @param[in] useFramebuffer True to use FBO for SceneView.
261 void UseFramebuffer(bool useFramebuffer);
264 * @brief Gets whether this SceneView uses Framebuffer or not.
266 * @return bool True if this SceneView uses Framebuffer.
268 bool IsUsingFramebuffer();
270 public: // Not intended for application developers
273 * @brief Creates a handle using the Toolkit::Internal implementation.
275 * @param[in] implementation The Control implementation
277 DALI_INTERNAL SceneView(Internal::SceneView& implementation);
280 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
282 * @param[in] internal A pointer to the internal CustomActor
284 DALI_INTERNAL SceneView(Dali::Internal::CustomActor* internal);
291 } // namespace Scene3D
295 #endif // DALI_SCENE3D_SCENE_VIEW_H