UnityGame/Library/PackageCache/com.unity.render-pipelines.core/Runtime/Volume/KeyframeUtility.cs

using System.Diagnostics.CodeAnalysis;
using Unity.Collections;
using UnityEngine.Assertions;

namespace UnityEngine.Rendering
{
    /// <summary>
    /// A helper function for interpolating AnimationCurves together. In general, curves can not be directly blended
    /// because they will have keypoints at different places. InterpAnimationCurve traverses through the keypoints.
    /// If both curves have a keypoint at the same time, they keypoints are trivially lerped together. However
    /// if one curve has a keypoint at a time that is missing in the other curve (which is the most common case),
    /// InterpAnimationCurve calculates a synthetic keypoint at that time based on value and derivative, and interpolates
    /// the resulting keys.
    /// Note that this function should only be called by internal rendering code. It creates a small pool of animation
    /// curves and reuses them to avoid creating garbage. The number of curves needed is quite small, since curves only need
    /// to be used when interpolating multiple volumes together with different curve parameters. The underlying interp
    /// function isn't allowed to fail, so in the case where we run out of memory we fall back to returning a single keyframe.
    /// </summary>
    ///
    /// <example>
    /// <code>
    /// {
    ///     AnimationCurve curve0 = new AnimationCurve();
    ///     curve0.AddKey(new Keyframe(0.0f, 3.0f));
    ///     curve0.AddKey(new Keyframe(4.0f, 2.0f));
    ///
    ///     AnimationCurve curve1 = new AnimationCurve();
    ///     curve1.AddKey(new Keyframe(0.0f, 0.0f));
    ///     curve1.AddKey(new Keyframe(2.0f, 1.0f));
    ///     curve1.AddKey(new Keyframe(4.0f, 4.0f));
    ///
    ///     float t = 0.5f;
    ///     KeyframeUtility.InterpAnimationCurve(curve0, curve1, t);
    ///
    ///     // curve0 now stores the resulting interpolated curve
    /// }
    /// </code>
    /// </example>
    public class KeyframeUtility
    {
        /// <summary>
        /// Helper function to remove all control points for an animation curve. Since animation curves are reused in a pool,
        /// this function clears existing keys so the curve is ready for reuse.
        /// </summary>
        /// <param name="curve">The curve to reset.</param>
        static public void ResetAnimationCurve(AnimationCurve curve)
        {
            curve.ClearKeys();
        }

        static private Keyframe LerpSingleKeyframe(Keyframe lhs, Keyframe rhs, float t)
        {
            var ret = new Keyframe();

            ret.time = Mathf.Lerp(lhs.time, rhs.time, t);
            ret.value = Mathf.Lerp(lhs.value, rhs.value, t);
            ret.inTangent = Mathf.Lerp(lhs.inTangent, rhs.inTangent, t);
            ret.outTangent = Mathf.Lerp(lhs.outTangent, rhs.outTangent, t);
            ret.inWeight = Mathf.Lerp(lhs.inWeight, rhs.inWeight, t);
            ret.outWeight = Mathf.Lerp(lhs.outWeight, rhs.outWeight, t);

            // it's not possible to lerp the weightedMode, so use the lhs mode.
            ret.weightedMode = lhs.weightedMode;

            // Note: ret.tangentMode is deprecated, so we will use  the value from the constructor
            return ret;
        }

        /// In an animation curve, the inTangent and outTangent don't match the edge of the curve. For example,
        /// the first key might have inTangent=3.0f but the actual incoming tangent is 0.0 because the curve is
        /// clamped outside the time domain. So this helper fetches a key, but zeroes out the inTangent of the first
        /// key and the outTangent of the last key.
        static private Keyframe GetKeyframeAndClampEdge([DisallowNull] NativeArray<Keyframe> keys, int index)
        {
            var lastKeyIndex = keys.Length - 1;
            if (index < 0 || index > lastKeyIndex)
            {
                Debug.LogWarning("Invalid index in GetKeyframeAndClampEdge. This is likely a bug.");
                return new Keyframe();
            }

            var currKey = keys[index];
            if (index == 0)
            {
                currKey.inTangent = 0.0f;
            }
            if (index == lastKeyIndex)
            {
                currKey.outTangent = 0.0f;
            }
            return currKey;
        }

        /// Fetch a key from the keys list. If index<0, then expand the first key backwards to startTime. If index>=keys.length,
        /// then extend the last key to endTime. Keys must be a valid array with at least one element.
        static private Keyframe FetchKeyFromIndexClampEdge([DisallowNull] NativeArray<Keyframe> keys, int index, float segmentStartTime, float segmentEndTime)
        {
            float startTime = Mathf.Min(segmentStartTime, keys[0].time);
            float endTime = Mathf.Max(segmentEndTime, keys[keys.Length - 1].time);

            float startValue = keys[0].value;
            float endValue = keys[keys.Length - 1].value;

            // In practice, we are lerping animcurves for post processing curves that are always clamping at the begining and the end,
            // so we are not implementing the other wrap modes like Loop, PingPong, etc.
            Keyframe ret;
            if (index < 0)
            {
                // when you are at a time either before the curve start time the value is clamped to the start time and the input tangent is ignored.
                ret = new Keyframe(startTime, startValue, 0.0f, 0.0f);
            }
            else if (index >= keys.Length)
            {
                // if we are after the end of the curve, there slope is always zero just like before the start of a curve
                var lastKey = keys[keys.Length - 1];
                ret = new Keyframe(endTime, endValue, 0.0f, 0.0f);
            }
            else
            {
                // only remaining case is that we have a proper index
                ret = GetKeyframeAndClampEdge(keys, index);
            }
            return ret;
        }


