dali-scene3d/public-api/controls/model/model.h

   1 #ifndef DALI_SCENE3D_MODEL_H
   2 #define DALI_SCENE3D_MODEL_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
  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 #include <dali/public-api/rendering/texture.h>
  29
  30 namespace Dali
  31 {
  32 namespace Scene3D
  33 {
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Model;
  37 }
  38
  39 /**
  40  * @addtogroup dali_toolkit_controls_model
  41  * @{
  42  */
  43
  44 /**
  45  * @brief Model is a control to show 3D model objects.
  46  * Model supports to load glTF 2.0 and DLI models for the input format
  47  * and also supports Physically Based Rendering with Image Based Lighting.
  48  *
  49  * The Animations defined in the glTF or DLI models are also loaded and can be retrieved by using GetAnimation() method.
  50  * The number of animation is also retrieved by GetAnimationCount() method.
  51  *
  52  * By default, The loaded model has its own position and size which are defined in vertex buffer regardless of the Control size.
  53  *
  54  * @SINCE_2_1.41
  55  * @code
  56  *
  57  * Model model = Model::New(modelUrl);
  58  * model.SetProperty(Dali::Actor::Property::SIZE, Vector2(width, height));
  59  * model.SetProperty(Dali::Actor::Property::ANCHOR_POINT, AnchorPoint::CENTER);
  60  * model.SetProperty(Dali::Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER);
  61  * model.SetImageBasedLightSource(diffuseUrl, specularUrl, scaleFactor);
  62  * window.Add(model);
  63  * uint32_t animationCount = model.GetAnimationCount();
  64  * Dali::Animation animation = model.GetAnimation(0);
  65  * animation.Play();
  66  *
  67  * @endcode
  68  */
  69 class DALI_SCENE3D_API Model : public Dali::Toolkit::Control
  70 {
  71 public:
  72   /**
  73    * @brief Create an initialized Model.
  74    *
  75    * @SINCE_2_1.41
  76    * @param[in] modelUrl model file path.(e.g., glTF, and DLI).
  77    * @param[in] resourceDirectoryUrl resource file path that includes binary, image etc.
  78    * @note If resourceDirectoryUrl is empty, the parent directory path of modelUrl is used for resource path.
  79    * @return A handle to a newly allocated Dali resource
  80    */
  81   static Model New(const std::string& modelUrl, const std::string& resourceDirectoryUrl = std::string());
  82
  83   /**
  84    * @brief Creates an uninitialized Model.
  85    *
  86    * Only derived versions can be instantiated. Calling member
  87    * functions with an uninitialized Dali::Object is not allowed.
  88    *
  89    * @SINCE_2_1.41
  90    */
  91   Model();
  92
  93   /**
  94    * @brief Destructor.
  95    *
  96    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  97    *
  98    * @SINCE_2_1.41
  99    */
 100   ~Model();
 101
 102   /**
 103    * @brief Copy constructor.
 104    *
 105    * @SINCE_2_1.41
 106    * @param[in] model Handle to an object
 107    */
 108   Model(const Model& model);
 109
 110   /**
 111    * @brief Move constructor
 112    *
 113    * @SINCE_2_1.41
 114    * @param[in] rhs A reference to the moved handle
 115    */
 116   Model(Model&& rhs);
 117
 118   /**
 119    * @brief Assignment operator.
 120    *
 121    * @SINCE_2_1.41
 122    * @param[in] model Handle to an object
 123    * @return reference to this
 124    */
 125   Model& operator=(const Model& model);
 126
 127   /**
 128    * @brief Move assignment
 129    *
 130    * @SINCE_2_1.41
 131    * @param[in] rhs A reference to the moved handle
 132    * @return A reference to this
 133    */
 134   Model& operator=(Model&& rhs);
 135
 136   /**
 137    * @brief Downcasts an Object handle to Model.
 138    *
 139    * If handle points to a Model, the downcast produces valid handle.
 140    * If not, the returned handle is left uninitialized.
 141    *
 142    * @SINCE_2_1.41
 143    * @param[in] handle Handle to an object
 144    * @return Handle to a Model or an uninitialized handle
 145    */
 146   static Model DownCast(BaseHandle handle);
 147
 148   /**
 149    * @brief Retrieves model root Actor.
 150    *
 151    * @SINCE_2_1.41
 152    * @return Root Actor of the model.
 153    */
 154   const Actor GetModelRoot() const;
 155
 156   /**
 157    * @brief Whether allow this model's children actor to use events.
 158    *
 159    * Usually, 3D Model might have a lot of actors. And most of them don't need to check events.
 160    * To optimize traversal, we need to setup some flag that this model don't allow (or allow) to traversal
 161    * children so that child can use events.
 162    *
 163    * @SINCE_2_1.43
 164    * @note Even if we set children sensitive as false, model itself's sensitive
 165    * is depend on it's property.
 166    * @note If we don't call this API, default is false. (Don't allow to traversal model's children during hit-test)
 167    *
 168    * @param[in] enable True to enable model's children can use events.
 169    */
 170   void SetChildrenSensitive(bool enable);
 171
 172   /**
 173    * @brief Gets whether this Model allow model's children actor to use events or not.
 174    *
 175    * @SINCE_2_1.43
 176    * @return bool True if this Model allow model children sensitive.
 177    */
 178   bool GetChildrenSensitive() const;
 179
 180   /**
 181    * @brief Whether allow this model's children actor to be keyboard focusable.
 182    *
 183    * Usually, 3D Model might have a lot of actors. And most of them don't need to check focusable.
 184    * To optimize traversal, we need to setup some flag that this model don't allow (or allow) to traversal
 185    * children so that child can be keyboard focusable.
 186    *
 187    * @SINCE_2_2.2
 188    * @note Even if we set children focusable as false, model itself's focusable
 189    * is depend on it's property.
 190    * @note If we don't call this API, default is false. (Don't allow to traversal model's children during focusable test)
 191    *
 192    * @param[in] enable True to enable model's children can be focusable.
 193    */
 194   void SetChildrenFocusable(bool enable);
 195
 196   /**
 197    * @brief Gets whether this Model allow model's children actor to be keyboard focusable or not.
 198    *
 199    * @SINCE_2_2.2
 200    * @return bool True if this Model allow model children are focusable.
 201    */
 202   bool GetChildrenFocusable() const;
 203
 204   /**
 205    * @brief Changes Image Based Light as the input textures.
 206    *
 207    * @SINCE_2_1.41
 208    * @param[in] diffuseUrl cube map that can be used as a diffuse IBL source.
 209    * @param[in] specularUrl cube map that can be used as a specular IBL source.
 210    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 211    */
 212   void SetImageBasedLightSource(const std::string& diffuseUrl, const std::string& specularUrl, float scaleFactor = 1.0f);
 213
 214   /**
 215    * @brief Sets Image Based Light Texture.
 216    *
 217    * @SINCE_2_1.41
 218    * @param[in] diffuseTexture cube map texture that can be used as a diffuse IBL source.
 219    * @param[in] specularTexture cube map texture that can be used as a specular IBL source.
 220    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 221    *
 222    * @note Both of diffuse texture and specular texture should be available. If not, nothing applied.
 223    */
 224   void SetImageBasedLightTexture(Texture diffuseTexture, Texture specularTexture, float scaleFactor = 1.0f);
 225
 226   /**
 227    * @brief Sets Scale Factor of Image Based Light Source.
 228    *
 229    * @SINCE_2_1.41
 230    * @note If SetImageBasedLightSource() or SetImageBasedLightTexture() method is called after this method, scaleFactor is overrided.
 231    *
 232    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 233    */
 234   void SetImageBasedLightScaleFactor(float scaleFactor);
 235
 236   /**
 237    * @brief Gets Scale Factor of Image Based Light Source.
 238    * Default value is 1.0f.
 239    *
 240    * @SINCE_2_1.41
 241    * @return scale factor that controls light source intensity.
 242    */
 243   float GetImageBasedLightScaleFactor() const;
 244
 245   /**
 246    * @brief Gets number of animations those loaded from model file.
 247    *
 248    * @SINCE_2_1.41
 249    * @return The number of loaded animations.
 250    * @note This method should be called after Model load finished.
 251    */
 252   uint32_t GetAnimationCount() const;
 253
 254   /**
 255    * @brief Gets animation at the index.
 256    *
 257    * @SINCE_2_1.41
 258    * @param[in] index Index of animation to be retrieved.
 259    * @return Animation at the index.
 260    * @note This method should be called after Model load finished.
 261    */
 262   Dali::Animation GetAnimation(uint32_t index) const;
 263
 264   /**
 265    * @brief Retrieves animation with the given name.
 266    *
 267    * @SINCE_2_1.41
 268    * @param[in] name string name of animation to be retrieved.
 269    * @return Animation that has the given name.
 270    * @note This method should be called after Model load finished.
 271    */
 272   Dali::Animation GetAnimation(const std::string& name) const;
 273
 274   /**
 275    * @brief Gets number of camera parameters those loaded from model file.
 276    *
 277    * @SINCE_2_2.15
 278    * @return The number of loaded camera parameters.
 279    * @note This method should be called after Model load finished.
 280    */
 281   uint32_t GetCameraCount() const;
 282
 283   /**
 284    * @brief Generate camera actor using camera parameters at the index.
 285    * If camera parameter is valid, create new CameraActor.
 286    * Camera parameter decide at initialized time and
 287    * didn't apply model node's current position (like Animation).
 288    *
 289    * @SINCE_2_2.15
 290    * @param[in] index Index of camera to be used for generation camera.
 291    * @return Generated CameraActor by the index, or empty Handle if generation failed.
 292    * @note This method should be called after Model load finished.
 293    */
 294   Dali::CameraActor GenerateCamera(uint32_t index) const;
 295
 296   /**
 297    * @brief Apply camera parameters at the index to inputed camera actor.
 298    * If camera parameter is valid and camera actor is not empty, apply parameters.
 299    * It will change camera's transform and near / far / fov or orthographic size / aspect ratio (if defined)
 300    * Camera parameter decide at initialized time and
 301    * didn't apply model node's current position (like Animation).
 302    *
 303    * @SINCE_2_2.15
 304    * @param[in] index Index of camera to be used for generation camera.
 305    * @param[in,out] camera Index of camera to be used for generation camera.
 306    * @return True if apply successed. False otherwise.
 307    * @note This method should be called after Model load finished.
 308    */
 309   bool ApplyCamera(uint32_t index, Dali::CameraActor camera) const;
 310
 311 public: // Not intended for application developers
 312   /// @cond internal
 313   /**
 314    * @brief Creates a handle using the Toolkit::Internal implementation.
 315    *
 316    * @param[in] implementation The Control implementation
 317    */
 318   DALI_INTERNAL Model(Internal::Model& implementation);
 319
 320   /**
 321    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 322    *
 323    * @param[in] internal A pointer to the internal CustomActor
 324    */
 325   DALI_INTERNAL Model(Dali::Internal::CustomActor* internal);
 326   /// @endcond
 327 };
 328
 329 /**
 330  * @}
 331  */
 332 } // namespace Scene3D
 333
 334 } // namespace Dali
 335
 336 #endif // DALI_SCENE3D_MODEL_H