/*
 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javafx.animation;

import javafx.util.Duration;

import com.sun.scenario.animation.NumberTangentInterpolator;
import com.sun.scenario.animation.SplineInterpolator;

/**
 * The abstract class defines several {@code interpolate} methods, which are
 * used to calculate interpolated values. Various built-in implementations of
 * this class are offered. Applications may choose to implement their own
 * {@code Interpolator} to get custom interpolation behavior.
 * <p>
 * A custom {@code Interpolator} has to be defined in terms of a "
 * {@link #curve(double) curve()}".
 * @since JavaFX 2.0
 */
public abstract class Interpolator {

    private static final double EPSILON = 1e-12;

    /**
     * The constructor of {@code Interpolator}.
     */
    protected Interpolator() {
    }

    /**
     * Built-in interpolator that provides discrete time interpolation. The
     * return value of {@code interpolate()} is {@code endValue} only when the
     * input {@code fraction} is 1.0, and {@code startValue} otherwise.
     */
    public static final Interpolator DISCRETE = new Interpolator() {
        @Override
        protected double curve(double t) {
            return (Math.abs(t - 1.0) < EPSILON) ? 1.0 : 0.0;
        }

        @Override
        public String toString() {
            return "Interpolator.DISCRETE";
        }
    };

    /**
     * Built-in interpolator that provides linear time interpolation. The return
     * value of {@code interpolate()} is {@code startValue} + ({@code endValue}
     * - {@code startValue}) * {@code fraction}.
     */
    public static final Interpolator LINEAR = new Interpolator() {
        @Override
        protected double curve(double t) {
            return t;
        }

        @Override
        public String toString() {
            return "Interpolator.LINEAR";
        }
    };

    /*
     * Easing is calculated with the following algorithm (taken from SMIL 3.0
     * specs). The result is clamped because of possible rounding errors.
     *
     * double runRate = 1.0 / (1.0 - acceleration/2.0 - deceleration/2.0); if
     * (fraction < acceleration) { double averageRunRate = runRate * (fraction /
     * acceleration) / 2; fraction *= averageRunRate; } else if (fraction > (1.0
     * - deceleration)) { // time spent in deceleration portion double tdec =
     * fraction - (1.0 - deceleration); // proportion of tdec to total
     * deceleration time double pdec = tdec / deceleration; fraction = runRate *
     * (1.0 - ( acceleration / 2) - deceleration + tdec * (2 - pdec) / 2); }
     * else { fraction = runRate * (fraction - (acceleration / 2)); }
     */

    /**
     * Built-in interpolator instance that provides ease in/out behavior.
     * <p>
     * An ease-both interpolator will make an animation start slow, then
     * accelerate and slow down again towards the end, all in a smooth manner.
     * <p>
     * The implementation uses the algorithm for easing defined in SMIL 3.0
     * with an acceleration and deceleration factor of 0.2, respectively.
     */
    public static final Interpolator EASE_BOTH = new Interpolator() {
        @Override
        protected double curve(double t) {
            // See the SMIL 3.1 specification for details on this calculation
            // acceleration = 0.2, deceleration = 0.2
            return Interpolator.clamp((t < 0.2) ? 3.125 * t * t
                    : (t > 0.8) ? -3.125 * t * t + 6.25 * t - 2.125
                            : 1.25 * t - 0.125);
        }

        @Override
        public String toString() {
            return "Interpolator.EASE_BOTH";
        }
    };
    /**
     * Built-in interpolator instance that provides ease in behavior.
     * <p>
     * An ease-in interpolator will make an animation start slow and then
     * accelerate smoothly.
     * <p>
     * The implementation uses the algorithm for easing defined in SMIL 3.0
     * with an acceleration factor of 0.2.
     */
    public static final Interpolator EASE_IN = new Interpolator() {
        private static final double S1 = 25.0 / 9.0;
        private static final double S3 = 10.0 / 9.0;
        private static final double S4 = 1.0 / 9.0;

        @Override
        protected double curve(double t) {
            // See the SMIL 3.1 specification for details on this calculation
            // acceleration = 0.2, deceleration = 0.0
            return Interpolator.clamp((t < 0.2) ? S1 * t * t : S3 * t - S4);
        }

        @Override
        public String toString() {
            return "Interpolator.EASE_IN";
        }
    };

