dali-scene3d/public-api/loader/animation-definition.h

   1 #ifndef DALI_SCENE3D_LOADER_ANIMATION_DEFINITION_H
   2 #define DALI_SCENE3D_LOADER_ANIMATION_DEFINITION_H
   3 /*
   4  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 // EXTERNAL INCLUDES
  21 #include <dali/public-api/common/vector-wrapper.h>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali-scene3d/public-api/api.h>
  25 #include <dali-scene3d/public-api/loader/animated-property.h>
  26
  27 namespace Dali::Scene3D::Loader
  28 {
  29 /**
  30  * @brief Animation handle + name + definition of properties.
  31  * @SINCE_2_0.7
  32  */
  33 class DALI_SCENE3D_API AnimationDefinition
  34 {
  35 public: // STATIC
  36   // For Animations created in the SDK.
  37   static const float DEFAULT_DURATION_SECONDS;
  38
  39   // For parsing Animations from dli, when duration was not defined.
  40   static const float MIN_DURATION_SECONDS;
  41
  42   /**
  43    * @brief Saves the original end action of @a anim, sets the end action to Discard, then stops
  44    * the animation and returns the end action.
  45    * @SINCE_2_0.7
  46    */
  47   static Animation::EndAction StopForModification(Animation& anim);
  48
  49 public: // METHODS
  50   AnimationDefinition();
  51
  52   AnimationDefinition(AnimationDefinition&& other);
  53
  54   AnimationDefinition& operator=(AnimationDefinition&& other);
  55
  56   /**
  57    * @brief Registers the properties against the given @a animation.
  58    *
  59    * @a getActor will be used to obtain the Actors for each AnimatedProperty.
  60    * @SINCE_2_0.7
  61    */
  62   void Animate(Animation& animation, AnimatedProperty::GetActor getActor);
  63
  64   /**
  65    * @brief Creates a new Animation and Animates() its properties.
  66    *
  67    * @a getActor will be used to obtain the Actors for each AnimatedProperty.
  68    * @SINCE_2_0.7
  69    */
  70   Animation ReAnimate(AnimatedProperty::GetActor getActor);
  71
  72   /**
  73    * @brief Set the name of the animation.
  74    *
  75    * @SINCE_2_2.22
  76    * @param[in] name The name of the animation.
  77    */
  78   void SetName(const std::string& name);
  79
  80   /**
  81    * @brief Get the name of the animation.
  82    *
  83    * @SINCE_2_2.22
  84    * @return The name of the animation.
  85    */
  86   const std::string& GetName() const;
  87
  88   /**
  89    * @brief Set the duration of the animation in seconds.
  90    *
  91    * @SINCE_2_2.22
  92    * @param[in] duration The duration of the animation in seconds.
  93    */
  94   void SetDuration(float duration);
  95
  96   /**
  97    * @brief Get the duration of the animation in seconds.
  98    *
  99    * @SINCE_2_2.22
 100    * @return The duration of the animation in seconds.
 101    */
 102   float GetDuration() const;
 103
 104   /**
 105    * @brief Set the number of times to loop the animation.
 106    *
 107    * @SINCE_2_2.22
 108    * @param[in] loopCount The number of times to loop the animation. Use -1 for infinite looping.
 109    */
 110   void SetLoopCount(int32_t loopCount);
 111
 112   /**
 113    * @brief Get the number of times to loop the animation.
 114    *
 115    * @SINCE_2_2.22
 116    * @return The number of times to loop the animation. Use -1 for infinite looping.
 117    */
 118   int GetLoopCount() const;
 119
 120   /**
 121    * @brief Set what should happen when an animation is disconnected from an object.
 122    *
 123    * @SINCE_2_2.22
 124    * @param[in] disconnectAction What should happen when an animation is disconnected from an object.
 125    */
 126   void SetDisconnectAction(Animation::EndAction disconnectAction);
 127
 128   /**
 129    * @brief Get what should happen when an animation is disconnected from an object.
 130    *
 131    * @SINCE_2_2.22
 132    * @return What should happen when an animation is disconnected from an object.
 133    */
 134   Animation::EndAction GetDisconnectAction() const;
 135
 136   /**
 137    * @brief Set what should happen when an animation reaches its end.
 138    *
 139    * @SINCE_2_2.22
 140    * @param[in] endAction What should happen when an animation reaches its end.
 141    */
 142   void SetEndAction(Animation::EndAction endAction);
 143
 144   /**
 145    * @brief Get what should happen when an animation reaches its end.
 146    *
 147    * @SINCE_2_2.22
 148    * @return What should happen when an animation reaches its end.
 149    */
 150   Animation::EndAction GetEndAction() const;
 151
 152   /**
 153    * @brief Set a speed factor for this animation. This can be used to speed up or slow down playback of this animation relative to other animations in a scene.
 154    *
 155    * @SINCE_2_2.22
 156    * @param[in] speedFactor The speed factor for this animation. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed, etc.
 157    */
 158   void SetSpeedFactor(float speedFactor);
 159
 160   /**
 161    * @brief Get a speed factor for this animation. This can be used to speed up or slow down playback of this animation relative to other animations in a scene.
 162    *
 163    * @SINCE_2_2.22
 164    * @return The speed factor for this animation. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed, etc.
 165    */
 166   float GetSpeedFactor() const;
 167
 168   /**
 169    * @brief Set a range within which to play this animation. This can be used to play only part of an animation or to play it backwards by setting playRange.y < playRange.x
 170    *
 171    * @SINCE_2_2.22
 172    * @param[in] playRange A range within which to play this animation. x = start time in seconds, y = end time in seconds
 173    */
 174   void SetPlayRange(const Vector2& playRange);
 175
 176   /**
 177    * @brief Get a range within which to play this animation. This can be used to play only part of an animation or to play it backwards by setting playRange.y < playRange.x
 178    *
 179    * @SINCE_2_2.22
 180    * @return A range within which to play this animation. x = start time in seconds, y = end time in seconds
 181    */
 182   Vector2 GetPlayRange() const;
 183
 184   /**
 185    * @brief Reserves Animated property vector's size
 186    *
 187    * @SINCE_2_2.22
 188    * @param[in] size The size to reserve property
 189    */
 190   void ReserveSize(uint32_t size);
 191
 192   /**
 193    * @brief Retrieves the number of animated properties' count
 194    *
 195    * @SINCE_2_2.22
 196    * @return The count of animated properties.
 197    */
 198   uint32_t GetPropertyCount() const;
 199
 200   /**
 201    * @brief Add a property that will be animated by this AnimationDefinition
 202    *
 203    * @SINCE_2_2.22
 204    * @param[in] index The index the property will be stored.
 205    * @param[in] property The property that will be animated by this AnimationDefinition
 206    */
 207   void SetProperty(uint32_t index, AnimatedProperty&& property);
 208
 209   /**
 210    * @brief Retrieves animated property at the index
 211    *
 212    * @SINCE_2_2.22
 213    * @param[in] index The index of property to be retrieved.
 214    */
 215   AnimatedProperty& GetPropertyAt(uint32_t index);
 216
 217   /**
 218    * @brief Retrieves animated property at the index
 219    *
 220    * @SINCE_2_2.34
 221    * @param[in] index The index of property to be retrieved.
 222    */
 223   const AnimatedProperty& GetPropertyAt(uint32_t index) const;
 224
 225 private: // DATA
 226   std::string mName;
 227
 228   float                mDuration         = DEFAULT_DURATION_SECONDS;
 229   int32_t              mLoopCount        = 1;
 230   Animation::EndAction mDisconnectAction = Animation::BAKE_FINAL;
 231   Animation::EndAction mEndAction        = Animation::BAKE;
 232   float                mSpeedFactor      = 1.f;
 233   Vector2              mPlayRange        = Vector2{0.f, 1.f};
 234
 235   std::vector<AnimatedProperty> mProperties;
 236 };
 237
 238 struct AnimationGroupDefinition
 239 {
 240   std::string              mName;
 241   std::vector<std::string> mAnimations;
 242 };
 243
 244 } // namespace Dali::Scene3D::Loader
 245
 246 #endif // DALI_SCENE3D_LOADER_ANIMATION_DEFINITION_H