dali-scene3d/public-api/model-motion/motion-data.h

   1 #ifndef DALI_SCENE3D_MODEL_MOTION_MOTION_DATA_H
   2 #define DALI_SCENE3D_MODEL_MOTION_MOTION_DATA_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/public-api/common/dali-common.h>
  23 #include <dali/public-api/object/base-handle.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-scene3d/public-api/api.h>
  27 #include <dali-scene3d/public-api/model-motion/motion-index/motion-index.h>
  28 #include <dali-scene3d/public-api/model-motion/motion-value.h>
  29
  30 namespace Dali
  31 {
  32 namespace Scene3D
  33 {
  34 //Forward declarations.
  35 namespace Internal
  36 {
  37 class MotionData;
  38 } // namespace Internal
  39
  40 /**
  41  * @addtogroup dali_scene3d_model_motion_motion_data
  42  * @{
  43  */
  44
  45 /**
  46  * @brief List of model motion definitions.
  47  * Each motion has pair of MotionIndex and MotionValue.
  48  * MotionIndex is abstract class that specify the target of motion.
  49  * MotionValue is target value of motion. It can be KeyFrames.
  50  *
  51  * We can generate list of motions by MotionIndex and MotionValue classes.
  52  *
  53  * @code
  54  *
  55  * MotionData motionData = MotionData::New(3.0f);
  56  *
  57  * // Make MotionIndex with MotionPropertyIndex
  58  * // Make MotionValue with Dali::Property::Value
  59  * motionData.Add(MotionPropertyIndex::New("nodeName", "color"), MotionValue::New(Color::RED));
  60  *
  61  * // Make MotionIndex with MotionTransformIndex
  62  * // Make MotionValue with Dali::KeyFrames
  63  * KeyFrames keyFrames = KeyFrames::New();
  64  * keyFrames.Add(0.0f, 0.0f);
  65  * keyFrames.Add(0.0f, 1.0f);
  66  * motionData.Add(MotionTransformIndex::New("nodeName", MotionTransformIndex::TransformType::POSITION_X), MotionValue::New(keyFrames));
  67  *
  68  * // Make MotionIndex with BlendShapeIndex
  69  * motionData.Add(BlendShapeIndex::New("nodeName", 0u), motionData.GetValue(1u));
  70  *
  71  * @endcode
  72  *
  73  * We can request to load MotionData from file or buffer asynchronously.
  74  * If load completed, LoadCompetedSignal will be emmited.
  75  *
  76  * @code
  77  *
  78  * MotionData motionData = MotionData::New();
  79  * motionData.LoadCompletedSignal().Connect(&OnLoadCompleted);
  80  * motionData.LoadBvh("bvhFilename.bvh", Vector3::ONE);
  81  *
  82  * @endcode
  83  *
  84  * We can generate animation of Scene3D::Model from MotionData class.
  85  * Or, just set values.
  86  *
  87  * @code
  88  *
  89  * // Generate animation from loaded Model
  90  * Dali::Animation animation = model.GenerateMotionDataAnimation(motionData);
  91  * animation.Play();
  92  *
  93  * // Set values from loaded Model.
  94  * model2.SetMotionData(motionData);
  95  *
  96  * @endcode
  97  * @note We don't check duplicated MotionIndex internally.
  98  * @SINCE_2_2.99
  99  */
 100 class DALI_SCENE3D_API MotionData : public Dali::BaseHandle
 101 {
 102 public:
 103   /// @brief LoadCompleted signal type. @SINCE_2_2.99
 104   typedef Signal<void(MotionData)> LoadCompletedSignalType;
 105
 106 public: // Creation & Destruction
 107   /**
 108    * @brief Create an initialized MotionData.
 109    *
 110    * @SINCE_2_2.99
 111    * @return A handle to a newly allocated Dali resource
 112    */
 113   static MotionData New();
 114
 115   /**
 116    * @brief Create an initialized MotionData with duration.
 117    *
 118    * @SINCE_2_2.99
 119    * @param[in] durationSeconds Duration of animation as seconds.
 120    * @return A handle to a newly allocated Dali resource
 121    */
 122   static MotionData New(float durationSeconds);
 123
 124   /**
 125    * @brief Creates an uninitialized MotionData.
 126    *
 127    * Only derived versions can be instantiated. Calling member
 128    * functions with an uninitialized Dali::Object is not allowed.
 129    *
 130    * @SINCE_2_2.99
 131    */
 132   MotionData();
 133
 134   /**
 135    * @brief Destructor.
 136    *
 137    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 138    *
 139    * @SINCE_2_2.99
 140    */
 141   ~MotionData();
 142
 143   /**
 144    * @brief Copy constructor.
 145    *
 146    * @SINCE_2_2.99
 147    * @param[in] motionData Handle to an object
 148    */
 149   MotionData(const MotionData& motionData);
 150
 151   /**
 152    * @brief Move constructor
 153    *
 154    * @SINCE_2_2.99
 155    * @param[in] rhs A reference to the moved handle
 156    */
 157   MotionData(MotionData&& rhs) noexcept;
 158
 159   /**
 160    * @brief Assignment operator.
 161    *
 162    * @SINCE_2_2.99
 163    * @param[in] motionData Handle to an object
 164    * @return reference to this
 165    */
 166   MotionData& operator=(const MotionData& motionData);
 167
 168   /**
 169    * @brief Move assignment
 170    *
 171    * @SINCE_2_2.99
 172    * @param[in] rhs A reference to the moved handle
 173    * @return A reference to this
 174    */
 175   MotionData& operator=(MotionData&& rhs) noexcept;
 176
 177   /**
 178    * @brief Downcasts an Object handle to MotionData.
 179    *
 180    * If handle points to a MotionData, the downcast produces valid handle.
 181    * If not, the returned handle is left uninitialized.
 182    *
 183    * @SINCE_2_2.99
 184    * @param[in] handle Handle to an object
 185    * @return Handle to a MotionData or an uninitialized handle
 186    */
 187   static MotionData DownCast(BaseHandle handle);
 188
 189 public: // Public Method
 190   /**
 191    * @brief Get the number of motions what we added
 192    *
 193    * @SINCE_2_2.99
 194    * @return The number of motions
 195    */
 196   uint32_t GetMotionCount() const;
 197
 198   /**
 199    * @brief Get MotionIndex from given index'th.
 200    *
 201    * @SINCE_2_2.99
 202    * @param[in] index The index of motion list.
 203    * @return Index of motion, or empty handle if invalid index inputed.
 204    */
 205   MotionIndex GetIndex(uint32_t index) const;
 206
 207   /**
 208    * @brief Get MotionValue from given index'th.
 209    *
 210    * @SINCE_2_2.99
 211    * @param[in] index The index of motion list.
 212    * @return Value of motion, or empty handle if invalid index inputed.
 213    */
 214   MotionValue GetValue(uint32_t index) const;
 215
 216   /**
 217    * @brief Append new motion.
 218    * @note We don't check duplicated MotionIndex internally.
 219    *
 220    * @SINCE_2_2.99
 221    * @param[in] index index of motion.
 222    * @param[in] value value of motion.
 223    */
 224   void Add(MotionIndex index, MotionValue value);
 225
 226   /**
 227    * @brief Clear all stored motion data.
 228    *
 229    * @SINCE_2_2.99
 230    */
 231   void Clear();
 232
 233   /**
 234    * @brief Set the duration of this motion data if it be generated as Dali::Animation.
 235    *
 236    * @SINCE_2_2.99
 237    * @param[in] durationSeconds Duration of animation as seconds.
 238    */
 239   void SetDuration(float durationSeconds);
 240
 241   /**
 242    * @brief Get the duration of this motion data if it be generated as Dali::Animation.
 243    *
 244    * @SINCE_2_2.99
 245    * @return The duration of this motion data seconds. Default is 0.0f
 246    */
 247   float GetDuration() const;
 248
 249   /**
 250    * @brief Load MotionData from bvh file.
 251    * It will use Dali::Scene3D::Loader::LoadBvh() internally.
 252    * LoadCompleteSignal() will be emitted after load completed.
 253    *
 254    * @SINCE_2_2.99
 255    * @param[in] path The file path.
 256    * @param[in] scale The scale factor to set on the position property manually.
 257    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 258    */
 259   void LoadBvh(const std::string& path, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 260
 261   /**
 262    * @brief Load MotionData from bvh buffer.
 263    * It will use Dali::Scene3D::Loader::LoadBvhFromBuffer() internally.
 264    * LoadCompleteSignal() will be emitted after load completed.
 265    *
 266    * @SINCE_2_2.99
 267    * @param[in] rawBuffer The bvh buffer.
 268    * @param[in] rawBufferLength The length of buffer.
 269    * @param[in] scale The scale factor to set on the position property manually.
 270    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 271    */
 272   void LoadBvhFromBuffer(const uint8_t* rawBuffer, int rawBufferLength, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 273
 274   /**
 275    * @brief Load MotionData from facail defined json file.
 276    * It will use Dali::Scene3D::Loader::LoadFacialAnimation() internally.
 277    * LoadCompleteSignal() will be emitted after load completed.
 278    *
 279    * @SINCE_2_2.99
 280    * @param[in] url The file path.
 281    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 282    */
 283   void LoadFacialAnimation(const std::string& url, bool synchronousLoad = false);
 284
 285   /**
 286    * @brief Load MotionData from facail defined json file.
 287    * It will use Dali::Scene3D::Loader::LoadFacialAnimationFromBuffer() internally.
 288    * LoadCompleteSignal() will be emitted after load completed.
 289    *
 290    * @SINCE_2_2.99
 291    * @param[in] rawBuffer The raw buffer containing the facial animation.
 292    * @param[in] rawBufferLength The length of raw buffer.
 293    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 294    */
 295   void LoadFacialAnimationFromBuffer(const uint8_t* rawBuffer, int rawBufferLength, bool synchronousLoad = false);
 296
 297 public:
 298   /**
 299    * @brief This signal is emitted after motion data are loaded completed.
 300    * @note Signal will be emitted even if we request load synchronously.
 301    *
 302    * A callback of the following type may be connected:
 303    * @code
 304    *   void YourCallbackName(MotionData motionData);
 305    * @endcode
 306    *
 307    * @SINCE_2_2.99
 308    * @return The signal to connect to.
 309    */
 310   LoadCompletedSignalType& LoadCompletedSignal();
 311
 312 public: // Not intended for application developers
 313   /// @cond internal
 314   /**
 315    * @brief Creates a handle using the Scene3D::Internal implementation.
 316    *
 317    * @param[in] implementation The MotionData implementation
 318    */
 319   DALI_INTERNAL MotionData(Dali::Scene3D::Internal::MotionData* implementation);
 320   /// @endcond
 321 };
 322
 323 /**
 324  * @}
 325  */
 326
 327 } // namespace Scene3D
 328
 329 } // namespace Dali
 330
 331 #endif // DALI_SCENE3D_MODEL_MOTION_MOTION_DATA_H