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, LoadCompletedSignal will be emitted.
  75  * If we try to load before LoadCompletedSignal emitted, previous load request cancel and only latest request loaded.
  76  *
  77  * @code
  78  *
  79  * MotionData motionData = MotionData::New();
  80  * motionData.LoadCompletedSignal().Connect(&OnLoadCompleted);
  81  * motionData.LoadBvh("bvhFilename.bvh", Vector3::ONE);
  82  *
  83  * @endcode
  84  *
  85  * We can generate animation of Scene3D::Model from MotionData class.
  86  * Or, just set values.
  87  *
  88  * @code
  89  *
  90  * // Generate animation from loaded Model
  91  * Dali::Animation animation = model.GenerateMotionDataAnimation(motionData);
  92  * animation.Play();
  93  *
  94  * // Set values from loaded Model.
  95  * model2.SetMotionData(motionData);
  96  *
  97  * @endcode
  98  * @note We don't check duplicated MotionIndex internally.
  99  * @note We don't check MotionValue type is matched with MotionIndex.
 100  * @SINCE_2_2.34
 101  */
 102 class DALI_SCENE3D_API MotionData : public Dali::BaseHandle
 103 {
 104 public:
 105   /// @brief LoadCompleted signal type. @SINCE_2_2.34
 106   typedef Signal<void(MotionData)> LoadCompletedSignalType;
 107
 108 public: // Creation & Destruction
 109   /**
 110    * @brief Create an initialized MotionData.
 111    *
 112    * @SINCE_2_2.34
 113    * @return A handle to a newly allocated Dali resource
 114    */
 115   static MotionData New();
 116
 117   /**
 118    * @brief Create an initialized MotionData with duration.
 119    *
 120    * @SINCE_2_2.34
 121    * @param[in] durationSeconds Duration of animation as seconds.
 122    * @return A handle to a newly allocated Dali resource
 123    */
 124   static MotionData New(float durationSeconds);
 125
 126   /**
 127    * @brief Creates an uninitialized MotionData.
 128    *
 129    * Only derived versions can be instantiated. Calling member
 130    * functions with an uninitialized Dali::Object is not allowed.
 131    *
 132    * @SINCE_2_2.34
 133    */
 134   MotionData();
 135
 136   /**
 137    * @brief Destructor.
 138    *
 139    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 140    *
 141    * @SINCE_2_2.34
 142    */
 143   ~MotionData();
 144
 145   /**
 146    * @brief Copy constructor.
 147    *
 148    * @SINCE_2_2.34
 149    * @param[in] motionData Handle to an object
 150    */
 151   MotionData(const MotionData& motionData);
 152
 153   /**
 154    * @brief Move constructor
 155    *
 156    * @SINCE_2_2.34
 157    * @param[in] rhs A reference to the moved handle
 158    */
 159   MotionData(MotionData&& rhs) noexcept;
 160
 161   /**
 162    * @brief Assignment operator.
 163    *
 164    * @SINCE_2_2.34
 165    * @param[in] motionData Handle to an object
 166    * @return reference to this
 167    */
 168   MotionData& operator=(const MotionData& motionData);
 169
 170   /**
 171    * @brief Move assignment
 172    *
 173    * @SINCE_2_2.34
 174    * @param[in] rhs A reference to the moved handle
 175    * @return A reference to this
 176    */
 177   MotionData& operator=(MotionData&& rhs) noexcept;
 178
 179   /**
 180    * @brief Downcasts an Object handle to MotionData.
 181    *
 182    * If handle points to a MotionData, the downcast produces valid handle.
 183    * If not, the returned handle is left uninitialized.
 184    *
 185    * @SINCE_2_2.34
 186    * @param[in] handle Handle to an object
 187    * @return Handle to a MotionData or an uninitialized handle
 188    */
 189   static MotionData DownCast(BaseHandle handle);
 190
 191 public: // Public Method
 192   /**
 193    * @brief Get the number of motions what we added
 194    *
 195    * @SINCE_2_2.34
 196    * @return The number of motions
 197    */
 198   uint32_t GetMotionCount() const;
 199
 200   /**
 201    * @brief Get MotionIndex from given index'th.
 202    *
 203    * @SINCE_2_2.34
 204    * @param[in] index The index of motion list.
 205    * @return Index of motion, or empty handle if invalid index inputed.
 206    */
 207   MotionIndex GetIndex(uint32_t index) const;
 208
 209   /**
 210    * @brief Get MotionValue from given index'th.
 211    *
 212    * @SINCE_2_2.34
 213    * @param[in] index The index of motion list.
 214    * @return Value of motion, or empty handle if invalid index inputed.
 215    */
 216   MotionValue GetValue(uint32_t index) const;
 217
 218   /**
 219    * @brief Append new motion.
 220    * @note We don't check duplicated MotionIndex internally.
 221    *
 222    * @SINCE_2_2.34
 223    * @param[in] index index of motion.
 224    * @param[in] value value of motion.
 225    */
 226   void Add(MotionIndex index, MotionValue value);
 227
 228   /**
 229    * @brief Clear all stored motion data.
 230    *
 231    * @SINCE_2_2.34
 232    */
 233   void Clear();
 234
 235   /**
 236    * @brief Set the duration of this motion data if it be generated as Dali::Animation.
 237    *
 238    * @SINCE_2_2.34
 239    * @param[in] durationSeconds Duration of animation as seconds.
 240    */
 241   void SetDuration(float durationSeconds);
 242
 243   /**
 244    * @brief Get the duration of this motion data if it be generated as Dali::Animation.
 245    *
 246    * @SINCE_2_2.34
 247    * @return The duration of this motion data seconds. Default is 0.0f
 248    */
 249   float GetDuration() const;
 250
 251   /**
 252    * @brief Load MotionData from bvh file.
 253    * It will use Dali::Scene3D::Loader::LoadBvh() internally.
 254    * LoadCompleteSignal() will be emitted after load completed.
 255    *
 256    * @SINCE_2_2.34
 257    * @param[in] path The file path.
 258    * @param[in] scale The scale factor to set on the position property manually.
 259    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 260    */
 261   void LoadBvh(const std::string& path, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 262
 263   /**
 264    * @brief Load MotionData from bvh file.
 265    * It will use Dali::Scene3D::Loader::LoadBvh() internally.
 266    * LoadCompleteSignal() will be emitted after load completed.
 267    *
 268    * @SINCE_2_2.34
 269    * @param[in] path The file path.
 270    * @param[in] scale The scale factor to set on the position property manually.
 271    * @param[in] useRootTranslationOnly True to use only root translation with rotation animation.
 272    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 273    */
 274   void LoadBvh(const std::string& path, bool useRootTranslationOnly, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 275
 276   /**
 277    * @brief Load MotionData from bvh buffer.
 278    * It will use Dali::Scene3D::Loader::LoadBvhFromBuffer() internally.
 279    * LoadCompleteSignal() will be emitted after load completed.
 280    *
 281    * @SINCE_2_2.34
 282    * @param[in] rawBuffer The bvh buffer containing the facial animation as bvh format string.
 283    * @param[in] rawBufferLength The length of buffer.
 284    * @param[in] scale The scale factor to set on the position property manually.
 285    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 286    */
 287   void LoadBvhFromBuffer(const uint8_t* rawBuffer, int rawBufferLength, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 288
 289   /**
 290    * @brief Load MotionData from bvh buffer.
 291    * It will use Dali::Scene3D::Loader::LoadBvhFromBuffer() internally.
 292    * LoadCompleteSignal() will be emitted after load completed.
 293    *
 294    * @SINCE_2_2.34
 295    * @param[in] rawBuffer The bvh buffer containing the facial animation as bvh format string.
 296    * @param[in] rawBufferLength The length of buffer.
 297    * @param[in] useRootTranslationOnly True to use only root translation with rotation animation.
 298    * @param[in] scale The scale factor to set on the position property manually.
 299    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 300    */
 301   void LoadBvhFromBuffer(const uint8_t* rawBuffer, int rawBufferLength, bool useRootTranslationOnly, const Vector3& scale = Vector3::ONE, bool synchronousLoad = false);
 302
 303   /**
 304    * @brief Load MotionData from facial defined json file.
 305    * It will use Dali::Scene3D::Loader::LoadFacialAnimation() internally.
 306    * LoadCompleteSignal() will be emitted after load completed.
 307    *
 308    * @SINCE_2_2.34
 309    * @param[in] url The file path.
 310    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 311    */
 312   void LoadFacialAnimation(const std::string& url, bool synchronousLoad = false);
 313
 314   /**
 315    * @brief Load MotionData from facial defined json file.
 316    * It will use Dali::Scene3D::Loader::LoadFacialAnimationFromBuffer() internally.
 317    * LoadCompleteSignal() will be emitted after load completed.
 318    *
 319    * @SINCE_2_2.34
 320    * @param[in] rawBuffer The raw buffer containing the facial animation as json format string.
 321    * @param[in] rawBufferLength The length of raw buffer.
 322    * @param[in] synchronousLoad True if we want to load result synchronously. Default is false.
 323    */
 324   void LoadFacialAnimationFromBuffer(const uint8_t* rawBuffer, int rawBufferLength, bool synchronousLoad = false);
 325
 326 public:
 327   /**
 328    * @brief This signal is emitted after motion data are loaded completed.
 329    * @note Signal will be emitted even if we request load synchronously.
 330    *
 331    * A callback of the following type may be connected:
 332    * @code
 333    *   void YourCallbackName(MotionData motionData);
 334    * @endcode
 335    *
 336    * @SINCE_2_2.34
 337    * @return The signal to connect to.
 338    */
 339   LoadCompletedSignalType& LoadCompletedSignal();
 340
 341 public: // Not intended for application developers
 342   /// @cond internal
 343   /**
 344    * @brief Creates a handle using the Scene3D::Internal implementation.
 345    *
 346    * @param[in] implementation The MotionData implementation
 347    */
 348   DALI_INTERNAL MotionData(Dali::Scene3D::Internal::MotionData* implementation);
 349   /// @endcond
 350 };
 351
 352 /**
 353  * @}
 354  */
 355
 356 } // namespace Scene3D
 357
 358 } // namespace Dali
 359
 360 #endif // DALI_SCENE3D_MODEL_MOTION_MOTION_DATA_H