1 #ifndef DALI_INTERNAL_SCENE_GRAPH_ANIMATION_H
2 #define DALI_INTERNAL_SCENE_GRAPH_ANIMATION_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/animation/animation.h>
24 #include <dali/internal/common/buffer-index.h>
25 #include <dali/internal/common/message.h>
26 #include <dali/internal/event/common/event-thread-services.h>
27 #include <dali/internal/update/animation/scene-graph-animator.h>
36 * Animations are used to change the properties of scene graph objects, as part of a scene
37 * managers "update" phase. An animation is a container of Animator objects; the actual setting
38 * of object values is done by the animators.
43 using EndAction = Dali::Animation::EndAction;
54 * Construct a new Animation.
55 * @param[in] durationSeconds The duration of the animation in seconds.
56 * @param[in] speedFactor Multiplier to the animation velocity.
57 * @param[in] playRange Minimum and maximum progress between which the animation will play.
58 * @param[in] loopCount The number of times the animation will loop. ( See SetLoopCount() )
59 * @param[in] endAction The action to perform when the animation ends.
60 * @param[in] disconnectAction The action to perform when the property owner of an animator is disconnected.
61 * @return A new Animation
63 static Animation* New(float durationSeconds, float speedFactor, const Vector2& playRange, int32_t loopCount, EndAction endAction, EndAction disconnectAction);
71 * Overriden delete operator
72 * Deletes the animation from its global memory pool
74 void operator delete(void* ptr);
77 * Set the duration of an animation.
78 * @pre durationSeconds must be greater than zero.
79 * @param[in] durationSeconds The duration in seconds.
81 void SetDuration(float durationSeconds);
84 * Set the progress marker to trigger notification
85 * @param[in] progress percent of progress to trigger notification, 0.0f < progress <= 1.0f
87 void SetProgressNotification(float progress);
90 * Retrieve the duration of the animation.
91 * @return The duration in seconds.
93 float GetDuration() const
95 return mDurationSeconds;
99 * Retrieve the current progress of the animation.
100 * @return The current progress as a normalized value between [0,1].
102 float GetCurrentProgress() const
104 if(mDurationSeconds > 0.0f)
106 return mElapsedSeconds / mDurationSeconds;
113 * Sets the progress of the animation.
114 * @param[in] The new progress as a normalized value between [0,1]
116 void SetCurrentProgress(float progress)
118 mElapsedSeconds = mDurationSeconds * progress;
122 * Specifies a speed factor for the animation.
123 * @param[in] factor A value which will multiply the velocity
125 void SetSpeedFactor(float factor)
127 mSpeedFactor = factor;
131 * Set the animation loop count.
132 * 0 is loop forever, N loop play N times
133 * @param[in] loopCount The loop count
135 void SetLoopCount(int32_t loopCount);
138 * Query whether the animation will loop.
139 * @return True if the animation will loop.
141 bool IsLooping() const
143 return mLoopCount != 1;
148 * @return the loop count
150 int32_t GetLoopCount() const
156 * Set the end action of the animation.
157 * @param[in] action The end action.
159 void SetEndAction(EndAction action);
162 * Retrieve the action performed when the animation ends.
163 * @return The end action.
165 EndAction GetEndAction()
171 * Set the disconnect action of the animation when connected objects are disconnected.
172 * This action is performed during the next update when
173 * the connected object is disconnected.
174 * @param[in] action The disconnect action.
176 void SetDisconnectAction(EndAction action);
179 * Retrieve the action performed when the animation is destroyed.
180 * @return The destroy action.
182 EndAction GetDisconnectAction()
184 return mDisconnectAction;
188 * Set the playing range. The animation will only play between the minimum and maximum progress
191 * @param[in] range Two values between [0,1] to specify minimum and maximum progress.
193 void SetPlayRange(const Vector2& range);
196 * Play the animation.
201 * Play the animation from a given point
202 * @param[in] progress A value between [0,1] form where the animation should start playing
204 void PlayFrom(float progress);
207 * @brief Play the animation after a given delay time.
208 * @param[in] delaySeconds The delay time
210 void PlayAfter(float delaySeconds);
213 * Pause the animation.
218 * Stop the animation.
219 * @param[in] bufferIndex The buffer to update when mEndAction == Bake.
220 * @return True if the animation has finished (otherwise it wasn't playing)
222 bool Stop(BufferIndex bufferIndex);
225 * Called shortly before the animation is destroyed.
226 * @param[in] bufferIndex The buffer to update when mEndAction == Bake.
228 void OnDestroy(BufferIndex bufferIndex);
231 * Query whether the animation is playing, paused or stopped.
232 * Note that even when paused, the Update() method should be called,
233 * since the current progress must be reapplied each frame.
235 State GetState() const
241 * Retrive a count of the number of times the animation has been played to completion.
242 * This can be used to emit "Finised" signals from the public-api
244 int32_t GetPlayedCount() const
250 * Get the current loop count from zero to GetLoopCount().
252 int32_t GetCurrentLoop() const
258 * Query whether the animation is currently active (i.e. at least one of the animators has been updated in either frame)
259 * @return True if the animation is currently active
261 bool IsActive() const
263 // As we have double buffering, if animator is updated in either frame, it needs to be rendered.
264 return mIsActive[0] || mIsActive[1];
268 * @brief Sets the looping mode.
270 * Animation plays forwards and then restarts from the beginning or runs backwards again.
271 * @param[in] loopingMode True when the looping mode is AUTO_REVERSE
273 void SetLoopingMode(bool loopingMode);
276 * Add a newly created animator.
277 * Animators are automatically removed, when orphaned from an animatable scene object.
278 * @param[in] animator The animator to add.
279 * @param[in] propertyOwner The scene-object that owns the animatable property.
280 * @post The animator is owned by this animation.
282 void AddAnimator(OwnerPointer<AnimatorBase>& animator);
285 * This causes the animators to change the properties of objects in the scene graph.
286 * @pre The animation is playing or paused.
287 * @param[in] bufferIndex The buffer to update.
288 * @param[in] elapsedSeconds The time elapsed since the previous frame.
289 * @param[out] looped True if the animation looped
290 * @param[out] finished True if the animation has finished.
291 * @param[out] progressReached True if progress marker reached
293 void Update(BufferIndex bufferIndex, float elapsedSeconds, bool& looped, bool& finished, bool& progressReached);
295 static uint32_t GetMemoryPoolCapacity();
299 * Protected constructor. See New()
301 Animation(float durationSeconds, float speedFactor, const Vector2& playRange, int32_t loopCount, EndAction endAction, EndAction disconnectAction);
305 * Helper for Update, also used to bake when the animation is stopped or destroyed.
306 * @param[in] bufferIndex The buffer to update.
307 * @param[in] bake True if the final result should be baked.
308 * @param[in] animationFinished True if the animation has finished.
310 void UpdateAnimators(BufferIndex bufferIndex, bool bake, bool animationFinished);
313 * Helper function to bake the result of the animation when it is stopped or
315 * @param[in] bufferIndex The buffer to update.
316 * @param[in] action The end action specified.
318 void Bake(BufferIndex bufferIndex, EndAction action);
321 * Helper function to set active state of animators.
322 * @param[in] active Every animator is set to this state
324 void SetAnimatorsActive(bool active);
327 Animation(const Animation&);
330 Animation& operator=(const Animation& rhs);
333 OwnerContainer<AnimatorBase*> mAnimators;
337 float mDurationSeconds;
339 float mElapsedSeconds;
341 float mProgressMarker; // Progress marker to trigger a notification
343 int32_t mPlayedCount; // Incremented at end of animation or completion of all loops
344 // Never incremented when looping forever. Event thread tracks to signal end.
345 int32_t mLoopCount; // N loop setting
346 int32_t mCurrentLoop; // Current loop number
348 EndAction mEndAction;
349 EndAction mDisconnectAction;
353 bool mProgressReachedSignalRequired; // Flag to indicate the progress marker was hit
354 bool mAutoReverseEnabled; // Flag to identify that the looping mode is auto reverse.
355 bool mIsActive[2]; // Flag to indicate whether the animation is active in the current frame (which is double buffered)
358 }; //namespace SceneGraph
360 // value types used by messages
362 struct ParameterType<Dali::Animation::EndAction> : public BasicType<Dali::Animation::EndAction>
368 // Messages for Animation
370 inline void SetDurationMessage(EventThreadServices& eventThreadServices, const Animation& animation, float durationSeconds)
372 using LocalType = MessageValue1<Animation, float>;
374 // Reserve some memory inside the message queue
375 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
377 // Construct message in the message queue memory; note that delete should not be called on the return value
378 new(slot) LocalType(&animation, &Animation::SetDuration, durationSeconds);
381 inline void SetProgressNotificationMessage(EventThreadServices& eventThreadServices, const Animation& animation, float progress)
383 using LocalType = MessageValue1<Animation, float>;
385 // Reserve some memory inside the message queue
386 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
388 // Construct message in the message queue memory; note that delete should not be called on the return value
389 new(slot) LocalType(&animation, &Animation::SetProgressNotification, progress);
392 inline void SetLoopingMessage(EventThreadServices& eventThreadServices, const Animation& animation, int32_t loopCount)
394 using LocalType = MessageValue1<Animation, int32_t>;
396 // Reserve some memory inside the message queue
397 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
399 // Construct message in the message queue memory; note that delete should not be called on the return value
400 new(slot) LocalType(&animation, &Animation::SetLoopCount, loopCount);
403 inline void SetEndActionMessage(EventThreadServices& eventThreadServices, const Animation& animation, Dali::Animation::EndAction action)
405 using LocalType = MessageValue1<Animation, Dali::Animation::EndAction>;
407 // Reserve some memory inside the message queue
408 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
410 // Construct message in the message queue memory; note that delete should not be called on the return value
411 new(slot) LocalType(&animation, &Animation::SetEndAction, action);
414 inline void SetDisconnectActionMessage(EventThreadServices& eventThreadServices, const Animation& animation, Dali::Animation::EndAction action)
416 using LocalType = MessageValue1<Animation, Dali::Animation::EndAction>;
418 // Reserve some memory inside the message queue
419 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
421 // Construct message in the message queue memory; note that delete should not be called on the return value
422 new(slot) LocalType(&animation, &Animation::SetDisconnectAction, action);
425 inline void SetCurrentProgressMessage(EventThreadServices& eventThreadServices, const Animation& animation, float progress)
427 using LocalType = MessageValue1<Animation, float>;
429 // Reserve some memory inside the message queue
430 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
432 // Construct message in the message queue memory; note that delete should not be called on the return value
433 new(slot) LocalType(&animation, &Animation::SetCurrentProgress, progress);
436 inline void SetSpeedFactorMessage(EventThreadServices& eventThreadServices, const Animation& animation, float factor)
438 using LocalType = MessageValue1<Animation, float>;
440 // Reserve some memory inside the message queue
441 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
443 // Construct message in the message queue memory; note that delete should not be called on the return value
444 new(slot) LocalType(&animation, &Animation::SetSpeedFactor, factor);
447 inline void SetPlayRangeMessage(EventThreadServices& eventThreadServices, const Animation& animation, const Vector2& range)
449 using LocalType = MessageValue1<Animation, Vector2>;
451 // Reserve some memory inside the message queue
452 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
454 // Construct message in the message queue memory; note that delete should not be called on the return value
455 new(slot) LocalType(&animation, &Animation::SetPlayRange, range);
458 inline void PlayAnimationMessage(EventThreadServices& eventThreadServices, const Animation& animation)
460 using LocalType = Message<Animation>;
462 // Reserve some memory inside the message queue
463 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
465 // Construct message in the message queue memory; note that delete should not be called on the return value
466 new(slot) LocalType(&animation, &Animation::Play);
469 inline void PlayAnimationFromMessage(EventThreadServices& eventThreadServices, const Animation& animation, float progress)
471 using LocalType = MessageValue1<Animation, float>;
473 // Reserve some memory inside the message queue
474 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
476 // Construct message in the message queue memory; note that delete should not be called on the return value
477 new(slot) LocalType(&animation, &Animation::PlayFrom, progress);
480 inline void PauseAnimationMessage(EventThreadServices& eventThreadServices, const Animation& animation)
482 using LocalType = Message<Animation>;
484 // Reserve some memory inside the message queue
485 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
487 // Construct message in the message queue memory; note that delete should not be called on the return value
488 new(slot) LocalType(&animation, &Animation::Pause);
491 inline void AddAnimatorMessage(EventThreadServices& eventThreadServices, const Animation& animation, AnimatorBase& animator)
493 using LocalType = MessageValue1<Animation, OwnerPointer<AnimatorBase> >;
495 // Reserve some memory inside the message queue
496 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
498 // Construct message in the message queue memory; note that delete should not be called on the return value
499 OwnerPointer<AnimatorBase> parameter(&animator);
500 new(slot) LocalType(&animation, &Animation::AddAnimator, parameter);
503 inline void PlayAfterMessage(EventThreadServices& eventThreadServices, const Animation& animation, float delaySeconds)
505 using LocalType = MessageValue1<Animation, float>;
507 // Reserve some memory inside the message queue
508 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
510 // Construct message in the message queue memory; note that delete should not be called on the return value
511 new(slot) LocalType(&animation, &Animation::PlayAfter, delaySeconds);
514 inline void SetLoopingModeMessage(EventThreadServices& eventThreadServices, const Animation& animation, bool loopingMode)
516 using LocalType = MessageValue1<Animation, bool>;
518 // Reserve some memory inside the message queue
519 uint32_t* slot = eventThreadServices.ReserveMessageSlot(sizeof(LocalType));
521 // Construct message in the message queue memory; note that delete should not be called on the return value
522 new(slot) LocalType(&animation, &Animation::SetLoopingMode, loopingMode);
525 } // namespace SceneGraph
527 } // namespace Internal
531 #endif // DALI_INTERNAL_SCENE_GRAPH_ANIMATION_H