dali-scene3d/public-api/light/light.h

   1 #ifndef DALI_SCENE3D_LIGHT_H
   2 #define DALI_SCENE3D_LIGHT_H
   3
   4 /*
   5  * Copyright (c) 2024 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/common/dali-common.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-scene3d/public-api/api.h>
  27
  28 namespace Dali
  29 {
  30 namespace Scene3D
  31 {
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class Light;
  35 }
  36
  37 /**
  38  * @addtogroup dali_toolkit_controls_light
  39  * @{
  40  */
  41
  42 /**
  43  * @brief This class is to define 3D Light source.
  44  * Currently this Light class supports Directional Light that lits every position from the same direction. (e.g, Sun light)
  45  * If a Light object is added on SceneView, the 3D objects in the SceneView are shined the Light.
  46  * DALi Scene3D limits the maximum enabled light count per each SceneView.
  47  * Currently the maximum number is set to 5, and it can be retrieved by using GetMaximumEnabledLightCount().
  48  * If more than 5 enabled Light objects are added on SceneView, SceneView turns on only 5 lights in the order the lights were added.
  49  * This Light can be added to SceneView directly but also it can be added on other Actor.
  50  * When a parent actor is added to a SceneView, its Light behaves in the SceneView the same as if it were added directly to the SceneView.
  51  * @note Light inherits Actor, so Light color and direction can be controlled by setting Actor's COLOR and ORIENTATION Property.
  52  * Dali::DevelActor::LookAt() method can be used to set light direction easily.
  53  * @note Default light direction is to Z-axis
  54  * @code
  55  * Scene3D::SceneView sceneView = Scene3D::SceneView::New();
  56  * Scene3D::Lightlight = Scene3D::Light::New();
  57  * light.SetProperty(Dali::Actor::Property::COLOR, Color::BROWN);
  58  * Dali::DevelActor::LookAt(light, Vector3(1.0f, 1.0f, 1.0f));
  59  * sceneView.Add(light);
  60  * @endcode
  61  * @SINCE_2_2.32
  62  */
  63 class DALI_SCENE3D_API Light : public Dali::Toolkit::Control
  64 {
  65 public:
  66   /**
  67    * @brief Create an initialized Light.
  68    *
  69    * @SINCE_2_2.32
  70    * @return A handle to a newly allocated Dali resource
  71    */
  72   static Light New();
  73
  74   /**
  75    * @brief Creates an uninitialized Light.
  76    *
  77    * Only derived versions can be instantiated. Calling member
  78    * functions with an uninitialized Dali::Object is not allowed.
  79    *
  80    * @SINCE_2_2.32
  81    */
  82   Light();
  83
  84   /**
  85    * @brief Destructor.
  86    *
  87    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  88    *
  89    * @SINCE_2_2.32
  90    */
  91   ~Light();
  92
  93   /**
  94    * @brief Copy constructor.
  95    *
  96    * @SINCE_2_2.32
  97    * @param[in] light Handle to an object
  98    */
  99   Light(const Light& light);
 100
 101   /**
 102    * @brief Move constructor
 103    *
 104    * @SINCE_2_2.32
 105    * @param[in] rhs A reference to the moved handle
 106    */
 107   Light(Light&& rhs) noexcept;
 108
 109   /**
 110    * @brief Assignment operator.
 111    *
 112    * @SINCE_2_2.32
 113    * @param[in] light Handle to an object
 114    * @return reference to this
 115    */
 116   Light& operator=(const Light& light);
 117
 118   /**
 119    * @brief Move assignment
 120    *
 121    * @SINCE_2_2.32
 122    * @param[in] rhs A reference to the moved handle
 123    * @return A reference to this
 124    */
 125   Light& operator=(Light&& rhs) noexcept;
 126
 127   /**
 128    * @brief Downcasts an Object handle to Light.
 129    *
 130    * If handle points to a Light, the downcast produces valid handle.
 131    * If not, the returned handle is left uninitialized.
 132    *
 133    * @SINCE_2_2.32
 134    * @param[in] handle Handle to an object
 135    * @return Handle to a Light or an uninitialized handle
 136    */
 137   static Light DownCast(BaseHandle handle);
 138
 139   /**
 140    * @brief Enables this light.
 141    * The Light is turned on when the Light object is added on SceneView and enabled.
 142    * @SINCE_2_2.32
 143    * @note SceneView can turn on only up to maximum enabled light count that can be retrieved by GetMaximumEnabledLightCount().
 144    * @param[in] enable True to make this Light enable.
 145    */
 146   void Enable(bool enable);
 147
 148   /**
 149    * @brief Checks whether this light is enabled or not.
 150    * @SINCE_2_2.32
 151    * @return True if this light is enabled.
 152    */
 153   bool IsEnabled() const;
 154
 155   /**
 156    * @brief Retrieves maximum enabled light count.
 157    * @SINCE_2_2.32
 158    * @return The number of maximum enabled light count.
 159    */
 160   static uint32_t GetMaximumEnabledLightCount();
 161
 162   /**
 163    * @brief Enables shadow for this light.
 164    * Dali::Scene3D generates shadow by using shadow map.
 165    * For the Directional Light, the shadow map is created to cover view frustum of current selected camera.
 166    * This means that if the distance between the near and far planes is too large,
 167    * the shadow map has to cover an unnecessarily large area. This results in lower shadow quality.
 168    * @SINCE_2_2.43
 169    * @note This light should be already turned on in the SceneView.
 170    * @note (When enable is true) If there is previous light already enabled shadow in the SceneView, this function call is ignored.
 171    * @note (When enable is false, and this light is currently used for shader)
 172    * If there are other lights those are turned on and shadow enabled, one of the light will be used for shadow automatically.
 173    * @param[in] enable True to make this Light's shadow enable.
 174    */
 175   void EnableShadow(bool enable);
 176
 177   /**
 178    * @brief Checks whether the shadow of this light is enabled or not.
 179    * @SINCE_2_2.43
 180    * @return True if the shadow of this light is enabled.
 181    */
 182   bool IsShadowEnabled() const;
 183
 184   /**
 185    * @brief Enables filtering to soften the edge of shadow.
 186    * Basically the shadow is hard shadow that has sharp edge.
 187    * This method enables soft filtering to make the sharp edge to smoothing.
 188    * @SINCE_2_2.43
 189    * @note This soft filtering requires expensive computation power.
 190    * @param[in] useSoftFiltering True to soften the shadow edge.
 191    */
 192   void EnableShadowSoftFiltering(bool useSoftFiltering);
 193
 194   /**
 195    * @brief Checks whether the shadow uses soft filtering.
 196    * @SINCE_2_2.43
 197    * @return True if the shadow edge is soften.
 198    */
 199   bool IsShadowSoftFilteringEnabled() const;
 200
 201   /**
 202    * @brief Sets shadow intensity.
 203    * If the intensity is larger, the shadow area will be darker.
 204    * The intensity value is between [0, 1].
 205    * Default value is 0.5
 206    * @SINCE_2_2.43
 207    * @param[in] shadowIntensity Shadow intensity value
 208    */
 209   void SetShadowIntensity(float shadowIntensity);
 210
 211   /**
 212    * @brief Retrieve shadow intensity.
 213    * @SINCE_2_2.43
 214    * @return Current shadow intensity value.
 215    */
 216   float GetShadowIntensity() const;
 217
 218   /**
 219    * @brief Sets shadow bias.
 220    * Shadow bias is an offset value to remove shadow acne that is a visual artifact can be shown on the Shadow
 221    * Default value is 0.001
 222    * @SINCE_2_2.43
 223    * @param[in] shadowBias bias value to remove shadow acne.
 224    * @note If the shadow bias is too large, the object will appear detached from the shadow.
 225    */
 226   void SetShadowBias(float shadowBias);
 227
 228   /**
 229    * @brief Retrieves shadow bias value.
 230    * @SINCE_2_2.43
 231    * @return Shadow bias value.
 232    */
 233   float GetShadowBias() const;
 234
 235 public: // Not intended for application developers
 236   /// @cond internal
 237   /**
 238    * @brief Creates a handle using the Toolkit::Internal implementation.
 239    *
 240    * @param[in] implementation The Control implementation
 241    */
 242   DALI_INTERNAL Light(Internal::Light& implementation);
 243
 244   /**
 245    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 246    *
 247    * @param[in] internal A pointer to the internal CustomActor
 248    */
 249   DALI_INTERNAL Light(Dali::Internal::CustomActor* internal);
 250   /// @endcond
 251 };
 252
 253 /**
 254  * @}
 255  */
 256 } // namespace Scene3D
 257
 258 } // namespace Dali
 259
 260 #endif // DALI_SCENE3D_LIGHT_H