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