Package  com.greensock.plugins 
Class  public class BezierPlugin 
Inheritance  BezierPlugin TweenPlugin Object 
type:"quadratic"
):
"thru"
(the default)  the plugin figures out how to draw the Bezier naturally through
the supplied values using a proprietary GreenSock algorithm. The values you provide in the array are essentially
treated as anchors on the Bezier and the plugin calculates the control points. The target's current/starting
values are used as the initial anchor. You can define a curviness
special property that
allows you to adjust the tension on the Bezier where 0 has no curviness (straight lines), 1 is normal
curviness, 2 is twice the normal curviness, etc. Since "thru" is the default Bezier type, you don't
need to define a type
at all if this is the one you want."soft"
 the values that you provide in the array act almost like magnets that attract the
curve towards them, but the Bezier doesn't typically travel through them. They are treated
as control points on a Quadratic Bezier and the plugin creates the necessary intermediate anchors.
The target's current/starting values are used as the initial anchor."quadratic"
 allows you to define standard Quadratic Bezier data (Quadratic Beziers have
1 control point between each anchor). The array should start with the first anchor, then control point,
then anchor, control point, etc. for as many iterations as you want, but obviously make sure that it
starts and ends with anchors."cubic"
 allows you to define standard Cubic Bezier data (Cubic Beziers have
2 control points between each anchor). The array should start with the first anchor, then 2 control points,
then anchor, 2 control points, anchor, etc. for as many iterations as you want, but obviously make sure that it
starts and ends with anchors."thruBasic"
 the same as "thru"
except that it uses a less complex
algorithm for the initial plotting of the Bezier through the supplied values. The "thruBasic"
algorithm is a slightly enhanced version of a somewhat common method that does a decent job
but it is more prone to having kinks or harsh angles when there is a very large segment right
next to a very short one or when two anchors are very close and the one inbetween them is very distant.
The proprietary GreenSock "thru"
algorithm almost always delivers more natural curves
than "thruBasic"
. In terms of calculation expense, "thruBasic" is only about 1520% faster
on the initial setup (when the tween begins), but then every update during the tween the speed is
identical, so overall improvement is negligible (probably less than 1%). The primary reason the
"thruBasic"
option is available is to offer a different style for drawing the Bezier
through the supplied values. If decreasing load on the CPU is your goal, you'd get better
results by decreasing the timeResolution
, particularly to 0.While it is most common to use x
and y
(and sometimes z
) properties for
Bezier tweens, you can use any properties (even ones that are functionbased 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:
Point
instances). Each object in the array should have matching property names
(like "x" and "y"). For example, the array might look like:
[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}]
"thru"
)  Either "thru", "thruBasic", "soft", "quadratic",
or "cubic"
as described above, indicating how the values
should be interpreted.timeResolution
controls. The greater the number,
the more accurate the time remapping but there is a processing price to pay for greater precision.
The default value of 6 is typically fine, but if you notice slight pace changes on the path you can increase
the timeResolution
value. Or, if you want to prioritize speed you could reduce the number.
If you use a timeResolution
value of 0, no length measurements will take place internally which
delivers maximum processing speed, but you may notice changes in speed during the animation.type:"thru"
)  allows you to adjust the
tension on the Bezier where 0 has no curviness (straight lines), 1 is normal curviness, 2 is twice
the normal curviness, etc.autoRotate
feature (previously called
orientToBezier
). If your Bezier is affecting the "x" and "y" properties of your target
and you don't need to offset the rotation by a certain amount more than normal, then you can simply
set autoRotate:true
. Or if you want to offset the rotation by a certain amount (in degrees),
you can define a number like autoRotate:90
(adding 90 degrees in this example). Or for more
advanced controls, you can define autoRotate
as an array. In order to adjust a rotation
property accurately, the plugin needs 5 pieces of information:
"x"
)"y"
)"rotation"
)false
which results in degrees)autoRotate
property should be an Array containing these values, like
["x","y","rotation",90,false]
. And if you need to affect multiple rotational
properties (like in 3D tweens where the Bezier is going through x,y,z points which could affect rotationX, rotationY, and rotationZ),
you can use an array of arrays, like
[["x","y","rotationZ",0,false], ["z","x","rotationY",0,false], ["z","y","rotationX",0,false]]
.type:"thru"
) 
a commadelimited list of property names whose relative distances should be correlated when calculating
the Bezier that travels through the points. Since x, y, and z are all spacial, it is almost always good
to correlate them, but properties like scaleX, scaleY, etc. don't typically need to be correlated.
It is rarely necessary to alter the default correlate
value.//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}); //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(obj, 5, {bezier:{curviness:1.25, values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}, ease:Power1.easeInOut}); //let's define the type as "soft" instead of using the default "thru" TweenMax.to(obj, 5, {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(obj, 5, {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});
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 Flash's curveTo() functionality.
It also has some useful static cubicToQuadratic()
and quadraticToCubic()
conversion methods.
Copyright 20082013, 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.
Method  Defined By  

