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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `Interpolator.StepPosition`
  Specifies the step position of a step interpolator.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Interpolator`
  `DISCRETE`
  Built-in interpolator that provides discrete time interpolation.
  `static final Interpolator`
  `EASE_BOTH`
  Built-in interpolator instance that provides ease in/out behavior.
  `static final Interpolator`
  `EASE_IN`
  Built-in interpolator instance that provides ease in behavior.
  `static final Interpolator`
  `EASE_OUT`
  Built-in interpolator instance that provides ease out behavior.
  `static final Interpolator`
  `LINEAR`
  Built-in interpolator that provides linear time interpolation.
  `static final Interpolator`
  `STEP_END`
  Built-in interpolator instance that is equivalent to `STEPS(1, StepPosition.END)`.
  `static final Interpolator`
  `STEP_START`
  Built-in interpolator instance that is equivalent to `STEPS(1, StepPosition.START)`.

- ## Constructor Summary

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

- ## Method Summary

  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`
  `STEPS(int intervalCount, Interpolator.StepPosition position)`
  Creates a step interpolator that divides the input time into a series of intervals, each interval being equal in length, where each interval maps to a constant output time value.
  `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 Details

  - ### 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.

  - ### STEP_START

    public static final Interpolator STEP_START
    Built-in interpolator instance that is equivalent to `STEPS(1, StepPosition.START)`.
    Since:
      23

  - ### STEP_END

    public static final Interpolator STEP_END
    Built-in interpolator instance that is equivalent to `STEPS(1, StepPosition.END)`.
    Since:
      23

- ## Constructor Details

  - ### Interpolator

    protected Interpolator()
    The constructor of `Interpolator`.

- ## Method Details

  - ### 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)`

  - ### STEPS

    public static Interpolator STEPS(int intervalCount, Interpolator.StepPosition position)
    Creates a step interpolator that divides the input time into a series of intervals, each interval being equal in length, where each interval maps to a constant output time value. The output time value is determined by the `Interpolator.StepPosition`.
    Parameters:
      `intervalCount` - the number of intervals in the step interpolator
      `position` - the `StepPosition` of the step interpolator
    Returns:
      a new step interpolator
    Throws:
      `IllegalArgumentException` - if `intervals` is less than 1, or if `intervals` is less than 2 when `position` is `Interpolator.StepPosition.NONE`
      `NullPointerException` - if `position` is `null`
    Since:
      23

  - ### 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