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