Interpolator (JavaFX 17)

Module javafx.graphics
Package javafx.animation

## Class Interpolator

- java.lang.Object
- - javafx.animation.Interpolator

-     public abstract class Interpolator
      extends Object

  The abstract class defines several `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 `Interpolator` to get custom interpolation behavior.

  A custom `Interpolator` has to be defined in terms of a " `curve()`".

  Since:
    JavaFX 2.0

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Interpolator` | `DISCRETE` | Built-in interpolator that provides discrete time interpolation.
    `static Interpolator` | `EASE_BOTH` | Built-in interpolator instance that provides ease in/out behavior.
    `static Interpolator` | `EASE_IN` | Built-in interpolator instance that provides ease in behavior.
    `static Interpolator` | `EASE_OUT` | Built-in interpolator instance that provides ease out behavior.
    `static Interpolator` | `LINEAR` | Built-in interpolator that provides linear time interpolation.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Interpolator()` | The constructor of `Interpolator`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract double` | `curve​(double t)` | Mapping from [0.0..1.0] to itself.
    `boolean` | `interpolate​(boolean startValue, boolean endValue, double fraction)` | This method takes two `boolean` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.
    `double` | `interpolate​(double startValue, double endValue, double fraction)` | This method takes two `double` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.
    `int` | `interpolate​(int startValue, int endValue, double fraction)` | This method takes two `int` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.
    `long` | `interpolate​(long startValue, long endValue, double fraction)` | This method takes two `int` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.
    `Object` | `interpolate​(Object startValue, Object endValue, double fraction)` | This method takes two `Objects` along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.
    `static Interpolator` | `SPLINE​(double x1, double y1, double x2, double y2)` | Creates an `Interpolator`, which `curve()` is shaped using the spline control points defined by (`x1`, `y1` ) and (`x2`, `y2`).
    `static Interpolator` | `TANGENT​(Duration t, double v)` | Creates a tangent interpolator, for which in-tangent and out-tangent are identical.
    `static Interpolator` | `TANGENT​(Duration t1, double v1, Duration t2, double v2)` | Create a tangent interpolator.

    - ### Methods declared in class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DISCRETE

          public static final Interpolator DISCRETE

      Built-in interpolator that provides discrete time interpolation. The return value of `interpolate()` is `endValue` only when the input `fraction` is 1.0, and `startValue` otherwise.

    - #### LINEAR

          public static final Interpolator LINEAR

      Built-in interpolator that provides linear time interpolation. The return value of `interpolate()` is `startValue` + (`endValue` - `startValue`) * `fraction`.

    - #### EASE_BOTH

          public static final Interpolator EASE_BOTH

      Built-in interpolator instance that provides ease in/out behavior.

      An ease-both interpolator will make an animation start slow, then accelerate and slow down again towards the end, all in a smooth manner.

      The implementation uses the algorithm for easing defined in SMIL 3.0 with an acceleration and deceleration factor of 0.2, respectively.

    - #### EASE_IN

          public static final Interpolator EASE_IN

      Built-in interpolator instance that provides ease in behavior.

      An ease-in interpolator will make an animation start slow and then accelerate smoothly.

      The implementation uses the algorithm for easing defined in SMIL 3.0 with an acceleration factor of 0.2.

    - #### EASE_OUT

          public static final Interpolator EASE_OUT

      Built-in interpolator instance that provides ease out behavior.

      An ease-out interpolator will make an animation slow down toward the end smoothly.

      The implementation uses the algorithm for easing defined in SMIL 3.0 with an deceleration factor of 0.2.

  - ### Constructor Detail

    - #### Interpolator

          protected Interpolator()

      The constructor of `Interpolator`.

  - ### Method Detail

    - #### SPLINE

          public static Interpolator SPLINE​(double x1,
                                            double y1,
                                            double x2,
                                            double y2)

      Creates an `Interpolator`, which `curve()` is shaped using the spline control points defined by (`x1`, `y1` ) and (`x2`, `y2`). The anchor points of the spline are implicitly defined as (`0.0`, `0.0`) and (`1.0`, `1.0`).
      Parameters:
        `x1` - x coordinate of the first control point
        `y1` - y coordinate of the first control point
        `x2` - x coordinate of the second control point
        `y2` - y coordinate of the second control point
      Returns:
        A spline interpolator

    - #### TANGENT

          public static Interpolator TANGENT​(Duration t1,
                                             double v1,
                                             Duration t2,
                                             double v2)

      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 `Timeline`. If used in a `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.

      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.

      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.

      Parameters:
        `t1` - The delta time of the in-tangent, relative to the KeyFrame
        `v1` - The value of the in-tangent
        `t2` - The delta time of the out-tangent, relative to the KeyFrame
        `v2` - The value of the out-tangent
      Returns:
        the new tangent interpolator

    - #### TANGENT

          public static Interpolator TANGENT​(Duration t,
                                             double v)

      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 `Timeline`, because for these key frames only one tangent is used.
      Parameters:
        `t` - The delta time of the tangent
        `v` - The value of the tangent
      Returns:
        the new Tangent interpolator
      See Also:
        `TANGENT(Duration, double, Duration, double)`

    - #### interpolate

          public Object interpolate​(Object startValue,
                                    Object endValue,
                                    double fraction)

      This method takes two `Objects` along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.

      If both `Objects` implement `Number`, their values are interpolated. If `startValue` implements `Interpolatable` the calculation defined in `interpolate()` is used. If neither of these conditions are met, a discrete interpolation is used, i.e. `endValue` is returned if and only if `fraction` is `1.0`, otherwise `startValue` is returned.

      Before calculating the interpolated value, the fraction is altered according to the function defined in `curve()`.

      Parameters:
        `startValue` - start value
        `endValue` - end value
        `fraction` - a value between 0.0 and 1.0
      Returns:
        interpolated value

    - #### interpolate

          public boolean interpolate​(boolean startValue,
                                     boolean endValue,
                                     double fraction)

      This method takes two `boolean` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.

      Before calculating the interpolated value, the fraction is altered according to the function defined in `curve()`.

      Parameters:
        `startValue` - the first data point
        `endValue` - the second data point
        `fraction` - the fraction in `[0.0...1.0]`
      Returns:
        the interpolated value

    - #### interpolate

          public double interpolate​(double startValue,
                                    double endValue,
                                    double fraction)

      This method takes two `double` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.

      Before calculating the interpolated value, the fraction is altered according to the function defined in `curve()`.

      Parameters:
        `startValue` - the first data point
        `endValue` - the second data point
        `fraction` - the fraction in `[0.0...1.0]`
      Returns:
        the interpolated value

    - #### interpolate

          public int interpolate​(int startValue,
                                 int endValue,
                                 double fraction)

      This method takes two `int` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.

      Before calculating the interpolated value, the fraction is altered according to the function defined in `curve()`.

      Parameters:
        `startValue` - the first data point
        `endValue` - the second data point
        `fraction` - the fraction in `[0.0...1.0]`
      Returns:
        the interpolated value

    - #### interpolate

          public long interpolate​(long startValue,
                                  long endValue,
                                  double fraction)

      This method takes two `int` values along with a `fraction` between `0.0` and `1.0` and returns the interpolated value.

      Before calculating the interpolated value, the fraction is altered according to the function defined in `curve()`.

      Parameters:
        `startValue` - the first data point
        `endValue` - the second data point
        `fraction` - the fraction in `[0.0...1.0]`
      Returns:
        the interpolated value

    - #### curve

          protected abstract double curve​(double t)

      Mapping from [0.0..1.0] to itself.
      Parameters:
        `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.
      Returns:
        the curved value