Packagecom.greensock.plugins
Classpublic class BezierPlugin
InheritanceBezierPlugin Inheritance TweenPlugin Inheritance Object

Animate virtually any property (or properties) along a Bezier (curved) path which you define as an array of points/values that can be interpreted 4 different ways (described as the Bezier's "type", like type:"quadratic"):

While it is most common to use x and y (or left and top) properties for Bezier tweens, you can use any properties (even ones that are function-based getters/setters).

Inside the bezier object, you must define at least a values property, and there are several other optional special properties that the BezierPlugin will recognize. Here is a list of them all:

IMPORTANT: if you are trying to do a bezier tween of css-related properties, make sure you utilize the CSSPlugin and put your bezier data inside the css object. BezierPlugin is not just for css-related properties - it can handle virtually any property of any object.

SYNTAX
//tween the "left" and "top" css properties through the supplied values (notice we put bezier inside the css object and we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:[{left:100, top:250}, {left:300, top:0}, {left:500, top:400}]}, ease:Power1.easeInOut});
 
//if we want to customize things, like the curviness and setting autoRotate:true, we need to define the bezier as an object instead, and pass our array as the "values" property
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{curviness:1.25, values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}, backgroundColor:"#f00"}, ease:Power1.easeInOut});

//let's define the type as "soft" instead of using the default "thru"
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{type:"soft", values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}}, ease:Power1.easeInOut});
 
//now we'll do a cubic Bezier and make our target auto rotate but add 45 degrees to the rotation
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{type:"cubic", values:[{x:100, y:250}, {x:150, y:100}, {x:300, y:500}, {x:500, y:400}], autoRotate:["x","y","rotation",45,false]}}, ease:Power1.easeInOut});

//NON-CSS, generic x/y property tween: animate obj through the points in the array (notice we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(obj, 5, {bezier:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], ease:Power1.easeInOut});

You can tap into BezierPlugin's Bezier drawing algorithm by passing its bezierThrough() method your array of points/objects and it will spit back and object with all the necessary data, either in Cubic Bezier form or in Quadratic Bezier form so that you could, for example, draw the path using the canvas's drawing API. It also has some useful static cubicToQuadratic() and quadraticToCubic() conversion methods.

Copyright 2008-2012, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.



Public Methods
 MethodDefined By
  
