GreenSock JavaScript API Docs | All Packages | All Classes | Index | Frames No Frames |
BezierPlugin

Package | com.greensock.plugins
Class | public class BezierPlugin
Inheritance | BezierPlugin TweenPlugin 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"`):

- `"thru"` (the default) - the plugin figures out how to draw the Bezier naturally through the supplied values using a proprietary 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.

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:

- values : Array [REQUIRED] - the array of your Bezier values as generic objects. 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}]`
- type : String (default:`"thru"`) - Either `"thru", "soft", "quadratic",` or `"cubic"` as described above, indicating how the `values` should be interpreted.
- timeResolution : Number (default:6) - due to the nature of Beziers, plotting the progression of an object on the path over time can make it appear to speed up or slow down based on the placement of the control points and the length of each successive segment on the path, so BezierPlugin implements a technique that reduces or eliminates that variance, but it involves breaking the segments down into a certain number of pieces which is what `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.
- curviness : Number (default:1) (only applies to `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. Use any number, not just integers
- autoRotate : Boolean, Number, or Array (default:false) - to automatically rotate the target according to its position on the Bezier path, you can use the `autoRotate` feature. If your Bezier is affecting the "x" and "y" (or "left" and "top") 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:
  1. Position property 1 (typically `"x"` or `"left"`)
  2. Position property 2 (typically `"y"` or `"top"`)
  3. Rotational property (typically `"rotation"`)
  4. Number of degrees (or radians) to add to the new rotation (optional - makes it easy to orient your target properly)
  5. Boolean value indicating whether or not the rotational property should be defined in radians rather than degrees (default is `false` which results in degrees)
  The `autoRotate` property should be an Array containing these values, like `["x","y","rotation",90*Math.PI/180,true]`. 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]]`. Note: 3D CSS animations aren't supported yet, but you if you're using a canvas-based framework that recognizes 3D properties, it should certainly be compatible with BezierPlugin.
- correlate : String (default:"x,y,z,left,top,right,bottom,marginLeft,marginTop,marginRight,marginBottom,paddingLeft,paddingTop,paddingRight,paddingBottom") (only applies to `type:"thru"`) - a comma-delimited list of property names whose relative distances should be correlated when calculating the Bezier that travels through the points. Since x, y, z, left, top, etc. 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, so there's typically no need to even define one at all (let the plugin use its defaults).

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

| Method | Defined 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:

- a - the starting anchor value of the Cubic Bezier segment. For example, `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`
- b - the first control point value of the Cubic Bezier segment. For example, `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`
- c - the second control point value of the Cubic Bezier segment. For example, `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`
- d - the final anchor value of the Cubic Bezier segment. For example, `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 = 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.

Thu Dec 20 2012, 04:30 PM -06:00