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 API_3D_ECS_SYSTEMS_IANIMATION_SYSTEM_H
17 #define API_3D_ECS_SYSTEMS_IANIMATION_SYSTEM_H
18 
19 #include <3d/ecs/components/animation_component.h>
20 #include <base/containers/string_view.h>
21 #include <core/ecs/intf_system.h>
22 
23 CORE_BEGIN_NAMESPACE()
24 struct Entity;
25 CORE_END_NAMESPACE()
26 
27 CORE3D_BEGIN_NAMESPACE()
28 class ISceneNode;
29 /** @ingroup group_ecs_systems_ianimation */
30 /**
31  * Animation Playback.
32  * Object which includes ways to control animation.
33  */
34 class IAnimationPlayback {
35 public:
36     /** Returns playback name. */
37     virtual BASE_NS::string_view GetName() const = 0;
38 
39     /** Sets playback state.
40      *  @param state can be one of the following states: STOP, PLAY and PAUSE.
41      */
42     virtual void SetPlaybackState(AnimationComponent::PlaybackState state) = 0;
43 
44     /** Returns playback state of this track.
45      */
46     virtual AnimationComponent::AnimationComponent::PlaybackState GetPlaybackState() const = 0;
47 
48     /** Sets number of times animation is repeated.
49      *  @param repeatCount number of repetition count or infinite if AnimationComponent::REPEAT_COUNT_INFINITE is
50      * passed.
51      */
52     virtual void SetRepeatCount(uint32_t repeatCount) = 0;
53 
54     /** Returns repetition count for playback clip.
55      */
56     virtual uint32_t GetRepeatCount() const = 0;
57 
58     /** Sets animation weight, used when multiple animations are blended together.
59      *  @param weight weight for the animation, in range from zero to one.
60      */
61     virtual void SetWeight(float weight) = 0;
62 
63     /** Returns animation weight, where 0.0 means that animation is not applied and 1.0 means that animation is applied
64      * in full strength.
65      */
66     virtual float GetWeight() const = 0;
67 
68     /** Set playback time position in seconds.
69      *  @param timePosition New time position for animation.
70      */
71     virtual void SetTimePosition(float timePosition) = 0;
72 
73     /** Returns current playback position in seconds. */
74     virtual float GetTimePosition() const = 0;
75 
76     /** Returns the length of the animation data in seconds. */
77     virtual float GetAnimationLength() const = 0;
78 
79     /** Set animation start time offset in seconds. */
80     virtual void SetStartOffset(float startOffset) = 0;
81 
82     /** Returns animation start time in seconds. */
83     virtual float GetStartOffset() const = 0;
84 
85     /** Set animation playback duration in seconds. */
86     virtual void SetDuration(float duration) = 0;
87 
88     /** Returns animation duration in seconds. */
89     virtual float GetDuration() const = 0;
90 
91     /** Returns boolean flag if animation playback is completed.
92      */
93     virtual bool IsCompleted() const = 0;
94 
95     /** Set speed for animation, can be also negative for reverse playback
96      */
97     virtual void SetSpeed(float) = 0;
98 
99     /** Get speed of animation currently in use
100      */
101     virtual float GetSpeed() const = 0;
102 
103     /** Get entity owning the animation component.
104      */
105     virtual CORE_NS::Entity GetEntity() const = 0;
106 
107 protected:
108     virtual ~IAnimationPlayback() = default;
109 };
110 
111 /** @ingroup group_ecs_systems_ianimation */
112 /**
113  * Animation System.
114  * System that has Creation and Destroying functions for Animation Playbacks(objects that control animation).
115  */
116 class IAnimationSystem : public CORE_NS::ISystem {
117 public:
118     static constexpr BASE_NS::Uid UID { "3937c464-0073-4900-865d-89da078b9daa" };
119 
120     /** Creates a playback object that allows to control animation state (play, pause etc).
121      *  This is intended for animations imported from glTF, which are limited to the node hierarchy.
122      *  @param animationEntity Entity owning the animation resource.
123      *  @param node Node to animate.
124      *  @return Playback object or nullptr if no animation is found.
125      */
126     virtual IAnimationPlayback* CreatePlayback(CORE_NS::Entity const& animationEntity, ISceneNode const& node) = 0;
127 
128     /** Creates a playback object that allows to control animation state (play, pause etc).
129      *  @param animationEntity Entity owning the animation resource.
130      *  @param targetEntities Target entity for each of the animation tracks.
131      *  @return Playback object or nullptr if no animation is found.
132      */
133     virtual IAnimationPlayback* CreatePlayback(
134         const CORE_NS::Entity animationEntity, const BASE_NS::array_view<const CORE_NS::Entity> targetEntities) = 0;
135 
136     /** Destroys given playback object
137      *  @param playback Playback object to be destroyed
138      */
139     virtual void DestroyPlayback(IAnimationPlayback* playback) = 0;
140 
141     /** Retrieve number of currently existing playback objects. */
142     virtual size_t GetPlaybackCount() const = 0;
143 
144     /** Retrieve playback object in given index. */
145     virtual IAnimationPlayback* GetPlayback(size_t index) const = 0;
146 
147 protected:
148     IAnimationSystem() = default;
149     IAnimationSystem(const IAnimationSystem&) = delete;
150     IAnimationSystem(IAnimationSystem&&) = delete;
151     IAnimationSystem& operator=(const IAnimationSystem&) = delete;
152     IAnimationSystem& operator=(IAnimationSystem&&) = delete;
153 };
154 
155 CORE3D_END_NAMESPACE()
156 
157 #endif // API_3D_ECS_SYSTEMS_IANIMATION_SYSTEM_H
158