1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef META_INTERFACE_INTF_ANIMATION_H 17 #define META_INTERFACE_INTF_ANIMATION_H 18 19 #include <base/containers/vector.h> 20 #include <base/math/vector.h> 21 22 #include <meta/base/ids.h> 23 #include <meta/base/namespace.h> 24 #include <meta/interface/animation/intf_animation_controller.h> 25 #include <meta/interface/animation/intf_animation_modifier.h> 26 #include <meta/interface/animation/intf_interpolator.h> 27 #include <meta/interface/curves/intf_curve_1d.h> 28 #include <meta/interface/intf_named.h> 29 #include <meta/interface/intf_object.h> 30 #include <meta/interface/property/intf_property.h> 31 #include <meta/interface/property/property_events.h> 32 #include <meta/interface/simple_event.h> 33 34 META_BEGIN_NAMESPACE() 35 36 META_REGISTER_INTERFACE(IAnimation, "37649f24-9ddd-4f8f-975b-9105db83cad0") 37 META_REGISTER_INTERFACE(IStartableAnimation, "1d1c7cac-0f13-421a-bbe8-f1aec751db6a") 38 META_REGISTER_INTERFACE(IPropertyAnimation, "501d9079-166e-4a59-a8f8-dfbae588bf80") 39 META_REGISTER_INTERFACE(IKeyframeAnimation, "75446215-498a-460f-8958-42f681c8becb") 40 META_REGISTER_INTERFACE(IStaggeredAnimation, "566ac43f-0408-403c-ab37-724687252ecd") 41 META_REGISTER_INTERFACE(ISequentialAnimation, "1c776172-f3d0-446c-8840-d487b916fbdd") 42 META_REGISTER_INTERFACE(IParallelAnimation, "5e9c463d-a442-46fe-8ee2-fb7396b1a90a") 43 META_REGISTER_INTERFACE(ITrackAnimation, "fdb5ee37-cd69-4591-8bc2-c13332baae18") 44 META_REGISTER_INTERFACE(ITimedAnimation, "4dacfc3d-747a-4bbb-88e7-505586d12c3f") 45 46 class IStaggeredAnimation; 47 48 /** 49 * @brief IAnimation is the base interface for all animations. 50 */ 51 class IAnimation : public INamed { 52 META_INTERFACE(INamed, IAnimation) 53 public: 54 /** 55 * @brief If true, the animation is enabled. If false, the animation 56 * remains stopped in the initial state. 57 * The default value is true. 58 */ 59 META_PROPERTY(bool, Enabled) 60 61 /** 62 * @brief True when the animation is in a valid state to be run. 63 * For a PropertyAnimation this means that the animation points 64 * to a valid property. For a StaggeredAnimation this means 65 * that the animation has valid child animations. 66 */ 67 META_READONLY_PROPERTY(bool, Valid) 68 69 /** 70 * @brief Duration of the animation after all animation modifiers have been applied. 71 */ 72 META_READONLY_PROPERTY(TimeSpan, TotalDuration) 73 74 /** 75 * @brief True when the animation is running, false otherwise. 76 */ 77 META_READONLY_PROPERTY(bool, Running) 78 79 /** 80 * @brief Animation state from [0,1] while the animation is running. When the animation 81 * has finished, the value will be 1. 82 */ 83 META_READONLY_PROPERTY(float, Progress) 84 85 /** 86 * @brief Animation follows this curve. 87 */ 88 META_PROPERTY(ICurve1D::Ptr, Curve) 89 90 /** 91 * @brief Controller which handles this animation. 92 * The default value is the controller returned by META_NS::GetAnimationController(). 93 * @note To completely detach the animation from any controller, set the property to nullptr. 94 * In such a case the user is responsible for manually stepping the animation 95 * whenever needed. 96 */ 97 META_PROPERTY(BASE_NS::weak_ptr<IAnimationController>, Controller) 98 99 /** 100 * @brief Steps the animation. Called by the framework, usually there is no 101 * need to call this manually. 102 */ 103 virtual void Step(const IClock::ConstPtr& clock) = 0; 104 105 /** 106 * @brief Invoked when the animation has reached the end. 107 */ 108 META_EVENT(IOnChanged, OnFinished) 109 /** 110 * @brief Invoked when the animation has started from the beginning. 111 */ 112 META_EVENT(IOnChanged, OnStarted) 113 }; 114 115 class IStartableAnimation : public CORE_NS::IInterface { 116 META_INTERFACE(CORE_NS::IInterface, IStartableAnimation) 117 public: 118 /** 119 * @brief Pauses the animation. 120 */ 121 virtual void Pause() = 0; 122 /** 123 * @brief Stops the animation and starts it from the beginning. 124 */ 125 virtual void Restart() = 0; 126 /** 127 * @brief Seeks animation to a specified position. 128 * 129 * @param position New Position of the animation. The value should be in 130 * [0, 1] range, otherwise it will be clamped. 131 */ 132 virtual void Seek(float position) = 0; 133 /** 134 * @brief Starts the animation. 135 */ 136 virtual void Start() = 0; 137 /** 138 * @brief Stops the animation. It resets animation progress. 139 */ 140 virtual void Stop() = 0; 141 /** 142 * @brief Jumps to the end of the animation. 143 */ 144 virtual void Finish() = 0; 145 }; 146 147 /** 148 * @brief The IStaggeredAnimation defines an interface for an animation container which 149 * takes control of how it's child animations are run. 150 */ 151 class IStaggeredAnimation : public IAnimation { 152 META_INTERFACE(IAnimation, IStaggeredAnimation) 153 public: 154 /** 155 * @brief Add a new animation to the container. 156 */ 157 virtual void AddAnimation(const IAnimation::Ptr&) = 0; 158 /** 159 * @brief Remove an animation from the container. 160 */ 161 virtual void RemoveAnimation(const IAnimation::Ptr&) = 0; 162 /** 163 * @brief Returns all direct child animations of this animation. 164 */ 165 virtual BASE_NS::vector<IAnimation::Ptr> GetAnimations() const = 0; 166 }; 167 168 /** 169 * @brief The ISequentialAnimation interface defines an interface for an animation container 170 * which runs its child animations in sequence one after another. 171 * 172 * Duration property is set by the container to reflect the total running time of all 173 * the animations added to the container. Setting the value has no effect. 174 */ 175 class ISequentialAnimation : public IStaggeredAnimation { 176 META_INTERFACE(IStaggeredAnimation, ISequentialAnimation) 177 public: 178 }; 179 180 /** 181 * @brief The IParallelAnimation interface defines an interface for an animation container 182 * which runs its child animations parallelly. 183 * 184 * Duration property is set by the container to reflect the running time of the longest 185 * running animation added to the container. Setting the value has no effect. 186 */ 187 class IParallelAnimation : public IStaggeredAnimation { 188 META_INTERFACE(IStaggeredAnimation, IParallelAnimation) 189 public: 190 }; 191 192 class ITimedAnimation : public IAnimation { 193 META_INTERFACE(IAnimation, ITimedAnimation) 194 public: 195 /** 196 * @brief Duration of the animation before any modifiers are applied. 197 */ 198 META_PROPERTY(TimeSpan, Duration) 199 }; 200 201 /** 202 * @brief IPropertyAnimation defines an interface for animations which can animate a property. 203 */ 204 class IPropertyAnimation : public CORE_NS::IInterface { 205 META_INTERFACE(CORE_NS::IInterface, IPropertyAnimation, META_NS::InterfaceId::IPropertyAnimation) 206 public: 207 /** 208 * @brief Target property for this animation. 209 * Once target property is set, the type of the animation will be automatically 210 * set to match the type of the target property. 211 */ 212 META_PROPERTY(IProperty::WeakPtr, Property) 213 }; 214 215 /** 216 * @brief IKeyframeAnimation can be used to define an explicit keyframe animation on a property between two values. 217 */ 218 class IKeyframeAnimation : public ITimedAnimation { 219 META_INTERFACE(ITimedAnimation, IKeyframeAnimation, META_NS::InterfaceId::IKeyframeAnimation) 220 public: 221 /** 222 * @brief A property containing the start value of the animation. 223 * Animation implementation will create a property of suitable type for the animation target property. 224 * @note The property is null until target property is set or IPropertyAnimation::SetType is called explicitly. 225 */ 226 META_PROPERTY(IAny::Ptr, From) 227 /** 228 * @brief A property containing the end value of the animation. 229 * Animation implementation will create a property of suitable type for the animation target property. 230 * @note The property is null until target property is set or IPropertyAnimation::SetType is called explicitly. 231 */ 232 META_PROPERTY(IAny::Ptr, To) 233 }; 234 235 /** 236 * @brief ITrackAnimation defines the interface for an animation track, which can have multiple keyframes associated 237 * with a set of timestamps. 238 * 239 * Functionality-wise a track animation is identical to a sequential animation with several keyframe animations 240 * all targetting the same property as it children. In such a case track animation is simpler to use and can 241 * also be implemented more efficiently by the framework. 242 */ 243 class ITrackAnimation : public CORE_NS::IInterface { 244 META_INTERFACE(CORE_NS::IInterface, ITrackAnimation, META_NS::InterfaceId::ITrackAnimation) 245 public: 246 /** 247 * @brief Value of CurrentKeyframeIndex when the animation is not in valid timestamp range. 248 */ 249 constexpr static uint32_t INVALID_INDEX = uint32_t(-1); 250 /** 251 * @brief TimeStamps for the animation. Timestamps are positions of the keyframes on the track, relative 252 * to the Duration of the animation. 253 * @note Number of timestamps must match the number of keyframes. 254 */ 255 META_ARRAY_PROPERTY(float, Timestamps) 256 /** 257 * @brief Keyframes for the animation. 258 * @note Number of keyframes must match the number of timestamps. 259 * @note KeyFrames property is invalid until target Property has been set, or IPropertyAnimation::SetType() 260 * has been called. 261 */ 262 virtual IProperty::Ptr Keyframes() const = 0; 263 /** 264 * @brief Array of curves used for interpolating between each keyframe. 265 * @note As the curves are used to interpolate between keyframes, the number of curves needed to cover 266 * the entire animation is the number of keyframes - 1. 267 * @note The array can contain nullptrs, in which case the keyframe is interpolated linearly. 268 * @note The array size does not need to match keyframe count. Any keyframes for whom a matching curve 269 * is not found in the array are interpolated linearly. 270 * @note IAnimation::Curve can be used for controlling the progress over the full animation duration. 271 */ 272 META_ARRAY_PROPERTY(ICurve1D::Ptr, KeyframeCurves) 273 /** 274 * @brief Array of functions that the track animation will call when the keyframe whose index corresponds 275 * to the index in the handler function array is reached. 276 * @note The array can also contain nullptrs if there is no handler for all frames. 277 */ 278 META_ARRAY_PROPERTY(IFunction::Ptr, KeyframeHandlers) 279 /** 280 * @brief Index of the current keyframe. 281 */ 282 META_READONLY_PROPERTY(uint32_t, CurrentKeyframeIndex) 283 /** 284 * @brief Adds a keyframe to the track animation. 285 * @param timestamp Timestamp of the new keyframe. The keyframe will be added to such an index which maintains 286 * ascending order of timestamps. 287 * @param from A property containing the value to be added. 288 * @return Index of the added keyframe or IMetaArrayProperty::N_POS in case of error. 289 */ 290 virtual size_t AddKeyframe(float timestamp, const IAny::ConstPtr& value) = 0; 291 /** 292 * @brief Removes a keyframe and its associated timestamp from the track animation. 293 * @param index Index to remove from. 294 * @return True if a keyframe was removed, false otherwise. 295 */ 296 virtual bool RemoveKeyframe(size_t index) = 0; 297 /** 298 * @brief Removes all keyframes and corresponding timestamps from the track animation. 299 */ 300 virtual void RemoveAllKeyframes() = 0; 301 }; 302 303 META_END_NAMESPACE() 304 305 META_INTERFACE_TYPE(META_NS::IAnimation) 306 META_INTERFACE_TYPE(META_NS::IPropertyAnimation) 307 META_INTERFACE_TYPE(META_NS::IKeyframeAnimation) 308 META_INTERFACE_TYPE(META_NS::IParallelAnimation) 309 META_INTERFACE_TYPE(META_NS::IStaggeredAnimation) 310 311 #endif 312