        /// Given a desiredTime, interpoloate between two keys to find the value and derivative. This function assumes that lhsKey.time <= desiredTime <= rhsKey.time,
        /// but will return a reasonable float value if that's not the case.
        static private void EvalCurveSegmentAndDeriv(out float dstValue, out float dstDeriv, Keyframe lhsKey, Keyframe rhsKey, float desiredTime)
        {
            // This is the same epsilon used internally
            const float epsilon = 0.0001f;

            float currTime = Mathf.Clamp(desiredTime, lhsKey.time, rhsKey.time);

            // (lhsKey.time <= rhsKey.time) should always be true. But theoretically, if garbage values get passed in, the value would
            // be clamped here to epsilon, and we would still end up with a reasonable value for dx.
            float dx = Mathf.Max(rhsKey.time - lhsKey.time, epsilon);
            float dy = rhsKey.value - lhsKey.value;
            float length = 1.0f / dx;
            float lengthSqr = length * length;

            float m1 = lhsKey.outTangent;
            float m2 = rhsKey.inTangent;
            float d1 = m1 * dx;
            float d2 = m2 * dx;

            // Note: The coeffecients are calculated to match what the editor does internally. These coeffeceients expect a
            // t in the range of [0,dx]. We could change the function to accept a range between [0,1], but then this logic would
            // be different from internal editor logic which could cause subtle bugs later.

            float c0 = (d1 + d2 - dy - dy) * lengthSqr * length;
            float c1 = (dy + dy + dy - d1 - d1 - d2) * lengthSqr;
            float c2 = m1;
            float c3 = lhsKey.value;

            float t = Mathf.Clamp(currTime - lhsKey.time, 0.0f, dx);

            dstValue = (t * (t * (t * c0 + c1) + c2)) + c3;
            dstDeriv = (t * (3.0f * t * c0 + 2.0f * c1)) + c2;
        }

        /// lhsIndex and rhsIndex are the indices in the keys array. The lhsIndex/rhsIndex may be -1, in which it creates a synthetic first key
        /// at startTime, or beyond the length of the array, in which case it creates a synthetic key at endTime.
        static private Keyframe EvalKeyAtTime([DisallowNull] NativeArray<Keyframe> keys, int lhsIndex, int rhsIndex, float startTime, float endTime, float currTime)
        {
            var lhsKey = KeyframeUtility.FetchKeyFromIndexClampEdge(keys, lhsIndex, startTime, endTime);
            var rhsKey = KeyframeUtility.FetchKeyFromIndexClampEdge(keys, rhsIndex, startTime, endTime);

            float currValue;
            float currDeriv;
            KeyframeUtility.EvalCurveSegmentAndDeriv(out currValue, out currDeriv, lhsKey, rhsKey, currTime);

            return new Keyframe(currTime, currValue, currDeriv, currDeriv);
        }


