starting to implement MD3 motion library

Author: MovGP0

Directory.packages.props

@@ -32,5 +32,6 @@
     <PackageVersion Include="System.Memory" Version="4.6.3" />
     <PackageVersion Include="System.ValueTuple" Version="4.6.1" />
     <PackageVersion Include="Polyfill" Version="8.8.1" />
+    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
   </ItemGroup>
 </Project>

MaterialDesignToolkit.Full.sln

@@ -1,4 +1,4 @@
-Microsoft Visual Studio Solution File, Format Version 12.00
+Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31612.314
 MinimumVisualStudioVersion = 10.0.40219.1
@@ -67,6 +67,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MaterialColorUtilities", "s
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MaterialColorUtilities.Tests", "tests\MaterialColorUtilities.Tests\MaterialColorUtilities.Tests.csproj", "{91485BEA-759F-406E-87B7-68D94CF66DE4}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MaterialDesignThemes.Motion", "src\MaterialDesign3.Motion\Motion.csproj", "{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -287,6 +289,22 @@ Global
 		{91485BEA-759F-406E-87B7-68D94CF66DE4}.Release|x64.Build.0 = Release|Any CPU
 		{91485BEA-759F-406E-87B7-68D94CF66DE4}.Release|x86.ActiveCfg = Release|Any CPU
 		{91485BEA-759F-406E-87B7-68D94CF66DE4}.Release|x86.Build.0 = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|ARM.ActiveCfg = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|ARM.Build.0 = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|x64.Build.0 = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Debug|x86.Build.0 = Debug|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|ARM.ActiveCfg = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|ARM.Build.0 = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|x64.ActiveCfg = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|x64.Build.0 = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|x86.ActiveCfg = Release|Any CPU
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -300,6 +318,7 @@ Global
 		{B39795A7-D66A-4F2F-9F41-050838D14048} = {D34BE232-DE51-43C1-ABDC-B69003BB50FF}
 		{2C29B80E-1689-43CE-85AC-71799666B4AC} = {9E303A4A-3712-44B9-91EE-830FDC087795}
 		{91485BEA-759F-406E-87B7-68D94CF66DE4} = {9E303A4A-3712-44B9-91EE-830FDC087795}
+		{3F7E3CFD-BAE6-4DC4-9C8D-A001138BD87F} = {9E303A4A-3712-44B9-91EE-830FDC087795}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {730B2F9E-74AE-46CE-9E61-89AA5C6D5DD3}

src/MaterialDesign3.Motion/AnimationEndReason.cs

@@ -0,0 +1,21 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// Possible reasons for <see cref="Animatable{T, V}"/>s to end.
+/// </summary>
+public enum AnimationEndReason
+{
+    /// <summary>
+    /// Animation will be forced to end when its value reaches upper/lower bound (if they have been
+    /// defined, e.g. via <c>Animatable.updateBounds</c>).
+    /// Unlike <see cref="Finished"/>, when an animation ends due to <see cref="BoundReached"/>, it often falls
+    /// short from its initial target, and the remaining velocity is often non-zero. Both the end value and the
+    /// remaining velocity can be obtained via <c>AnimationResult</c>.
+    /// </summary>
+    BoundReached,
+
+    /// <summary>
+    /// Animation has finished successfully without any interruption.
+    /// </summary>
+    Finished,
+}

src/MaterialDesign3.Motion/AnimationParameters.cs

@@ -0,0 +1,33 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// Animation specs of duration, easing and repeat delay.
+/// </summary>
+public sealed class AnimationParameters
+{
+    /// <summary>
+    /// The duration of the animation.
+    /// </summary>
+    /// <remarks>
+    /// If not set, defaults to 300ms.
+    /// </remarks>
+    public TimeSpan Duration { get; set; } = TimeSpan.FromMilliseconds(300);
+
+    /// <summary>
+    /// The easing to be used for adjusting an animation's fraction.
+    /// </summary>
+    /// <remarks>
+    /// If not set, defaults to Linear Interpolation.
+    /// </remarks>
+    public Easing? Easing { get; set; }
+
+    /// <summary>
+    /// Animation delay in millis.
+    /// </summary>
+    /// <remarks>
+    /// When used outside repeatable, this is the delay to start the animation.
+    /// When set inside repeatable, this is the delay before repeating animation.
+    /// If not set, no delay will be applied.
+    /// </remarks>
+    public TimeSpan? Delay { get; set; } = TimeSpan.FromMilliseconds(3);
+}

src/MaterialDesign3.Motion/AnimationSpec.cs

@@ -0,0 +1,20 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// Animation parameters that can be added to any animatable node.
+/// </summary>
+public sealed class AnimationSpec
+{
+    /// <summary>
+    /// Animation parameters including duration, easing and repeat delay.
+    /// </summary>
+    public AnimationParameters AnimationParameters { get; set; } = new();
+
+    /// <summary>
+    /// The repeatable mode to be used for specifying repetition parameters for the animation.
+    /// </summary>
+    /// <remarks>
+    /// If not set, animation won't be repeated.
+    /// </remarks>
+    public Repeatable? Repeatable { get; set; }
+}

src/MaterialDesign3.Motion/AnimationVector.cs

@@ -0,0 +1,26 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// <see cref="AnimationVector"/> class that is the base class of <see cref="AnimationVector1D"/>,
+/// <see cref="AnimationVector2D"/>, <see cref="AnimationVector3D"/> and <see cref="AnimationVector4D"/>.
+/// In order to animate any arbitrary type, it is required to provide a <see cref="ITwoWayConverter{T,TAnimationVector}"/>
+/// that defines how to convert that arbitrary type T to an <see cref="AnimationVector"/>, and vice versa.
+/// </summary>
+public abstract class AnimationVector
+{
+    internal abstract void Reset();
+
+    internal abstract AnimationVector NewVector();
+
+    internal abstract float GetValue(int index);
+
+    internal abstract void SetValue(int index, float value);
+
+    internal abstract int Size { get; }
+
+    public float this[int index]
+    {
+        get => GetValue(index);
+        set => SetValue(index, value);
+    }
+}

src/MaterialDesign3.Motion/AnimationVector1D.cs

@@ -0,0 +1,42 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// This class defines a 1D vector. It contains only one Float value that is initialized in the constructor.
+/// </summary>
+public sealed class AnimationVector1D : AnimationVector
+{
+    public AnimationVector1D()
+        : this(0f)
+    {
+    }
+
+    public AnimationVector1D(float value)
+    {
+        Value = value;
+    }
+
+    public float Value { get; internal set; }
+
+    internal override void Reset() => Value = 0f;
+
+    internal override AnimationVector NewVector() => new AnimationVector1D(0f);
+
+    internal override float GetValue(int index) => index == 0 ? Value : 0f;
+
+    internal override void SetValue(int index, float value)
+    {
+        if (index == 0)
+        {
+            Value = value;
+        }
+    }
+
+    internal override int Size => 1;
+
+    public override string ToString() => $"AnimationVector1D(Value = {Value})";
+
+    public override bool Equals(object? obj) =>
+        obj is AnimationVector1D other && other.Value.Equals(Value);
+
+    public override int GetHashCode() => Value.GetHashCode();
+}

src/MaterialDesign3.Motion/AnimationVector2D.cs

@@ -0,0 +1,59 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// This class defines a 2D vector that contains two Float value fields.
+/// </summary>
+public sealed class AnimationVector2D : AnimationVector
+{
+    public AnimationVector2D()
+        : this(0f, 0f)
+    {
+    }
+
+    public AnimationVector2D(float v1, float v2)
+    {
+        V1 = v1;
+        V2 = v2;
+    }
+
+    public float V1 { get; internal set; }
+
+    public float V2 { get; internal set; }
+
+    internal override void Reset()
+    {
+        V1 = 0f;
+        V2 = 0f;
+    }
+
+    internal override AnimationVector NewVector() => new AnimationVector2D(0f, 0f);
+
+    internal override float GetValue(int index) => index switch
+    {
+        0 => V1,
+        1 => V2,
+        _ => 0f,
+    };
+
+    internal override void SetValue(int index, float value)
+    {
+        switch (index)
+        {
+            case 0:
+                V1 = value;
+                break;
+            case 1:
+                V2 = value;
+                break;
+        }
+    }
+
+    internal override int Size => 2;
+
+    public override string ToString() => $"AnimationVector2D(V1 = {V1}, V2 = {V2})";
+
+    public override bool Equals(object? obj) =>
+        obj is AnimationVector2D other && other.V1.Equals(V1) && other.V2.Equals(V2);
+
+    public override int GetHashCode() => HashCode.Combine(V1, V2);
+}

src/MaterialDesign3.Motion/AnimationVector3D.cs

@@ -0,0 +1,70 @@
+namespace MaterialDesignThemes.Motion;
+
+/// <summary>
+/// This class defines a 3D vector that contains three Float value fields for the three dimensions.
+/// </summary>
+public sealed class AnimationVector3D : AnimationVector
+{
+    public AnimationVector3D()
+        : this(0f, 0f, 0f)
+    {
+    }
+
+    public AnimationVector3D(float v1, float v2, float v3)
+    {
+        V1 = v1;
+        V2 = v2;
+        V3 = v3;
+    }
+
+    public float V1 { get; internal set; }
+
+    public float V2 { get; internal set; }
+
+    public float V3 { get; internal set; }
+
+    internal override void Reset()
+    {
+        V1 = 0f;
+        V2 = 0f;
+        V3 = 0f;
+    }
+
+    internal override AnimationVector NewVector() => new AnimationVector3D(0f, 0f, 0f);
+
+    internal override float GetValue(int index) => index switch
+    {
+        0 => V1,
+        1 => V2,
+        2 => V3,
+        _ => 0f,
+    };
+
+    internal override void SetValue(int index, float value)
+    {
+        switch (index)
+        {
+            case 0:
+                V1 = value;
+                break;
+            case 1:
+                V2 = value;
+                break;
+            case 2:
+                V3 = value;
+                break;
+        }
+    }
+
+    internal override int Size => 3;
+
+    public override string ToString() => $"AnimationVector3D(V1 = {V1}, V2 = {V2}, V3 = {V3})";
+
+    public override bool Equals(object? obj) =>
+        obj is AnimationVector3D other &&
+        other.V1.Equals(V1) &&
+        other.V2.Equals(V2) &&
+        other.V3.Equals(V3);
+
+    public override int GetHashCode() => HashCode.Combine(V1, V2, V3);
+}