activate(plugins:Array):Boolean [static]
Activates one or more plugins so that TweenLite and TweenMax recognize the associated special properties.  TweenPlugin  
bezierThrough(values:Array, curviness:Number = 1, quadratic:Boolean = false, basic:Boolean = false, correlate:String = x,y,z, prepend:Object = null):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 
bezierThrough  ()  method 
public static function bezierThrough(values:Array, curviness:Number = 1, quadratic:Boolean = false, basic:Boolean = false, correlate:String = x,y,z, prepend:Object = null):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:
bezierThrough([{x:0, y:0, scaleX:0.5}, {x:100, y:200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]);
would return an object with "x", "y", and "scaleX" properties, each containing an array of objects, one per Bezier segment and you could
access the first Bezier's initial anchor values like:
myReturnedObject.x[0].a, myReturnedObject.y[0].a
, and myReturnedObject.scaleX[0].a
bezierThrough([{x:0, y:0, scaleX:0.5}, {x:100, y:200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]);
would return an object with "x", "y", and "scaleX" properties, each containing an array of objects, one per Bezier segment and you could
access the first Bezier's first control point values like:
myReturnedObject.x[0].b, myReturnedObject.y[0].b
, and myReturnedObject.scaleX[0].b
bezierThrough([{x:0, y:0, scaleX:0.5}, {x:100, y:200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]);
would return an object with "x", "y", and "scaleX" properties, each containing an array of objects, one per Bezier segment and you could
access the first Bezier's second control point values like:
myReturnedObject.x[0].c, myReturnedObject.y[0].c
, and myReturnedObject.scaleX[0].c
bezierThrough([{x:0, y:0, scaleX:0.5}, {x:100, y:200, scaleX:1.2}, {x:300, y:20, scaleX:0.8}]);
would return an object with "x", "y", and "scaleX" properties, each containing an array of objects, one per Bezier segment and you could
access the first Bezier's final anchor values like:
myReturnedObject.x[0].d, myReturnedObject.y[0].d
, and myReturnedObject.scaleX[0].d
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:Object = 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 Flash's drawing API... var beziers:Object = BezierPlugin.bezierThrough([{x:0, y:0}, {x:250, y:400}, {x:500, y:0}], 1, true); var bx:Array = beziers.x; //the "x" Beziers var by:Array = beziers.y; //the "y" Beziers //draw the curve in Flash using AS3: var g:Graphics = this.graphics; g.moveTo(bx[0].a, by[0].a); for (var i:int = 0; i < bx.length; i++) { g.curveTo(bx[i].b, by[i].b, bx[i].c, by[i].c); }
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.
 
basic:Boolean (default = false ) — if true , a faster algorithm will be used for calculating the control points which can be less aesthetically pleasing in situations where there are large differences in the spaces or angles between the values provided (the curves are more likely to get kinks or harsh angles)
 
correlate:String (default = x,y,z ) — [optional] a commadelimited 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)

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

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

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.