        /// <summary>
        /// Interpolates two AnimationCurves. Since both curves likely have control points at different places
        /// in the curve, this method will create a new curve from the union of times between both curves. However, to avoid creating
        /// garbage, this function will always replace the keys of lhsAndResultCurve with the final result, and return lhsAndResultCurve.
        /// </summary>
        /// <param name="lhsAndResultCurve">The start value. Additionaly, this instance will be reused and returned as the result.</param>
        /// <param name="rhsCurve">The end value.</param>
        /// <param name="t">The interpolation factor in range [0,1].</param>
        static public void InterpAnimationCurve(ref AnimationCurve lhsAndResultCurve, [DisallowNull] AnimationCurve rhsCurve, float t)
        {
            if (t <= 0.0f || rhsCurve.length == 0)
            {
                // no op. lhsAndResultCurve is already the result
            }
            else if (t >= 1.0f || lhsAndResultCurve.length == 0)
            {
                // In this case the obvious solution would be to return the rhsCurve. BUT (!) the lhsCurve and rhsCurve are different. This function is
                // called by:
                //      stateParam.Interp(stateParam, toParam, interpFactor);
                //
                // stateParam (lhsCurve) is a temporary in/out parameter, but toParam (rhsCurve) might point to the original component, so it's unsafe to
                // change that data. Thus, we need to copy the keys from the rhsCurve to the lhsCurve instead of returning rhsCurve.
                lhsAndResultCurve.CopyFrom(rhsCurve);
            }
            else
            {
                // Note: If we reached this code, we are guaranteed that both lhsCurve and rhsCurve are valid with at least 1 key

                // create a native array for the temp keys to avoid GC
                var lhsCurveKeys = new NativeArray<Keyframe>(lhsAndResultCurve.length, Allocator.Temp);
                var rhsCurveKeys = new NativeArray<Keyframe>(rhsCurve.length, Allocator.Temp);

                for (int i = 0; i < lhsAndResultCurve.length; i++)
                {
                    lhsCurveKeys[i] = lhsAndResultCurve[i];
                }

                for (int i = 0; i < rhsCurve.length; i++)
                {
                    rhsCurveKeys[i] = rhsCurve[i];
                }

                float startTime = Mathf.Min(lhsCurveKeys[0].time, rhsCurveKeys[0].time);
                float endTime = Mathf.Max(lhsCurveKeys[lhsAndResultCurve.length - 1].time, rhsCurveKeys[rhsCurve.length - 1].time);

                // we don't know how many keys the resulting curve will have (because we will compact keys that are at the exact
                // same time), but in most cases we will need the worst case number of keys. So allocate the worst case.
                int maxNumKeys = lhsAndResultCurve.length + rhsCurve.length;
                int currNumKeys = 0;
                var dstKeys = new NativeArray<Keyframe>(maxNumKeys, Allocator.Temp);

                int lhsKeyCurr = 0;
                int rhsKeyCurr = 0;

                while (lhsKeyCurr < lhsCurveKeys.Length || rhsKeyCurr < rhsCurveKeys.Length)
                {
                    // the index is considered invalid once it goes off the end of the array
                    bool lhsValid = lhsKeyCurr < lhsCurveKeys.Length;
                    bool rhsValid = rhsKeyCurr < rhsCurveKeys.Length;

                    // it's actually impossible for lhsKey/rhsKey to be uninitialized, but have to
                    // add initialize here to prevent compiler erros
                    var lhsKey = new Keyframe();
                    var rhsKey = new Keyframe();
                    if (lhsValid && rhsValid)
                    {
                        lhsKey = GetKeyframeAndClampEdge(lhsCurveKeys, lhsKeyCurr);
                        rhsKey = GetKeyframeAndClampEdge(rhsCurveKeys, rhsKeyCurr);

                        if (lhsKey.time == rhsKey.time)
                        {
                            lhsKeyCurr++;
                            rhsKeyCurr++;
                        }
                        else if (lhsKey.time < rhsKey.time)
                        {
                            // in this case:
                            //     rhsKey[curr-1].time <= lhsKey.time <= rhsKey[curr].time
                            // so interpolate rhsKey at the lhsKey.time.
                            rhsKey = KeyframeUtility.EvalKeyAtTime(rhsCurveKeys, rhsKeyCurr - 1, rhsKeyCurr, startTime, endTime, lhsKey.time);
                            lhsKeyCurr++;
                        }
                        else
                        {
                            // only case left is (lhsKey.time > rhsKey.time)
                            Assert.IsTrue(lhsKey.time > rhsKey.time);

                            // this is the reverse of the lhs key case
                            //     lhsKey[curr-1].time <= rhsKey.time <= lhsKey[curr].time
                            // so interpolate lhsKey at the rhsKey.time.
                            lhsKey = KeyframeUtility.EvalKeyAtTime(lhsCurveKeys, lhsKeyCurr - 1, lhsKeyCurr, startTime, endTime, rhsKey.time);
                            rhsKeyCurr++;
                        }
                    }
                    else if (lhsValid)
                    {
                        // we are still processing lhsKeys, but we are out of rhsKeys, so increment lhs and evaluate rhs
                        lhsKey = GetKeyframeAndClampEdge(lhsCurveKeys, lhsKeyCurr);

                        // rhs will be evaluated between the last rhs key and the extrapolated rhs key at the end time
                        rhsKey = KeyframeUtility.EvalKeyAtTime(rhsCurveKeys, rhsKeyCurr - 1, rhsKeyCurr, startTime, endTime, lhsKey.time);

                        lhsKeyCurr++;
                    }
                    else
                    {
                        // either lhsValid is True, rhsValid is True, or they are both True. So to miss the first two cases,
                        // right here rhsValid must be true.
                        Assert.IsTrue(rhsValid);

                        // we still have rhsKeys to lerp, but we are out of lhsKeys, to increment rhs and evaluate lhs
                        rhsKey = GetKeyframeAndClampEdge(rhsCurveKeys, rhsKeyCurr);

                        // lhs will be evaluated between the last lhs key and the extrapolated lhs key at the end time
                        lhsKey = KeyframeUtility.EvalKeyAtTime(lhsCurveKeys, lhsKeyCurr - 1, lhsKeyCurr, startTime, endTime, rhsKey.time);

                        rhsKeyCurr++;
                    }

                    var dstKey = KeyframeUtility.LerpSingleKeyframe(lhsKey, rhsKey, t);
                    dstKeys[currNumKeys] = dstKey;
                    currNumKeys++;
                }

                // Replace the keys in lhsAndResultCurve with our interpolated curve.
                KeyframeUtility.ResetAnimationCurve(lhsAndResultCurve);
                for (int i = 0; i < currNumKeys; i++)
                {
                    lhsAndResultCurve.AddKey(dstKeys[i]);
                }

                dstKeys.Dispose();
            }
        }
    }
}