    /**
     * Built-in interpolator instance that provides ease out behavior.
     * <p>
     * An ease-out interpolator will make an animation slow down toward the
     * end smoothly.
     * <p>
     * The implementation uses the algorithm for easing defined in SMIL 3.0
     * with an deceleration factor of 0.2.
     */
    public static final Interpolator EASE_OUT = new Interpolator() {
        private static final double S1 = -25.0 / 9.0;
        private static final double S2 = 50.0 / 9.0;
        private static final double S3 = -16.0 / 9.0;
        private static final double S4 = 10.0 / 9.0;

        @Override
        protected double curve(double t) {
            // See the SMIL 3.1 specification for details on this calculation
            // acceleration = 0.2, deceleration = 0.0
            return Interpolator.clamp((t > 0.8) ? S1 * t * t + S2 * t + S3 : S4
                    * t);
        }

        @Override
        public String toString() {
            return "Interpolator.EASE_OUT";
        }
    };

    /**
     * Creates an {@code Interpolator}, which {@link #curve(double) curve()} is
     * shaped using the spline control points defined by ({@code x1}, {@code y1}
     * ) and ({@code x2}, {@code y2}). The anchor points of the spline are
     * implicitly defined as ({@code 0.0}, {@code 0.0}) and ({@code 1.0},
     * {@code 1.0}).
     *
     * @param x1
     *            x coordinate of the first control point
     * @param y1
     *            y coordinate of the first control point
     * @param x2
     *            x coordinate of the second control point
     * @param y2
     *            y coordinate of the second control point
     * @return A spline interpolator
     */
    public static Interpolator SPLINE(double x1, double y1, double x2, double y2) {
        return new SplineInterpolator(x1, y1, x2, y2);
    }

    /**
     * Create a tangent interpolator. A tangent interpolator allows to define
     * the behavior of an animation curve very precisely by defining the
     * tangents close to a key frame.
     *
     * A tangent interpolator defines the behavior to the left and to the right
     * of a key frame, therefore it is only useful within a {@link Timeline}.
     * If used in a {@link KeyFrame} after a KeyFrame that has different interpolator,
     * it's treated as if the out-tangent of that KeyFrame was equal to the value in the KeyFrame.
     *
     * <p>
     * <img src="doc-files/tangent_interpolator.png"/>
     *
     * <p>
     * The parameters define the tangent of the animation curve for the in
     * tangent (before a key frame) and out tangent (after a key frame). Each
     * tangent is specified with a pair, the distance to the key frame and the
     * value of the tangent at this moment.
     * <p>
     * The interpolation then follows a bezier curve, with 2 control points defined by the specified tangent and
     * positioned at 1/3 of the duration before the second KeyFrame or after the first KeyFrame. See the picture above.
     *
     * @param t1
     *            The delta time of the in-tangent, relative to the KeyFrame
     * @param v1
     *            The value of the in-tangent
     * @param t2
     *            The delta time of the out-tangent, relative to the KeyFrame
     * @param v2
     *            The value of the out-tangent
     * @return the new tangent interpolator
     */
    public static Interpolator TANGENT(Duration t1, double v1, Duration t2,
            double v2) {
        return new NumberTangentInterpolator(t1, v1, t2, v2);
    }

    /**
     * Creates a tangent interpolator, for which in-tangent and out-tangent are
     * identical. This is especially useful for the first and the last key frame
     * of a {@link Timeline}, because for these key frames only one tangent is
     * used.
     *
     * @see #TANGENT(Duration, double, Duration, double)
     *
     * @param t
     *            The delta time of the tangent
     * @param v
     *            The value of the tangent
     * @return the new Tangent interpolator
     */
    public static Interpolator TANGENT(Duration t, double v) {
        return new NumberTangentInterpolator(t, v);
    }

