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

   1 #ifndef DALI_SCENE3D_MODEL_VIEW_H
   2 #define DALI_SCENE3D_MODEL_VIEW_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/rendering/texture.h>
  27 #include <dali/public-api/common/dali-common.h>
  28
  29 namespace Dali
  30 {
  31 namespace Scene3D
  32 {
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class ModelView;
  36 }
  37
  38 /**
  39  * @addtogroup dali_toolkit_controls_model_view
  40  * @{
  41  */
  42
  43 /**
  44  * @brief ModelView is a control to show 3D model objects.
  45  * ModelView 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 it's own position and size which are defined in vertex buffer regardless of the Control size.
  52  * The model can be resized and repositioned to fit to the ModelView Control with FitSize() and FitCenter() methods.
  53  *
  54  * @code
  55  *
  56  * ModelView modelView = ModelView::New(modelUrl);
  57  * modelView.SetProperty(Dali::Actor::Property::SIZE, Vector2(width, height));
  58  * modelView.SetProperty(Dali::Actor::Property::ANCHOR_POINT, AnchorPoint::CENTER);
  59  * modelView.SetProperty(Dali::Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER);
  60  * modelView.SetImageBasedLightSource(diffuseUrl, specularUrl, scaleFactor);
  61  * modelView.FitSize(true);
  62  * modelView.FitCenter(true);
  63  * window.Add(modelView);
  64  * uint32_t animationCount = modelView.GetAnimationCount();
  65  * Dali::Animation animation = modelView.GetAnimation(0);
  66  * animation.Play();
  67  *
  68  * @endcode
  69  */
  70 class DALI_SCENE3D_API ModelView : public Dali::Toolkit::Control
  71 {
  72 public:
  73   /**
  74    * @brief Create an initialized ModelView.
  75    * @param[in] modelPath model file path.(e.g., glTF, and DLI).
  76    * @param[in] resourcePath resource file path that includes binary, image etc.
  77    * @note If resourcePath is empty, the parent directory path of modelPath is used for resource path.
  78    * @return A handle to a newly allocated Dali resource
  79    */
  80   static ModelView New(const std::string& modelPath, const std::string& resourcePath = std::string());
  81
  82   /**
  83    * @brief Creates an uninitialized ModelView.
  84    *
  85    * Only derived versions can be instantiated. Calling member
  86    * functions with an uninitialized Dali::Object is not allowed.
  87    */
  88   ModelView();
  89
  90   /**
  91    * @brief Destructor.
  92    *
  93    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  94    */
  95   ~ModelView();
  96
  97   /**
  98    * @brief Copy constructor.
  99    * @param[in] modelView Handle to an object
 100    */
 101   ModelView(const ModelView& modelView);
 102
 103   /**
 104    * @brief Move constructor
 105    *
 106    * @param[in] rhs A reference to the moved handle
 107    */
 108   ModelView(ModelView&& rhs);
 109
 110   /**
 111    * @brief Assignment operator.
 112    * @param[in] modelView Handle to an object
 113    * @return reference to this
 114    */
 115   ModelView& operator=(const ModelView& modelView);
 116
 117   /**
 118    * @brief Move assignment
 119    *
 120    * @param[in] rhs A reference to the moved handle
 121    * @return A reference to this
 122    */
 123   ModelView& operator=(ModelView&& rhs);
 124
 125   /**
 126    * @brief Downcasts an Object handle to ModelView.
 127    *
 128    * If handle points to a ModelView, the downcast produces valid handle.
 129    * If not, the returned handle is left uninitialized.
 130    *
 131    * @param[in] handle Handle to an object
 132    * @return Handle to a ModelView or an uninitialized handle
 133    */
 134   static ModelView DownCast(BaseHandle handle);
 135
 136   /**
 137    * @brief Retrieves model root Actor.
 138    * @return Root Actor of the model.
 139    */
 140   const Actor GetModelRoot() const;
 141
 142   /**
 143    * @brief Fits the model to the Control size.
 144    * @param[in] fit true to fit model size to control.
 145    * @note This method makes model fit to the Control size by keeping original model ratio.
 146    * It means If model size is (2, 2, 2) and ModelView size is (10, 8), then the model become looks (8, 8, 8).
 147    * If ModelView Size x or y is 0, this method don't work anything.
 148    * If ModelView Size z is 0, this method considers only x and y values of ModelView Size.
 149    */
 150   void FitSize(bool fit);
 151
 152   /**
 153    * @brief Moves the model to the center of control.
 154    * @param[in] fit true to fit model to center of control.
 155    * @note This method doesn't changes size of model.
 156    */
 157   void FitCenter(bool fit);
 158
 159   /**
 160    * @brief Changes Image Based Light as the input textures.
 161    * @param[in] diffuse cube map that can be used as a diffuse IBL source.
 162    * @param[in] specular cube map that can be used as a specular IBL source.
 163    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 164    */
 165   void SetImageBasedLightSource(const std::string& diffuse, const std::string& specular, float scaleFactor = 1.0f);
 166
 167   /**
 168    * @brief Sets Image Based Light Texture.
 169    *
 170    * @param[in] diffuse cube map texture that can be used as a diffuse IBL source.
 171    * @param[in] specular cube map texture that can be used as a specular IBL source.
 172    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.
 173    *
 174    * @note Both of diffuse and specular should be available. If not, nothing applied.
 175    */
 176   void SetImageBasedLightTexture(Texture diffuse, Texture specular, float scaleFactor = 1.0f);
 177
 178   /**
 179    * @brief Sets Scale Factor of Image Based Light Source.
 180    *
 181    * @note If SetImageBasedLightSource() or SetImageBasedLightTexture() method is called after this method, scaleFactor is overrided.
 182    *
 183    * @param[in] scaleFactor scale factor that controls light source intensity in [0.0f, 1.0f].
 184    */
 185   void SetImageBasedLightScaleFactor(float scaleFactor);
 186
 187   /**
 188    * @brief Gets Scale Factor of Image Based Light Source.
 189    * Default value is 1.0f.
 190    *
 191    * @return scale factor that controls light source intensity.
 192    */
 193   float GetImageBasedLightScaleFactor() const;
 194
 195   /**
 196    * @brief Gets number of animations those loaded from model file.
 197    * @return The number of loaded animations.
 198    * @note This method should be called after Model load finished.
 199    */
 200   uint32_t GetAnimationCount() const;
 201
 202   /**
 203    * @brief Gets animation at the index.
 204    * @param[in] index Index of animation to be retrieved.
 205    * @return Animation at the index.
 206    * @note This method should be called after Model load finished.
 207    */
 208   Dali::Animation GetAnimation(uint32_t index) const;
 209
 210   /**
 211    * @brief Retrieves animation with the given name.
 212    * @param[in] name string name of animation to be retrieved.
 213    * @return Animation that has the given name.
 214    * @note This method should be called after Model load finished.
 215    */
 216   Dali::Animation GetAnimation(const std::string& name) const;
 217
 218 public: // Not intended for application developers
 219   /// @cond internal
 220   /**
 221    * @brief Creates a handle using the Toolkit::Internal implementation.
 222    *
 223    * @param[in] implementation The Control implementation
 224    */
 225   DALI_INTERNAL ModelView(Internal::ModelView& implementation);
 226
 227   /**
 228    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 229    *
 230    * @param[in] internal A pointer to the internal CustomActor
 231    */
 232   DALI_INTERNAL ModelView(Dali::Internal::CustomActor* internal);
 233   /// @endcond
 234 };
 235
 236 /**
 237  * @}
 238  */
 239 } // namespace Scene3D
 240
 241 } // namespace Dali
 242
 243 #endif // DALI_SCENE3D_MODEL_VIEW_H