#define DALI_SCENE3D_SCENE_VIEW_H
/*
- * Copyright (c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2024 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*
*/
-// INTERNAL INCLUDES
-#include <dali-scene3d/public-api/api.h>
-
// EXTERNAL INCLUDES
#include <dali-toolkit/public-api/controls/control.h>
#include <dali/public-api/actors/camera-actor.h>
#include <dali/public-api/common/dali-common.h>
+// INTERNAL INCLUDES
+#include <dali-scene3d/public-api/api.h>
+#include <dali-scene3d/public-api/common/environment-map.h>
+
namespace Dali
{
namespace Scene3D
* Users can place multiple cameras in a scene, either to show the entire scene or to show individual objects.
* And the user can select the currently needed camera by using the SelectCamera() method.
*
- * SceneView has one CameraActor built-in by default at the (0, 0, -z).
+ * SceneView makes one built-in CameraActor by default.
* The default CameraActor has index 0 and is not removed by using RemoveCamera() method.
* Therefore, the minimum value returned by GetCameraCount() method is 1.
*
*
* And since SceneView is a Control, it can be placed together with other 2D UI components in the DALi window.
*
+ * @note We support to render model well only if glsl version is higher than 300.
+ *
+ * @SINCE_2_1.38
* @code
*
* Dali::Scene3D::SceneView sceneView = Dali::Scene3D::SceneView::New();
* sceneView.SetProperty(Dali::Actor::Property::SIZE, Vector2(400, 400));
* mWindow.Add(sceneView);
*
- * Dali::Scene3D::ModelView model = Dali::Scene3D::ModelView::New(...);
+ * Dali::Scene3D::Model model = Dali::Scene3D::Model::New(...);
* sceneView.Add(model);
*
* CameraActor cameraActor = CameraActor::New();
- * // Setting CameraActor.
* sceneView.AddCamera(cameraActor);
*
* @endcode
{
public:
/**
+ * @brief The start and end property ranges for this control.
+ * @SINCE_2_3.1
+ */
+ enum PropertyRange
+ {
+ PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
+ PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000
+ };
+
+ struct Property
+ {
+ enum
+ {
+ /**
+ * @brief URL of a masking image
+ * @details Name "alphaMaskUrl", type Property::STRING, URL of image to apply as
+ * a mask after SceneView is drawn.
+ * @note Alpha masking is only available when framebuffer is used.
+ * @note Optional.
+ */
+ ALPHA_MASK_URL = PROPERTY_START_INDEX,
+
+ /**
+ * @brief The scale factor to apply to the content image before masking
+ * @details Name "maskContentScale", type Property::FLOAT, The scale factor
+ * to apply to the content before masking. Note, scaled result is cropped to
+ * the same size as the alpha mask.
+ * @note Optional.
+ */
+ MASK_CONTENT_SCALE,
+
+ /**
+ * @brief Whether to crop rendered result to mask or scale mask to fit result
+ * @details Name "cropToMask", type Property::BOOLEAN, True if the rendered result should
+ * be cropped to match the mask size, or false if the result should remain the same size.
+ * @note Optional, Default true
+ * @note If this is false, then the mask is scaled to fit the rendered result before being applied.
+ */
+ CROP_TO_MASK,
+ };
+ };
+
+public:
+ /**
* @brief Create an initialized SceneView.
+ *
+ * @SINCE_2_1.38
* @return A handle to a newly allocated Dali resource
*/
static SceneView New();
*
* Only derived versions can be instantiated. Calling member
* functions with an uninitialized Dali::Object is not allowed.
+ *
+ * @SINCE_2_1.38
*/
SceneView();
* @brief Destructor.
*
* This is non-virtual since derived Handle types must not contain data or virtual methods.
+ *
+ * @SINCE_2_1.38
*/
~SceneView();
/**
* @brief Copy constructor.
+ *
+ * @SINCE_2_1.38
* @param[in] sceneView Handle to an object
*/
SceneView(const SceneView& sceneView);
/**
* @brief Move constructor
*
+ * @SINCE_2_1.38
* @param[in] rhs A reference to the moved handle
*/
- SceneView(SceneView&& rhs);
+ SceneView(SceneView&& rhs) noexcept;
/**
* @brief Assignment operator.
+ *
+ * @SINCE_2_1.38
* @param[in] sceneView Handle to an object
* @return reference to this
*/
/**
* @brief Move assignment
*
+ * @SINCE_2_1.38
* @param[in] rhs A reference to the moved handle
* @return A reference to this
*/
- SceneView& operator=(SceneView&& rhs);
+ SceneView& operator=(SceneView&& rhs) noexcept;
/**
* @brief Downcasts an Object handle to SceneView.
* If handle points to a SceneView, the downcast produces valid handle.
* If not, the returned handle is left uninitialized.
*
+ * @SINCE_2_1.38
* @param[in] handle Handle to an object
* @return Handle to a SceneView or an uninitialized handle
*/
* @brief Adds a CameraActor to the SceneView
* The CameraActor can be used as a selected camera to render the scene by using SelectCamera(uint32_t) or SelectCamera(std::string)
*
- * @note Some properties of the CameraActor will be change depending on the Size of this SceneView.
- * Those properties are as follows:
- * projectionMode, aspectRatio, nearPlaneDistance, farPlaneDistance, leftPlaneDistance, rightPlaneDistance, topPlaneDistance, and bottomPlaneDistance.
+ * @SINCE_2_1.38
+ * @note
+ * AspectRatio property of CameraActor will be changed depending on the Size of this SceneView.
*
+ * For Perspective camera
* The FieldOfView of Dali::CameraActor is for vertical fov.
* When the size of the SceneView is changed, the vertical fov is maintained
* and the horizontal fov is automatically calculated according to the SceneView's aspect ratio.
*
+ * For Orthographic camera
+ * leftPlaneDistance, rightPlaneDistance, and bottomPlaneDistance properties are defined according to the topPlaneDistance and aspectRatio.
+ *
* @param[in] camera CameraActor added on this scene view.
*/
void AddCamera(Dali::CameraActor camera);
/**
* @brief Removes a CameraActor from this SceneView.
+ *
+ * @SINCE_2_1.38
* @note If removed CameraActor is selected CameraActor,
* first camera in the list is set to selected CameraActor.
*
/**
* @brief Retrieves the number of cameras.
*
+ * @SINCE_2_1.38
* @return Number of cameras those currently the SceneView contains.
*/
- uint32_t GetCameraCount();
+ uint32_t GetCameraCount() const;
/**
* @brief Retrieves selected CameraActor.
*
+ * @SINCE_2_1.38
* @return CameraActor currently used in SceneView as a selected CameraActor
*/
- CameraActor GetSelectedCamera();
+ CameraActor GetSelectedCamera() const;
/**
* @brief Retrieves a CameraActor of the index.
*
+ * @SINCE_2_1.38
* @param[in] index Index of CameraActor to be retrieved.
*
* @return CameraActor of the index
*/
- CameraActor GetCamera(uint32_t index);
+ CameraActor GetCamera(uint32_t index) const;
/**
* @brief Retrieves a CameraActor of the name.
*
+ * @SINCE_2_1.38
* @param[in] name string keyword of CameraActor to be retrieved.
*
* @return CameraActor that has the name as a Dali::Actor::Property::NAME
*/
- CameraActor GetCamera(const std::string& name);
+ CameraActor GetCamera(const std::string& name) const;
/**
* @brief Makes SceneView use a CameraActor of index as a selected camera.
*
+ * @SINCE_2_1.38
* @param[in] index Index of CameraActor to be used as a selected camera.
*/
void SelectCamera(uint32_t index);
/**
* @brief Makes SceneView use a CameraActor of a name as a selected camera.
*
+ * @SINCE_2_1.38
* @param[in] name string keyword of CameraActor to be used as a selected camera.
*/
void SelectCamera(const std::string& name);
/**
* @brief Sets Image Based Light Source to apply it on the all Models those added on this SceneView.
*
+ * @SINCE_2_1.38
* @note If any Models already have IBL, they are batch-overridden with the SceneView's IBL.
* If SceneView has IBL, IBL of newly added Model is also overridden.
* To set indivisual IBL for each Model, the Model's IBL should be set after the SceneView's IBL.
*
- * @param[in] diffuse cube map that can be used as a diffuse IBL source.
- * @param[in] specular cube map that can be used as a specular IBL source.
+ * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
+ * @param[in] specularUrl cube map that can be used as a specular IBL source.
* @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
*/
- void SetImageBasedLightSource(const std::string& diffuse, const std::string& specular, float scaleFactor = 1.0f);
+ void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
+
+ /**
+ * @brief Sets Scale Factor of Image Based Light Source.
+ *
+ * @SINCE_2_1.41
+ * @note If SetImageBasedLightSource() method is called after this method, scaleFactor is overriden.
+ * @note Default value is 1.0f.
+ *
+ * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
+ */
+ void SetImageBasedLightScaleFactor(float scaleFactor);
+
+ /**
+ * @brief Gets Scale Factor of Image Based Light Source.
+ * Default value is 1.0f.
+ *
+ * @SINCE_2_1.41
+ * @return scale factor that controls light source intensity.
+ */
+ float GetImageBasedLightScaleFactor() const;
+
+ /**
+ * @brief Gets Enabled Light Count of this SceneView
+ *
+ * @SINCE_2_2.32
+ * @return The number of enabled light count;
+ */
+ uint32_t GetActivatedLightCount() const;
/**
* @brief Sets whether to use FBO or not for the SceneView.
* If useFramebuffer is false, each item in SceneView is rendered on window directly.
* Default is false.
*
+ * @SINCE_2_1.38
* @note If useFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
* If useFramebuffer is false, performance is become better but SceneView is rendered on top of the other 2D Actors regardless tree order.
*
/**
* @brief Gets whether this SceneView uses Framebuffer or not.
*
+ * @SINCE_2_1.38
* @return bool True if this SceneView uses Framebuffer.
*/
- bool IsUsingFramebuffer();
+ bool IsUsingFramebuffer() const;
+
+ /**
+ * @brief Sets SceneView's resolution manually.
+ * @note This manual resolution is only available when the SceneView uses FBO for rendering by using UseFrameBuffer(true).
+ * @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.
+ *
+ * @SINCE_2_3.2
+ * @param[in] width The input width.
+ * @param[in] height The input height.
+ */
+ void SetResolution(uint32_t width, uint32_t height);
+
+ /**
+ * @brief Retrieves width of resolution of the SceneView.
+ * @note If the SceneView not uses FBO, this method returns SceneView's width.
+ *
+ * @SINCE_2_3.2
+ * @return Width value of resolution of the SceneView.
+ */
+ uint32_t GetResolutionWidth();
+
+ /**
+ * @brief Retrieves height of resolution of the SceneView.
+ * @note If the SceneView not uses FBO, this method returns SceneView's height.
+ *
+ * @SINCE_2_3.2
+ * @return Height value of resolution of the SceneView.
+ */
+ uint32_t GetResolutionHeight();
+
+ /**
+ * @brief Resets SceneView's resolution to the current size of SceneView.
+ *
+ * @SINCE_2_3.2
+ */
+ void ResetResolution();
+
+ /**
+ * @brief Sets Multisampling level when we use Framebuffer.
+ * Default is 0.
+ *
+ * @SINCE_2_2.12
+ * @note Only applied if SceneView is using Framebuffer and Framebuffer Multisampling extension is supported.
+ *
+ * @param[in] multiSamplingLevel Level of multisampling if we use Framebuffer.
+ */
+ void SetFramebufferMultiSamplingLevel(uint8_t multiSamplingLevel);
+
+ /**
+ * @brief Gets Multisampling level that user set.
+ * Default is 0.
+ *
+ * @SINCE_2_2.12
+ * @note This API doesn't check whether Multisampling extension is supported or not.
+ *
+ * @return MultisamplingLevel that user set.
+ */
+ uint8_t GetFramebufferMultiSamplingLevel() const;
+
+ /**
+ * @brief Sets Skybox for this scene.
+ * Skybox texture starts to be loaded when SceneView is onScene.
+ * And Skybox texture is asynchronously loaded. When loading is finished, ResourceReady is emitted.
+ *
+ * @SINCE_2_2.0
+ * @param[in] skyboxUrl image url for skybox.
+ * @note Default SkyboxEnvironmentMapType is Cube Map. Use SetSkyboxEnvironmentMapType method to set type explicitly.
+ */
+ void SetSkybox(const std::string& skyboxUrl);
+
+ /**
+ * @brief Sets Skybox environment map type for this skybox.
+ * 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.
+ *
+ * @SINCE_2_2.11
+ * @param[in] skyboxEnvironmentMapType The environment type of skybox (by default it is cubemap).
+ */
+ void SetSkyboxEnvironmentMapType(Scene3D::EnvironmentMapType skyboxEnvironmentMapType);
+
+ /**
+ * @brief Sets Skybox intensity.
+ * The skybox intensity is multiplied to the color of skybox texture.
+ * Default value is 1.0f.
+ *
+ * @SINCE_2_2.0
+ * @note Intensity should be positive value.
+ * @param[in] intensity Intensity value to be multiplied to the cube map color
+ */
+ void SetSkyboxIntensity(float intensity);
+
+ /**
+ * @brief Gets Skybox intensity.
+ * Default value is 1.0f.
+ *
+ * @SINCE_2_2.0
+ * @return skybox intensity
+ */
+ float GetSkyboxIntensity() const;
+
+ /**
+ * @brief Sets Orientation of Skybox.
+ *
+ * @SINCE_2_2.0
+ * @param[in] orientation Quaternion for orientation of Skybox.
+ */
+ void SetSkyboxOrientation(const Quaternion& orientation);
+
+ /**
+ * @brief Gets Skybox orientation.
+ *
+ * @SINCE_2_2.0
+ * @return skybox orientation
+ */
+ Quaternion GetSkyboxOrientation() const;
public: // Not intended for application developers
/// @cond internal