    /**
     * This method takes two {@code Objects} along with a {@code fraction}
     * between {@code 0.0} and {@code 1.0} and returns the interpolated value.
     * <p>
     * If both {@code Objects} implement {@code Number}, their values are
     * interpolated. If {@code startValue} implements {@link Interpolatable} the
     * calculation defined in {@link Interpolatable#interpolate(Object, double)
     * interpolate()} is used. If neither of these conditions are met, a
     * discrete interpolation is used, i.e. {@code endValue} is returned if and
     * only if {@code fraction} is {@code 1.0}, otherwise {@code startValue} is
     * returned.
     * <p>
     * Before calculating the interpolated value, the fraction is altered
     * according to the function defined in {@link #curve(double) curve()}.
     *
     * @param startValue
     *            start value
     * @param endValue
     *            end value
     * @param fraction
     *            a value between 0.0 and 1.0
     * @return interpolated value
     */
    @SuppressWarnings({ "unchecked", "rawtypes" })
    public Object interpolate(Object startValue, Object endValue,
            double fraction) {
        if ((startValue instanceof Number) && (endValue instanceof Number)) {
            final double start = ((Number) startValue).doubleValue();
            final double end = ((Number) endValue).doubleValue();
            final double val = start + (end - start) * curve(fraction);
            if ((startValue instanceof Double) || (endValue instanceof Double)) {
                return Double.valueOf(val);
            }
            if ((startValue instanceof Float) || (endValue instanceof Float)) {
                return Float.valueOf((float) val);
            }
            if ((startValue instanceof Long) || (endValue instanceof Long)) {
                return Long.valueOf(Math.round(val));
            }
            return Integer.valueOf((int) Math.round(val));
        } else if ((startValue instanceof Interpolatable) && (endValue instanceof Interpolatable)) {
            return ((Interpolatable) startValue).interpolate(endValue,
                    curve(fraction));
        } else {
            // discrete
            return (curve(fraction) == 1.0) ? endValue : startValue;
        }
    }

    /**
     * This method takes two {@code boolean} values along with a
     * {@code fraction} between {@code 0.0} and {@code 1.0} and returns the
     * interpolated value.
     * <p>
     * Before calculating the interpolated value, the fraction is altered
     * according to the function defined in {@link #curve(double) curve()}.
     *
     * @param startValue
     *            the first data point
     * @param endValue
     *            the second data point
     * @param fraction
     *            the fraction in {@code [0.0...1.0]}
     */
    public boolean interpolate(boolean startValue, boolean endValue,
            double fraction) {
        return (Math.abs(curve(fraction) - 1.0) < EPSILON) ? endValue
                : startValue;
    }

    /**
     * This method takes two {@code double} values along with a {@code fraction}
     * between {@code 0.0} and {@code 1.0} and returns the interpolated value.
     * <p>
     * Before calculating the interpolated value, the fraction is altered
     * according to the function defined in {@link #curve(double) curve()}.
     *
     * @param startValue
     *            the first data point
     * @param endValue
     *            the second data point
     * @param fraction
     *            the fraction in {@code [0.0...1.0]}
     */
    public double interpolate(double startValue, double endValue,
            double fraction) {
        return startValue + (endValue - startValue) * curve(fraction);
    }

    /**
     * This method takes two {@code int} values along with a {@code fraction}
     * between {@code 0.0} and {@code 1.0} and returns the interpolated value.
     * <p>
     * Before calculating the interpolated value, the fraction is altered
     * according to the function defined in {@link #curve(double) curve()}.
     *
     * @param startValue
     *            the first data point
     * @param endValue
     *            the second data point
     * @param fraction
     *            the fraction in {@code [0.0...1.0]}
     */
    public int interpolate(int startValue, int endValue, double fraction) {
        return startValue
                + (int) Math.round((endValue - startValue) * curve(fraction));
    }

    /**
     * This method takes two {@code int} values along with a {@code fraction}
     * between {@code 0.0} and {@code 1.0} and returns the interpolated value.
     * <p>
     * Before calculating the interpolated value, the fraction is altered
     * according to the function defined in {@link #curve(double) curve()}.
     *
     * @param startValue
     *            the first data point
     * @param endValue
     *            the second data point
     * @param fraction
     *            the fraction in {@code [0.0...1.0]}
     */
    public long interpolate(long startValue, long endValue,
            double fraction) {
        return startValue
                + Math.round((endValue - startValue) * curve(fraction));
    }

    private static double clamp(double t) {
        return (t < 0.0) ? 0.0 : (t > 1.0) ? 1.0 : t;
    }

    /**
     * Mapping from [0.0..1.0] to itself.
     *
     * @param t
     *            time, but normalized to the range [0.0..1.0], where 0.0 is the
     *            start of the current interval, while 1.0 is the end of the
     *            current interval. Usually a function that increases
     *            monotonically.
     */
    protected abstract double curve(double t);

}
