BezierEasing

View source
ceramic.BezierEasing (Class)

High-performance Bezier curve easing for smooth animations.

This class implements cubic and quadratic Bezier easing functions with optimized performance through pre-computed sample tables and intelligent caching. Based on the implementation from https://github.com/gre/bezier-easing, extended to support both cubic and quadratic curves.

Features

  • Cubic Bezier: Standard CSS-style cubic-bezier(x1, y1, x2, y2)
  • Quadratic Bezier: Simplified two-point control
  • Performance Optimized: Pre-computed samples and Newton-Raphson iteration
  • Instance Caching: Automatic reuse of common easing functions
  • Linear Detection: Automatically optimizes linear easings

Usage Examples 

// Create cubic bezier (CSS-style)
var easeInOut = new BezierEasing(0.42, 0, 0.58, 1);
var progress = easeInOut.ease(0.5); // Returns ~0.5

// Create quadratic bezier (single control point)
var easeQuad = new BezierEasing(0.5, 0.8);

// Use cached instances for better performance
var cached = BezierEasing.get(0.25, 0.1, 0.25, 1); // ease-out

// Common easing curves
var easeIn = BezierEasing.get(0.42, 0, 1, 1);
var easeOut = BezierEasing.get(0, 0, 0.58, 1);
var easeInOut = BezierEasing.get(0.42, 0, 0.58, 1);

Performance Notes

  • First call pre-computes 11 sample points
  • Subsequent calls use Newton-Raphson method (4 iterations max)
  • Linear easings bypass all calculations
  • Cache stores up to 10,000 instances
See: ceramic.Easing For pre-defined easing functions, ceramic.Tween For animation implementation

Static Members

clearCache(): Void

Clears all cached BezierEasing instances.

Call this if you need to free memory or have created many temporary easing functions.

get(x1: Float, y1: Float, ?x2: Float, ?y2: Float): BezierEasing

Get or create a BezierEasing instance with the given parameters. Created instances are cached and reused.

Name Type Default
x1 Float
y1 Float
x2 Float (optional)
y2 Float (optional)
Returns
BezierEasing

Instance Members

configure(x1: Float, y1: Float, ?x2: Float, ?y2: Float): Void

Configure the instance with the given arguments. If only x1 and y1 are provided, the curve is treated as quadratic. If all four values x1, y1, x2, y2 are provided, the curve is treated as cubic.

Name Type Default
x1 Float
y1 Float
x2 Float (optional)
y2 Float (optional)
ease(x: Float): Float

Calculates the eased value for the given progress.

Name Type Description
x Float Progress value from 0 to 1
Returns Description
Float Eased value (typically 0 to 1, but can overshoot) * haxe var easing = new BezierEasing(0.42, 0, 0.58, 1); tween.progress = easing.ease(elapsed / duration);
new(x1: Float, y1: Float, ?x2: Float, ?y2: Float): Void

Create a new instance with the given arguments. If only x1 and y1 are provided, the curve is treated as quadratic. If all four values x1, y1, x2, y2 are provided, the curve is treated as cubic.

Name Type Default
x1 Float
y1 Float
x2 Float (optional)
y2 Float (optional)

Private Members

SPLINE_TABLE_SIZE: Int

Number of pre-computed samples for faster lookup

SAMPLE_STEP_SIZE: Float

Distance between each sample point

NEWTON_ITERATIONS: Int

Maximum iterations for Newton-Raphson method

NEWTON_MIN_SLOPE: Float

Minimum slope to use Newton-Raphson (below this, use subdivision)

SUBDIVISION_PRECISION: Float

Precision threshold for binary subdivision

SUBDIVISION_MAX_ITERATIONS: Int

Maximum iterations for binary subdivision

TWO_THIRD: Float

Constant for quadratic to cubic conversion

CACHE_SIZE: Int

Maximum number of cached instances before clearing cache

cachedInstances: IntMap<Array<BezierEasing>>

Map of cached instances by parameter hash

numCachedInstances: Int

Current number of cached instances

linearEasing: Bool

Whether this easing is linear (optimization flag)

sampleValues: Array<Float>

Pre-computed sample values for performance

cached: Bool

Whether this instance is stored in the cache

quadratic: Bool

Whether this is a quadratic (vs cubic) curve

mQuadraticX1: Float

Original quadratic X1 value (before conversion)

mQuadraticX2: Float

Original quadratic X2 value (before conversion)

mX1: Float

First control point X coordinate (0-1)

mY1: Float

First control point Y coordinate

mX2: Float

Second control point X coordinate (0-1)

mY2: Float

Second control point Y coordinate

quadraticToCubicCP1(p: Float): Float

Converts a quadratic control point to the first cubic control point.

Name Type
p Float
Returns
Float
quadraticToCubicCP2(p: Float): Float

Converts a quadratic control point to the second cubic control point.

Name Type
p Float
Returns
Float
cacheKey(x1: Float, y1: Float, x2: Float, y2: Float): Int

Generates a hash key for caching based on control points. Note: This is a simple hash that may have collisions.

Name Type
x1 Float
y1 Float
x2 Float
y2 Float
Returns
Int
getTForX(aX: Float): Float

Finds the t parameter for a given x value using the pre-computed samples. Uses Newton-Raphson iteration when slope is sufficient, otherwise falls back to binary subdivision.

Name Type
aX Float
Returns
Float
calcBezier(aT: Float, aA1: Float, aA2: Float): Float

Calculates the bezier curve value at parameter t.

Name Type Description
aT Float The t parameter (0-1)
aA1 Float First control point coordinate
aA2 Float Second control point coordinate
Returns Description
Float The curve value at t
getSlope(aT: Float, aA1: Float, aA2: Float): Float

Calculates the derivative (slope) of the bezier curve at parameter t.

Name Type Description
aT Float The t parameter (0-1)
aA1 Float First control point coordinate
aA2 Float Second control point coordinate
Returns Description
Float The slope at t
binarySubdivide(aX: Float, aA: Float, aB: Float, mX1: Float, mX2: Float): Float

Uses binary subdivision to find t for a given x when Newton-Raphson is not suitable (low slope).

Name Type
aX Float
aA Float
aB Float
mX1 Float
mX2 Float
Returns
Float
newtonRaphsonIterate(aX: Float, aGuessT: Float, mX1: Float, mX2: Float): Float

Uses Newton-Raphson iteration to quickly converge on the t value for a given x coordinate.

Name Type
aX Float
aGuessT Float
mX1 Float
mX2 Float
Returns
Float
A(aA1: Float, aA2: Float): Float

Bezier coefficient A for cubic formula

Name Type
aA1 Float
aA2 Float
Returns
Float
B(aA1: Float, aA2: Float): Float

Bezier coefficient B for cubic formula

Name Type
aA1 Float
aA2 Float
Returns
Float
C(aA1: Float): Float

Bezier coefficient C for cubic formula

Name Type
aA1 Float
Returns
Float
removeFromCache(x1: Float, y1: Float, x2: Float, y2: Float): Void

Removes this instance from the cache when its parameters change.

Name Type
x1 Float
y1 Float
x2 Float
y2 Float