fyrox_ui/
animation.rs

1// Copyright (c) 2019-present Dmitry Stepanov and Fyrox Engine contributors.
2//
3// Permission is hereby granted, free of charge, to any person obtaining a copy
4// of this software and associated documentation files (the "Software"), to deal
5// in the Software without restriction, including without limitation the rights
6// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7// copies of the Software, and to permit persons to whom the Software is
8// furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in all
11// copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19// SOFTWARE.
20
21//! Animation player is a node that contains multiple animations. It updates and plays all the animations.
22//! See [`AnimationPlayer`] docs for more info.
23
24use crate::MessageDirection;
25use crate::{
26    core::{
27        log::{Log, MessageKind},
28        pool::Handle,
29        reflect::prelude::*,
30        type_traits::prelude::*,
31        variable::InheritableVariable,
32        visitor::prelude::*,
33    },
34    define_constructor, define_widget_deref,
35    generic_animation::value::{BoundValueCollection, TrackValue, ValueBinding},
36    message::UiMessage,
37    widget::{Widget, WidgetBuilder},
38    BuildContext, Control, UiNode, UserInterface,
39};
40use fyrox_graph::constructor::{ConstructorProvider, GraphNodeConstructor};
41use fyrox_graph::BaseSceneGraph;
42use std::ops::{Deref, DerefMut};
43
44#[derive(Debug, Clone, PartialEq)]
45pub enum AnimationPlayerMessage {
46    EnableAnimation { animation: String, enabled: bool },
47    RewindAnimation { animation: String },
48    TimePosition { animation: String, time: f32 },
49}
50
51impl AnimationPlayerMessage {
52    define_constructor!(
53        /// Creates a new [Self::EnableAnimation] message.
54        AnimationPlayerMessage:EnableAnimation => fn enable_animation(animation: String, enabled: bool), layout: false
55    );
56    define_constructor!(
57        /// Creates a new [Self::RewindAnimation] message.
58        AnimationPlayerMessage:RewindAnimation => fn rewind_animation(animation: String), layout: false
59    );
60    define_constructor!(
61        /// Creates a new [Self::TimePosition] message.
62        AnimationPlayerMessage:TimePosition => fn time_position(animation: String, time: f32), layout: false
63    );
64}
65
66/// UI-specific animation.
67pub type Animation = crate::generic_animation::Animation<Handle<UiNode>>;
68/// UI-specific animation track.
69pub type Track = crate::generic_animation::track::Track;
70/// UI-specific animation container.
71pub type AnimationContainer = crate::generic_animation::AnimationContainer<Handle<UiNode>>;
72/// UI-specific animation pose.
73pub type AnimationPose = crate::generic_animation::AnimationPose<Handle<UiNode>>;
74/// UI-specific animation node pose.
75pub type NodePose = crate::generic_animation::NodePose<Handle<UiNode>>;
76
77/// Standard prelude for animations, that contains all most commonly used types and traits.
78pub mod prelude {
79    pub use super::{
80        Animation, AnimationContainer, AnimationContainerExt, AnimationPlayer,
81        AnimationPlayerBuilder, AnimationPose, AnimationPoseExt, BoundValueCollectionExt, NodePose,
82        Track,
83    };
84    pub use crate::generic_animation::{
85        container::{TrackDataContainer, TrackValueKind},
86        signal::AnimationSignal,
87        value::{BoundValueCollection, TrackValue, ValueBinding, ValueType},
88        AnimationEvent,
89    };
90}
91
92/// Extension trait for [`AnimationContainer`].
93pub trait AnimationContainerExt {
94    /// Updates all animations in the container and applies their poses to respective nodes. This method is intended to
95    /// be used only by the internals of the engine!
96    fn update_animations(&mut self, nodes: &mut UserInterface, dt: f32);
97}
98
99impl AnimationContainerExt for AnimationContainer {
100    fn update_animations(&mut self, ui: &mut UserInterface, dt: f32) {
101        for animation in self.iter_mut().filter(|anim| anim.is_enabled()) {
102            animation.tick(dt);
103            animation.pose().apply(ui);
104        }
105    }
106}
107
108/// Extension trait for [`AnimationPose`].
109pub trait AnimationPoseExt {
110    /// Tries to set each value to the each property from the animation pose to respective widgets.
111    fn apply(&self, ui: &mut UserInterface);
112}
113
114impl AnimationPoseExt for AnimationPose {
115    fn apply(&self, ui: &mut UserInterface) {
116        for (node, local_pose) in self.poses() {
117            if node.is_none() {
118                Log::writeln(MessageKind::Error, "Invalid node handle found for animation pose, most likely it means that animation retargeting failed!");
119            } else if let Some(node) = ui.try_get_mut(*node) {
120                node.invalidate_layout();
121
122                local_pose.values.apply(node);
123            }
124        }
125    }
126}
127
128/// Extension trait for [`BoundValueCollection`].
129pub trait BoundValueCollectionExt {
130    /// Tries to set each value from the collection to the respective property (by binding) of the
131    /// given widget.
132    fn apply(&self, node_ref: &mut UiNode);
133}
134
135impl BoundValueCollectionExt for BoundValueCollection {
136    fn apply(&self, node_ref: &mut UiNode) {
137        for bound_value in self.values.iter() {
138            match bound_value.binding {
139                ValueBinding::Position => {
140                    if let TrackValue::Vector2(v) = bound_value.value {
141                        node_ref.set_desired_local_position(v);
142                    } else {
143                        Log::err(
144                            "Unable to apply position, because underlying type is not Vector2!",
145                        )
146                    }
147                }
148                ValueBinding::Scale => Log::warn("Implement me!"),
149                ValueBinding::Rotation => Log::warn("Implement me!"),
150                ValueBinding::Property {
151                    name: ref property_name,
152                    value_type,
153                } => bound_value.apply_to_object(node_ref, property_name, value_type),
154            }
155        }
156    }
157}
158
159/// Animation player is a node that contains multiple animations. It updates and plays all the animations.
160/// The node could be a source of animations for animation blending state machines. To learn more about
161/// animations, see [`Animation`] docs.
162#[derive(Visit, Reflect, Clone, Debug, ComponentProvider)]
163pub struct AnimationPlayer {
164    widget: Widget,
165    #[component(include)]
166    pub(crate) animations: InheritableVariable<AnimationContainer>,
167    #[component(include)]
168    auto_apply: bool,
169}
170
171impl ConstructorProvider<UiNode, UserInterface> for AnimationPlayer {
172    fn constructor() -> GraphNodeConstructor<UiNode, UserInterface> {
173        GraphNodeConstructor::new::<Self>()
174            .with_variant("Animation Player", |ui| {
175                AnimationPlayerBuilder::new(WidgetBuilder::new().with_name("Animation Player"))
176                    .build(&mut ui.build_ctx())
177                    .into()
178            })
179            .with_group("Animation")
180    }
181}
182
183impl Default for AnimationPlayer {
184    fn default() -> Self {
185        Self {
186            widget: Default::default(),
187            animations: Default::default(),
188            auto_apply: true,
189        }
190    }
191}
192
193impl AnimationPlayer {
194    /// Enables or disables automatic animations update and pose applying. If auto applying is enabled,
195    /// then every animation in this node is updated first, and then their output pose could be applied
196    /// to the graph, so the animation takes effect. Automatic applying is useful when you need your
197    /// animations to be applied immediately to the graph, but in some cases (if you're using animation
198    /// blending state machines for example) this functionality is undesired.
199    ///
200    /// Animation blending machines hijacks control over the animation container and updates only
201    /// active animations, instead of all available. This is much better for performance than updating
202    /// all at once.
203    pub fn set_auto_apply(&mut self, auto_apply: bool) {
204        self.auto_apply = auto_apply;
205    }
206
207    /// Returns `true` if the node is automatically applying output poses of animations to the graph, `false` -
208    /// otherwise.
209    pub fn is_auto_apply(&self) -> bool {
210        self.auto_apply
211    }
212
213    /// Returns a reference to internal animations container.
214    pub fn animations(&self) -> &InheritableVariable<AnimationContainer> {
215        &self.animations
216    }
217
218    /// Returns a reference to internal animations container. Keep in mind that mutable access to [`InheritableVariable`]
219    /// may have side effects if used inappropriately. Checks docs for [`InheritableVariable`] for more info.
220    pub fn animations_mut(&mut self) -> &mut InheritableVariable<AnimationContainer> {
221        &mut self.animations
222    }
223
224    /// Sets new animations container of the animation player.
225    pub fn set_animations(&mut self, animations: AnimationContainer) {
226        self.animations.set_value_and_mark_modified(animations);
227    }
228
229    fn find_animation(&mut self, name: &str) -> Option<&mut Animation> {
230        self.animations.find_by_name_mut(name).map(|(_, a)| a)
231    }
232}
233
234impl TypeUuidProvider for AnimationPlayer {
235    fn type_uuid() -> Uuid {
236        uuid!("44d1c94e-354f-4f9a-b918-9d31c28aa16a")
237    }
238}
239
240define_widget_deref!(AnimationPlayer);
241
242impl Control for AnimationPlayer {
243    fn handle_routed_message(&mut self, ui: &mut UserInterface, message: &mut UiMessage) {
244        self.widget.handle_routed_message(ui, message);
245
246        if let Some(msg) = message.data::<AnimationPlayerMessage>() {
247            match msg {
248                AnimationPlayerMessage::EnableAnimation { animation, enabled } => {
249                    if let Some(animation) = self.find_animation(animation) {
250                        animation.set_enabled(*enabled);
251                    }
252                }
253                AnimationPlayerMessage::RewindAnimation { animation } => {
254                    if let Some(animation) = self.find_animation(animation) {
255                        animation.rewind();
256                    }
257                }
258                AnimationPlayerMessage::TimePosition { animation, time } => {
259                    if let Some(animation) = self.find_animation(animation) {
260                        animation.set_time_position(*time);
261                    }
262                }
263            }
264        }
265    }
266
267    fn update(&mut self, dt: f32, ui: &mut UserInterface) {
268        if self.auto_apply {
269            self.animations
270                .get_value_mut_silent()
271                .update_animations(ui, dt);
272        }
273    }
274}
275
276/// A builder for [`AnimationPlayer`] node.
277pub struct AnimationPlayerBuilder {
278    widget_builder: WidgetBuilder,
279    animations: AnimationContainer,
280    auto_apply: bool,
281}
282
283impl AnimationPlayerBuilder {
284    /// Creates new builder instance.
285    pub fn new(widget_builder: WidgetBuilder) -> Self {
286        Self {
287            widget_builder,
288            animations: AnimationContainer::new(),
289            auto_apply: true,
290        }
291    }
292
293    /// Sets a container with desired animations.
294    pub fn with_animations(mut self, animations: AnimationContainer) -> Self {
295        self.animations = animations;
296        self
297    }
298
299    /// Enables or disables automatic pose applying. See [`AnimationPlayer::set_auto_apply`] docs for more info.
300    pub fn with_auto_apply(mut self, auto_apply: bool) -> Self {
301        self.auto_apply = auto_apply;
302        self
303    }
304
305    /// Creates an instance of [`AnimationPlayer`] node.
306    pub fn build_node(self, ctx: &BuildContext) -> UiNode {
307        UiNode::new(AnimationPlayer {
308            widget: self.widget_builder.with_need_update(true).build(ctx),
309            animations: self.animations.into(),
310            auto_apply: self.auto_apply,
311        })
312    }
313
314    /// Creates an instance of [`AnimationPlayer`] node and adds it to the given user interface.
315    pub fn build(self, ctx: &mut BuildContext) -> Handle<UiNode> {
316        ctx.add_node(self.build_node(ctx))
317    }
318}
319
320#[cfg(test)]
321mod test {
322    use crate::animation::AnimationPlayerBuilder;
323    use crate::{test::test_widget_deletion, widget::WidgetBuilder};
324
325    #[test]
326    fn test_deletion() {
327        test_widget_deletion(|ctx| AnimationPlayerBuilder::new(WidgetBuilder::new()).build(ctx));
328    }
329}
fyrox_ui/animation.rs

fyrox_ui/
animation.rs
