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