From c47e49d516de396f8efbdfd062be0a0573e032f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=C3=AF=7E?= Date: Fri, 5 Jul 2024 02:30:01 +0200 Subject: [PATCH] Work towards correcting inconsistencies in the API: - Rename *Percent to *Normalized. - Update inline documentation. - Add additional single-valued and array overloads. - Add AacFlSettingCurveObjectReference.WithUnit to be on-par with AacFlSettingCurve. --- .../V1/Editor/AacFlAnimations.cs | 102 ++++++++++++++++-- .../V1/Editor/AacFlStates.cs | 24 ++++- 2 files changed, 116 insertions(+), 10 deletions(-) diff --git a/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlAnimations.cs b/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlAnimations.cs index d31aed6..d4e30d8 100644 --- a/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlAnimations.cs +++ b/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlAnimations.cs @@ -119,8 +119,88 @@ namespace AnimatorAsCode.V1 return this; } + + public AacFlClip Positioning(Transform transform, Vector3 localPosition) + { + // Single-valued overloads must not tolerate null values + if (transform == null) throw new NullReferenceException("Transform must not be null"); + return Positioning(new GameObject[]{ transform.gameObject }, localPosition); + } + + public AacFlClip RotatingUsingEulerInterpolation(Transform transform, Vector3 localEulerAngles) + { + // Single-valued overloads must not tolerate null values + if (transform == null) throw new NullReferenceException("Transform must not be null"); + return RotatingUsingEulerInterpolation(new GameObject[]{ transform.gameObject }, localEulerAngles); + } + + public AacFlClip RotatingUsingQuaternionInterpolation(Transform transform, Quaternion localQuaternionAngles) + { + // Single-valued overloads must not tolerate null values + if (transform == null) throw new NullReferenceException("Transform must not be null"); + return RotatingUsingQuaternionInterpolation(new GameObject[]{ transform.gameObject }, localQuaternionAngles); + } + + public AacFlClip Scaling(Transform transform, Vector3 scale) + { + // Single-valued overloads must not tolerate null values + if (transform == null) throw new NullReferenceException("Transform must not be null"); + return Scaling(new GameObject[]{ transform.gameObject }, scale); + } + + public AacFlClip Positioning(GameObject gameObject, Vector3 localPosition) + { + // Single-valued overloads must not tolerate null values + if (gameObject == null) throw new NullReferenceException("GameObject must not be null"); + return Positioning(new GameObject[]{ gameObject }, localPosition); + } + + public AacFlClip RotatingUsingEulerInterpolation(GameObject gameObject, Vector3 localEulerAngles) + { + // Single-valued overloads must not tolerate null values + if (gameObject == null) throw new NullReferenceException("GameObject must not be null"); + return RotatingUsingEulerInterpolation(new GameObject[]{ gameObject }, localEulerAngles); + } + + public AacFlClip RotatingUsingQuaternionInterpolation(GameObject gameObject, Quaternion localQuaternionAngles) + { + // Single-valued overloads must not tolerate null values + if (gameObject == null) throw new NullReferenceException("GameObject must not be null"); + return RotatingUsingQuaternionInterpolation(new GameObject[]{ gameObject }, localQuaternionAngles); + } + + public AacFlClip Scaling(GameObject gameObject, Vector3 scale) + { + // Single-valued overloads must not tolerate null values + if (gameObject == null) throw new NullReferenceException("GameObject must not be null"); + return Scaling(new GameObject[]{ gameObject }, scale); + } + + public AacFlClip Positioning(Transform[] transformsWithNulls, Vector3 localPosition) + { + return Positioning(AsGameObjectsWithNulls(transformsWithNulls), localPosition); + } + + public AacFlClip RotatingUsingEulerInterpolation(Transform[] transformsWithNulls, Vector3 localEulerAngles) + { + return RotatingUsingEulerInterpolation(AsGameObjectsWithNulls(transformsWithNulls), localEulerAngles); + } + + public AacFlClip RotatingUsingQuaternionInterpolation(Transform[] transformsWithNulls, Quaternion localQuaternionAngles) + { + return RotatingUsingQuaternionInterpolation(AsGameObjectsWithNulls(transformsWithNulls), localQuaternionAngles); + } + + public AacFlClip Scaling(Transform[] transformsWithNulls, Vector3 scale) + { + return Scaling(AsGameObjectsWithNulls(transformsWithNulls), scale); + } + + private static GameObject[] AsGameObjectsWithNulls(Transform[] transformsWithNulls) + { + return transformsWithNulls.Select(o => o != null ? o.gameObject : null).ToArray(); + } - // FIXME API: This is weird, this should be a Transform array, and also this needs a single-object overload. /// Change the position of a GameObject in local space. This lasts one frame. This lasts one frame. The array can safely contain null values. public AacFlClip Positioning(GameObject[] gameObjectsWithNulls, Vector3 localPosition) { @@ -201,6 +281,7 @@ namespace AnimatorAsCode.V1 return this; } + /// Swap a material of a Renderer on the specified slot (indexed at 0). This lasts one frame. public AacFlClip SwappingMaterial(Renderer renderer, int slot, Material material) { var binding = AacInternals.Binding(_component, renderer.GetType(), renderer.transform, $"m_Materials.Array.data[{slot}]"); @@ -212,7 +293,9 @@ namespace AnimatorAsCode.V1 return this; } - + + /// Swap a material of a Particle System on the specified slot (indexed at 0). This lasts one frame.
+ /// In practice, this will animate the ParticleSystemRenderer of that particle system. public AacFlClip SwappingMaterial(ParticleSystem particleSystem, int slot, Material material) { var binding = AacInternals.Binding(_component, typeof(ParticleSystemRenderer), particleSystem.transform, $"m_Materials.Array.data[{slot}]"); @@ -397,7 +480,6 @@ namespace AnimatorAsCode.V1 } } - // FIXME WEB: Missing from web docs /// Define the curve as the parameter. The duration is encoded inside the curve itself. public void WithAnimationCurve(AnimationCurve animationCurve) { @@ -432,9 +514,16 @@ namespace AnimatorAsCode.V1 } } - // FIXME WEB: Missing from web docs - // FIXME NON-DOCUMENTED: Missing docs - public void WithKeyframes(AacFlUnit unit, Action action) // FIXME: Should this be renamed? + /// Obsolete. Use `WithUnit()` instead.
+ /// Start defining the keyframes with a lambda expression, expressing the unit. + [Obsolete("This function was renamed to WithUnit(...)")] + public void WithKeyframes(AacFlUnit unit, Action action) + { + WithUnit(unit, action); + } + + /// Start defining the keyframes with a lambda expression, expressing the unit. + public void WithUnit(AacFlUnit unit, Action action) { var mutatedObjectReferenceKeyframes = new List(); var builder = new AacFlSettingObjectReferenceKeyframes(unit, mutatedObjectReferenceKeyframes); @@ -458,6 +547,7 @@ namespace AnimatorAsCode.V1 _mutatedKeyframes = mutatedKeyframes; } + /// Create a keyframe for an object reference. The unit is defined by the function that invokes this lambda expression. public AacFlSettingObjectReferenceKeyframes Setting(int timeInUnit, Object value) { _mutatedKeyframes.Add(new ObjectReferenceKeyframe { time = AsSeconds(timeInUnit), value = value }); diff --git a/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlStates.cs b/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlStates.cs index 6babe74..831fe21 100644 --- a/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlStates.cs +++ b/Packages/dev.hai-vr.animator-as-code.v1/V1/Editor/AacFlStates.cs @@ -612,9 +612,23 @@ namespace AnimatorAsCode.V1 return this; } - - // FIXME API: Percent is misnomer + /// Set the exit time at a specific normalized amount. + public AacFlTransition AfterAnimationIsAtLeastAtNormalized(float exitTimeNormalized) + { + return AfterAnimationIsAtLeastAtPercent(exitTimeNormalized); + } + + /// Set a non-fixed transition duration in a normalized amount. + public AacFlTransition WithTransitionDurationNormalized(float transitionDurationNormalized) + { + return WithTransitionDurationPercent(transitionDurationNormalized); + } + + /// Set the exit time at a specific normalized amount.
+ ///
+ /// Note: Percent is a misnomer. You are expected to provide a value expressed as a normalized value (where 1 represents the clip duration).
+ /// This function behaves identically to `AfterAnimationIsAtLeastAtNormalized(float)` public AacFlTransition AfterAnimationIsAtLeastAtPercent(float exitTimeNormalized) { _transition.hasExitTime = true; @@ -623,8 +637,10 @@ namespace AnimatorAsCode.V1 return this; } - // FIXME API: Percent is misnomer - /// Set a non-fixed transition duration in a normalized amount. + /// Set a non-fixed transition duration in a normalized amount.
+ ///
+ /// Note: Percent is a misnomer. You are expected to provide a value expressed as a normalized value (where 1 represents the clip duration).
+ /// This function behaves identically to `WithTransitionDurationNormalized(float)` public AacFlTransition WithTransitionDurationPercent(float transitionDurationNormalized) { _transition.hasFixedDuration = false;