Interpolator (JavaFX 27)
Description: declaration: module: javafx.graphics, package: javafx.animation, class: Interpolator

# 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 instance that is equivalent to `ofLinear([0, 0], [1, 1])`.
  `static final Interpolator`
  `STEP_END`
  Built-in interpolator instance that is equivalent to `Interpolator.ofSteps(1, StepPosition.END)`.
  `static final Interpolator`
  `STEP_START`
  Built-in interpolator instance that is equivalent to `Interpolator.ofSteps(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`
  `ofLinear(Point2D... controlPoints)`
  Returns an interpolator that interpolates linearly between its specified control points.
  `static Interpolator`
  `ofSpline(double x1, double y1, double x2, double y2)`
  Returns an `Interpolator` whose `curve()` is shaped using the spline control points defined by (`x1`, `y1` ) and (`x2`, `y2`).
  `static Interpolator`
  `ofSteps(int intervalCount, Interpolator.StepPosition position)`
  Returns 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`
  `ofTangent(Duration t, double v)`
  Returns a tangent interpolator, for which in-tangent and out-tangent are identical.
  `static Interpolator`
  `ofTangent(Duration t1, double v1, Duration t2, double v2)`
  Returns a tangent interpolator.
  `static Interpolator`
  `SPLINE(double x1, double y1, double x2, double y2)`
  Deprecated.
  use `ofSpline(double, double, double, double)` instead
  `static Interpolator`
  `STEPS(int intervalCount, Interpolator.StepPosition position)`
  Deprecated.
  use `ofSteps(int, StepPosition)` instead
  `static Interpolator`
  `TANGENT(Duration t, double v)`
  Deprecated.
  use `ofTangent(Duration, double)` instead
  `static Interpolator`
  `TANGENT(Duration t1, double v1, Duration t2, double v2)`
  Deprecated.
  use `ofTangent(Duration, double, Duration, double)` instead

  ### Methods declared in class 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 instance that is equivalent to `ofLinear([0, 0], [1, 1])`.

  - ### 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 `Interpolator.ofSteps(1, StepPosition.START)`.
    Since:
      23

  - ### STEP_END

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

- ## Constructor Details

  - ### Interpolator

    protected Interpolator()
    The constructor of `Interpolator`.

- ## Method Details

  - ### ofLinear

    public static Interpolator ofLinear(Point2D... controlPoints)
    Returns an interpolator that interpolates linearly between its specified control points.

    Each control point associates an input progress value (X) with an output progress value (Y). The input progress value is the normalized progress of the animation, while the output progress value is the normalized progress of the value change. This means that when the time has reached X of the animation, the animation should be at Y of its value change. Both values are specified in normalized coordinates, but are not required to fall within the `[0..1]` interval.

    If the input progress value (X) of a control point is unspecified (`Double.NaN`), it is distributed evenly between its neighboring control points. If the input progress value of the first or last control point is unspecified, it is set to 0 or 1, respectively.

    The control point list is canonicalized so that input progress values (X) are non-decreasing in the order provided. In particular, if a control point specifies an X value that is lower than any preceding control point's X value, it is adjusted to match the greatest preceding X value.

    Parameters:
      `controlPoints` - the control points
    Returns:
      a linear interpolator
    Throws:
      `NullPointerException` - if `controlPoints` is `null`
      `IllegalArgumentException` - if `controlPoints` contains less than two items
    Since:
      26

  - ### SPLINE

    @Deprecated(since="26") public static Interpolator SPLINE(double x1, double y1, double x2, double y2)
    Deprecated.
    use `ofSpline(double, double, double, double)` instead
    This is a legacy method named inconsistently with method naming conventions, use `ofSpline(double, double, double, double)` instead.
    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
    Throws:
      `IllegalArgumentException` - if `x1` or `x2` is outside of `[0, 1]`

  - ### ofSpline

    public static Interpolator ofSpline(double x1, double y1, double x2, double y2)
    Returns an `Interpolator` whose `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
    Throws:
      `IllegalArgumentException` - if `x1` or `x2` is outside of `[0, 1]`
    Since:
      26

  - ### TANGENT

    @Deprecated(since="26") public static Interpolator TANGENT(Duration t1, double v1, Duration t2, double v2)
    Deprecated.
    use `ofTangent(Duration, double, Duration, double)` instead
    This is a legacy method named inconsistently with method naming conventions, use `ofTangent(Duration, double, Duration, double)` instead.
    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:
      a tangent interpolator

  - ### ofTangent

    public static Interpolator ofTangent(Duration t1, double v1, Duration t2, double v2)
    Returns 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:
      a tangent interpolator
    Since:
      26

  - ### TANGENT

    @Deprecated(since="26") public static Interpolator TANGENT(Duration t, double v)
    Deprecated.
    use `ofTangent(Duration, double)` instead
    This is a legacy method named inconsistently with method naming conventions, use `ofTangent(Duration, double)` instead.
    Parameters:
      `t` - the delta time of the tangent
      `v` - the value of the tangent
    Returns:
      a tangent interpolator

  - ### ofTangent

    public static Interpolator ofTangent(Duration t, double v)
    Returns 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:
      a tangent interpolator
    Since:
      26
    See Also:
      - `ofTangent(Duration, double, Duration, double)`

  - ### STEPS

    @Deprecated(since="26") public static Interpolator STEPS(int intervalCount, Interpolator.StepPosition position)
    Deprecated.
    use `ofSteps(int, StepPosition)` instead
    This is a legacy method named inconsistently with method naming conventions, use `ofSteps(int, StepPosition)` instead.
    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

  - ### ofSteps

    public static Interpolator ofSteps(int intervalCount, Interpolator.StepPosition position)
    Returns 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 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:
      26

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