bezierThrough(values:Array, curviness:Number = 1, quadratic:Boolean = false, correlate:String = x,y,z, prepend:Object = null, calcDifs:Boolean = false):Object
[static] Takes an array that contains objects (could be Points, could be generic objects with any number of properties but they should all match in terms of the names of properties like [{x:0, y:0, scaleX:0.5}, {x:100, y:-200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]) and plots Bezier segments THROUGH those values and returns an array containing a generic object for each Bezier segment.
BezierPlugin
  
cubicToQuadratic(a:Number, b:Number, c:Number, d:Number):Array
[static] Using the fixed midpoint approach, we return an array of 4 quadratic Beziers that closely approximates the cubic Bezier data provided.
BezierPlugin
  
quadraticToCubic(a:Number, b:Number, c:Number):Object
[static] Returns the Cubic equivalent of a Quadratic Bezier.
BezierPlugin
Method Detail
bezierThrough()method
public static function bezierThrough(values:Array, curviness:Number = 1, quadratic:Boolean = false, correlate:String = x,y,z, prepend:Object = null, calcDifs:Boolean = false):Object

Takes an array that contains objects (could be Points, could be generic objects with any number of properties but they should all match in terms of the names of properties like [{x:0, y:0, scaleX:0.5}, {x:100, y:-200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]) and plots Bezier segments THROUGH those values and returns an array containing a generic object for each Bezier segment. By default Cubic Beziers (which use 2 control points per segment) are used but you can optionally request Quadratic Beziers (1 control point per segment) instead using the quadratic parameter.

For Cubic Beziers (the default), each segment object will have a, b, c, and d properties:

If you set the quadratic parameter to true, all of the Bezier segments will contain a, b, and c properties (NOT d) where b is the only control point. This can be very useful because some drawing APIs only understand Quadratic Beziers. There are 4 times as many Quadratic Beziers returned as Cubic Beziers, though, due to the fact that the internal algorithm uses Cubic Beziers to plot the points (they're much more flexible) and then splits each into 4 Quadratic ones.

 //input:
 var beziers = BezierPlugin.bezierThrough([{x:0, y:0}, {x:250, y:400}, {x:500, y:0}]);
 
 //output:
 {
     x:[{a:0, b:0, c:125, d:250}, {a:250, b:375, c:500, d:500}],
     y:[{a:0, b:0, c:400, d:400}, {a:400, b:400, c:0, d:0}]
 }
 //get quadratic beziers so that we can use the canvas's drawing API...
 var beziers = BezierPlugin.bezierThrough([{x:0, y:0}, {x:250, y:400}, {x:500, y:0}], 1, true);
 
 var bx = beziers.x; //the "x" Beziers
 var by = beziers.y; //the "y" Beziers

Parameters

values:Array — An array containing generic objects with matching properties (or Point instances) through which the Beziers should be plotted, like [{x:0, y:0, scaleX:0.5}, {x:100, y:-200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]
 
curviness:Number (default = 1) — A number (default: 1) that controls the strength of the curves that are plotted through the values. A curviness of 0 would be result in straight lines, 1 is normal curviness, and 2 would be extreme curves. Use any value.
 
quadratic:Boolean (default = false) — if true, quadratic Bezier information will be returned instead of cubic Bezier data, thus each object in the returned array will only contain a, b, and c properties where b is the control point.
 
correlate:String (default = x,y,z) — a comma-delimited list of property names whose relative distances should be correlated with each other when calculating the curvature of the Bezier through the values (the default is "x,y,z" because those are almost always properties that should be correlated).
 
prepend:Object (default = null) — [optional] an object to treat as though it is the first element in the values array (typically only used internally for adding a tween's starting values)
 
calcDifs:Boolean (default = false) — if true, da, ca, and ba properties will be added to each bezier segment indicating (d - a), (c - a), and (b - a) which is typically only useful for improving animation performance slightly by precalculating those values instead of doing it each time the tween updates.

Returns
Object — An object with properties matching those from the objects in the values array, with an array assigned to each property populated with an object for each Bezier. The Bezier objects will contain a, b, c (and d if quadratic is not true) properties for the anchors and control points.
cubicToQuadratic()method 
public static function cubicToQuadratic(a:Number, b:Number, c:Number, d:Number):Array

Using the fixed midpoint approach, we return an array of 4 quadratic Beziers that closely approximates the cubic Bezier data provided. Each quadratic Bezier object contains a, b, and c properties where a is the starting anchor value, b is the control point, and c is the ending anchor value.

Parameters

a:Number — starting anchor of the cubic Bezier
 
b:Number — first control point of the cubic Bezier
 
c:Number — second control point of the cubic Bezier
 
d:Number — final anchor of the cubic Bezier

Returns
Array — an array of 4 objects, one for each quadratic Bezier with a, b, and c properties
quadraticToCubic()method 
public static function quadraticToCubic(a:Number, b:Number, c:Number):Object

Returns the Cubic equivalent of a Quadratic Bezier. This method returns an object with a, b, c, and d properties representing the starting anchor value (a), first control point (b), second control point (c), and ending anchor value (d) of a Cubic Bezier matching the Quadratic Bezier data passed in.

Parameters

a:Number — The starting anchor value
 
b:Number — The control point value
 
c:Number — The ending anchor value

Returns
Object — An object with a, b, c, and d properties representing the starting anchor value (a), first control point (b), second control point (c), and ending anchor value (d) of a Cubic Bezier matching the Quadratic Bezier data passed in.