GreenSock

TweenFilterLite (AS2 Version) - Easily Tween Filters & Image Effects

Posted in Tweening by jack on the October 18th, 2007


Version 7.21, Updated 7/4/2008


Download Now
 		 
Donate

Join Club GreenSock to get updates and a lot more

RECENT VERSION HIGHLIGHTS

  • IMPORTANT: syntax change! - instead of defining a "type" property that indicates the kind of filter, you define a property like "blurFilter", "glowFilter", "colorMatrixFilter", "dropShadowFilter", or "bevelFilter" and pass an object with whatever properties you want to tween. So

    OLD SYNTAX:
    TweenFilterLite.to(mc, 2, {type:"blur", blurX:20, blurY:20, delay:1});

    NEW SYNTAX:
    TweenFilterLite.to(mc, 2, {blurFilter:{blurX:20, blurY:20}, delay:1});

    Why make this change? Here are a few reasons:

    1. It allows you to tween multiple filters with a single call, like:
      TweenFilterLite.to(mc, 2, {blurFilter:{blurX:30}, colorMatrixFilter:{colorize:0xFF0000}});
    2. It eliminates problems with ambiguous properties like "alpha", mostly in the AS3 version. For example, some people wanted to be able to tween a MovieClip's alpha property AND a DropShadowFilter on that Sprite with the drop shadow's alpha changing too, but with the old syntax, you could only define one alpha
    3. It makes it more flexible to extend (e.g. my upcoming TweenMax class)
  • Removed MovieClip limitation: - Previously, TweenFilterLite only allowed you to tween MovieClips, but you can now use it for any object. It is still recommended that you use TweenLite directly to tween non-MovieClip objects because it'll perform slightly faster, but unless you doing a LOT of tweens simultaneously, you'd probably never notice a difference.

DESCRIPTION

TweenFilterLite extends the extremely lightweight (about 3k), powerful TweenLite "core" class, adding the ability to tween filters (like blurs, glows, drop shadows, bevels, etc.) as well as image effects like contrast, colorization, brightness, saturation, hue, and threshold (combined size: 6k). The syntax is identical to the TweenLite class. If you're unfamiliar with TweenLite, I'd highly recommend that you check it out. It provides easy way to tween multiple object properties over time including a MovieClip's position, alpha, volume, color, etc. Just like the TweenLite class, TweenFilterLite allows you to build in a delay, call any function when the tween starts or has completed (even passing any number of parameters you define), automatically kill other tweens that are affecting the same object (to avoid conflicts), tween arrays, etc. One of the big benefits of this class (and the reason "Lite" is in the name) is that it was carefully built to minimize file size. There are several other Tweening engines out there, but in my experience, they required more than triple the file size which was unacceptable when dealing with strict file size requirements (like banner ads). I haven't been able to find a faster tween engine either. The syntax is simple and the class doesn't rely on complicated prototype alterations that can cause problems with certain compilers. TweenFilterLite is simple, very fast, and more lightweight (about 5k) than any other popular tweening engine.

And if you want even more features and don't mind a few extra Kb, check out the new TweenMax class which adds bezier tweening, pause/resume, easier sequencing, and more. It can do everything TweenFilterLite does, plus more.

Other links: AS3 version | Forums

OBJECTIVES

  • Minimize file size
  • Maximize flexibility and efficiency by extending the TweenLite class. That way, if you don't need to tween filters, you can just use TweenLite (about 3k); otherwise, this class will only add another 3k (6k total)
  • Minimize the amount of code required to initiate a tween
  • Maximize performance
  • Allow for very flexible callbacks (onComplete, onUpdate, onStart, all with the ability to pass any number of parameters)

FITLERS & PROPERTIES:

  • blurFilter -
    blurX, blurY, quality
  • glowFilter -
    alpha, blurX, blurY, color, strength, quality
  • colorMatrixFilter -
    colorize, amount, contrast, brightness, saturation, hue, threshold, relative, matrix
  • dropShadowFilter -
    alpha, angle, blurX, blurY, color, distance, strength, quality
  • bevelFilter -
    angle, blurX, blurY, distance, highlightAlpha, highlightColor, shadowAlpha, shadowColor, strength, quality

USAGE

TweenFilterLite.to(target:Object, duration:Number, variables:Object):TweenFilterLite

  • Description: Tweens the target's properties from whatever they are at the time you call the method to whatever you define in the variables parameter.
  • Parameters:
    1. target : Object - Target object whose properties we're tweening
    2. duration : Number - Duration (in seconds) of the tween
    3. variables : Object - An object containing the end values of all the properties you'd like to have tweened (or if you're using the
      TweenLite.from() method, these variables would define the BEGINNING values). Pass in one object for each filter
      (named appropriately, like blurFilter, glowFilter, colorMatrixFilter, etc.) Filter objects can contain any number of
      properties specific to that filter, like blurX, blurY, contrast, color, distance, colorize, brightness, highlightAlpha, etc.
      Special Properties:

      • delay : Number - Number of seconds to delay before the tween begins. This can be very useful when sequencing tweens.
      • ease : Function - You can specify a function to use for the easing with this variable. For example, mx.transitions.easing.Elastic.easeOut. The Default is Regular.easeOut.
      • easeParams : Array - An array of extra parameter values to feed the easing equation. This can be useful when you use an equation like Elastic and want to control extra parameters like the amplitude and period. Most easing equations, however, don't require extra parameters so you won't need to pass in any easeParams.
      • autoAlpha : Number - Same as changing the "alpha" property but with the additional feature of toggling the "visible" property to false if the alpha ends at 0. It will also toggle visible to true before the tween starts if the value of autoAlpha is greater than zero.
      • _visible : Boolean - To set a MovieClip's "_visible" property at the end of the tween, use this special property.
      • volume : Number - To change a MovieClip's volume, just set this to the value you'd like the MovieClip to end up at (or begin at if you're using TweenFilterLite.from()).
      • tint : Number - To change a MovieClip's color, set this to the hex value of the color you'd like the MovieClip to end up at(or begin at if you're using TweenLite.from()). An example hex value would be 0xFF0000. If you'd like to remove the color from a MovieClip, just pass null as the value of tint. Before version 5.8, tint was called mcColor (which is now deprecated and will likely be removed at a later date although it still works)
      • frame : Number - Use this to tween a MovieClip to a particular frame.
      • onStart : Function - If you'd like to call a function as soon as the tween begins, pass in a reference to it here. This can be useful when there's a delay and you want something to happen just as the tween begins.
      • onStartParams : Array - An array of parameters to pass the onStart function.
      • onStartScope : Object - Use this to define the scope of your onStart function call
      • onUpdate : Function - If you'd like to call a function every time the property values are updated (on every frame during the time the tween is active), pass a reference to it here.
      • onUpdateParams : Array - An array of parameters to pass the onUpdate function (this is optional)
      • onUpdateScope : Object - Use this to define the scope of your onUpdate function call
      • onComplete : Function - If you'd like to call a function when the tween has finished, use this.
      • onCompleteParams : Array - An array of parameters to pass the onComplete function (this is optional)
      • onCompleteScope : Object - Use this to define the scope of your onComplete function call
      • renderOnStart : Boolean - If you're using TweenFilterLite.from() with a delay and want to prevent the tween from rendering until it actually begins, set this to true. By default, it's false which causes TweenFilterLite.from() to render its values immediately, even before the delay has expired.
      • overwrite : Boolean - If you do NOT want the tween to automatically overwrite any other tweens that are affecting the same target, make sure this value is false.
      • blurFilter : Object - To apply a BlurFilter, pass an object with one or more of the following properties:
        • blurX
        • blurY
        • quality
      • glowFilter : Object - To apply a GlowFilter, pass an object with one or more of the following properties:
        • alpha
        • blurX
        • blurY
        • color
        • strength
        • quality
        • inner
        • knockout
      • colorMatrixFilter : Object - To apply a ColorMatrixFilter, pass an object with one or more of the following properties:
        • colorize
        • amount
        • contrast
        • brightness
        • saturation
        • hue
        • threshold
        • relative
        • matrix
      • dropShadowFilter : Object - To apply a ColorMatrixFilter, pass an object with one or more of the following properties:
        • alpha
        • angle
        • blurX
        • blurY
        • color
        • distance
        • strength
        • quality
      • bevelFilter : Object - To apply a BevelFilter, pass an object with one or more of the following properties:
        • angle
        • blurX
        • blurY
        • distance
        • highlightAlpha
        • highlightColor
        • shadowAlpha
        • shadowColor
        • strength
        • quality



TweenFilterLite.from(target:Object, duration:Number, variables:Object):TweenFilterLite

  • Description: Exactly the same as TweenFilterLite.to(), but instead of tweening the properties from where they're at currently to whatever you define, this tweens them the opposite way - from where you define TO where ever they are now (when the method is called). This is handy for when things are set up on the stage the way the should end up and you just want to tween them to where they are.
  • Parameters: Same as TweenFilterLite.to(). (see above)




TweenLite.delayedCall(delay:Number, onComplete:Function, onCompleteParams:Array, scope:Object);

  • Description: Provides an easy way to call any function after a specified number of seconds. Any number of parameters can be passed to that function when it's called too.
  • Parameters:
    1. delay : Number - Number of seconds before the function should be called.
    2. onComplete : Function - The function to call
    3. onCompleteParams : Array - [optional] An array of parameters to pass the onComplete function when it's called.
    4. scope : Object - [optional] Defines the scope of the function.




TweenFilterLite.killTweensOf(target:Object, complete:Boolean);

  • Description: Provides an easy way to kill all tweens of a particular Object/MovieClip. You can optionally force it to immediately complete (which will also call the onComplete function if you defined one)
  • Parameters:
    1. target : Object - Any/All tweens of this Object/MovieClip will be killed.
    2. complete : Function - If true, the tweens for this object will immediately complete (go to the ending values and call the onComplete function if you defined one).




TweenFilterLite.killDelayedCallsTo(function:Function);

  • Description: Provides an easy way to kill all delayed calls to a particular function (ones that were instantiated using the TweenFilterLite.delayedCall() method).
  • Parameters:
    1. function : Function - Any/All delayed calls to this function will be killed.


EXAMPLES

As a simple example, you could tween the blur of clip_mc from where it's at now to 20 over the course of 1.5 seconds by:

  1. import gs.TweenFilterLite;
  2. TweenFilterLite.to(clip_mc, 1.5, {blurFilter:{blurX:20, blurY:20}});


If you want to get more advanced and tween the clip_mc MovieClip over 5 seconds, changing the saturation to 0, delay starting the whole tween by 2 seconds, and then call a function named "onFinishTween" when it has completed and pass in a few arguments to that function (a value of 5 and a reference to the clip_mc), you'd do so like:

  1. import gs.TweenFilterLite;
  2. import mx.transitions.easing.Back;
  3. TweenFilterLite.to(clip_mc, 5, {colorMatrixFilter:{saturation:0}, delay:2, onComplete:onFinishTween, onCompleteParams:[5, clip_mc]});
  4. function onFinishTween(argument1:Number, argument2:MovieClip):Void {
  5.     trace("The tween has finished! argument1 = " + argument1 + ", and argument2 = " + argument2);
  6. }

If you have a MovieClip on the stage that already has the properties you'd like to end at, and you'd like to start with a colorized version (red: 0xFF0000) and tween to the current properties, you could:

  1. import gs.TweenFilterLite;
  2. TweenFilterLite.from(clip_mc, 5, {colorMatrixFilter:{colorize:0xFF0000}});

FAQ

  1. How do I install the class? Do I have to import it on every frame?
    Just make sure the "gs" folder from the download is in the same folder as your FLA file. Keep the class files in the "gs" folder (don't remove them). That's it. And, yes, just like any Class, you need to import TweenFilterLite at the top of any frame that contains code referencing it. This does NOT add extra Kb to your file size very time you import it. Flash is smart enough to embed it once and all the other import statments just act as a "pointer" to the embedded Class.

  2. Why doesn't the tweening engine selectively overwrite ONLY tweens that are affecting the same property? How can I achieve this effect?
    As you can tell from the speed tests, performance is a primary concern. Searching through potentially hundreds or thousands of tweens for overlapping tween properties can get expensive in terms of performance. Therefore, the TweenFilterLite family opted for a much faster approach: all or nothing. But don't worry - in almost every case, you can achieve the result you're after with a little bit of extra code. Trust me, it's worth the increased speed and efficiency you'll get.

    You can selectively kill tweens by keeping track of the TweenFilterLite instance that’s returned by the to() or from() methods, and calling removeTween() on them. For example, if you want to have a button scale up when you roll over it, and scale back down when you roll off (those tweens should overwrite each other) but you don't want them to overwrite a from() call that fades the button in over the course of 2 seconds, you could do:

    1. TweenFilterLite.from(myButton, 2, {_alpha:0, overwrite:false});
    2. var scaleTween:TweenFilterLite;
    3. myButton.onRollOver = function():Void {
    4.     TweenFilterLite.removeTween(scaleTween);
    5.     scaleTween = TweenFilterLite.to(myButton, 0.5, {_xscale:120, _yscale:120, overwrite:false});
    6. }
    7. myButton.onRollOut = function():Void {
    8.     TweenFilterLite.removeTween(scaleTween);
    9.     scaleTween = TweenFilterLite.to(myButton, 0.5, {_xscale:100, _yscale:100, overwrite:false});
    10. }

    Remember, other tweens of the same object will always be overwritten by default. You must set overwrite:false to avoid that behavior. The above example is essentially allowing you to selectively handle overwriting yourself instead of relying on the tweening engine to do the "all or nothing" technique.

  3. Can I set up a sequence of tweens so that they occur one after the other?
    Of course! Just use the delay property and make sure you set the overwrite property to false (otherwise tweens of the same object will always overwrite each other to avoid conflicts). Here's an example where we colorize a MovieClip red over the course of 2 seconds, and then blur it over the course of 1 second:

    1. import gs.TweenFilterLite;
    2. TweenFilterLite.to(clip_mc, 2, {colorMatrixFilter:{colorize:0xFF0000, amount:1}});
    3. TweenFilterLite.to(clip_mc, 1, {blurFilter:{blurX:20, blurY:20}, delay:2, overwrite:false});

  4. Why aren't my filters working?
    If you're using a filter that has an alpha property, try setting it to 1. The default alpha value is zero, so the filter may be working just fine, but you're not seeing it.

  5. Do the properties have to be in a specific order?
    Nope. The only thing that matters is that the first parameter is the object you're tweening, the second parameter is the time (in seconds), and the third parameter contains all the properties you want to tween (in any order). So TweenFilterLite.to(clip_mc, 1, {colorMatrixFilter:{colorize:0xFF0000, amount:1}}) is the same as TweenFilterLite.to(clip_mc, 1, {colorMatrixFilter:{amount:1, colorize:0xFF0000}});

  6. Can I use TweenFilterLite to tween things other than filters?
    Sure. It extends TweenLite, so you can tween any property you want. TweenFilterLite.to(my_mc, 1, {_x:200}) gives you the same result as TweenLite.to(my_mc, 1, {_x:200}). However, I'd recommend using TweenLite to tween properties other than filters for two reasons:
    1. In order to accommodate the specialized nature of filters, TweenFilterLite's code is a bit lengthier which translates into more work for the processor. It's doubtful that anyone would notice a performance hit unless you're tweening hundreds or thousands of instances simultaneously, but I'm a bit of an efficiency freak.
    2. TweenLite can tween any property of ANY object whereas TweenFilterLite tweens properties MovieClips.

  7. Why are TweenLite and TweenFilterLite split into 2 classes instead of building all the functionality into one class?
    1. File size. Only a portion of projects out there require tweening of filters. Almost every project I work on uses TweenLite, but only a few require tweening filters (TweenFilterLite). TweenLite is 3k whereas TweenFilterLite is 6k. Again, one of the stated purposes of TweenLite is to minimize file size & code bloat. If someone only wants to use TweenFilterLite, fine. But I think many people appreciate being able to use the most lightweight option for their needs and shave off the 3k when possible.
    2. Speed. Tweening filters is a more complex task. There are additional if/else statements and calculations in the rendering loop inside TweenFilterLite which could potentially slow things down a bit, even for non-filter tweens (I doubt anyone would notice a difference unless they’re running hundreds or thousands of simultaneous tweens, but I'm a big fan of keeping things as efficient & fast as possible)

  8. Do I have to purchase a license to use this code? Can I use it for commercial purposes?
    TweenFilterLite is free. You're welcome to use it for commercial purposes - I only ask that you donate what you think the class is worth in your project(s), and consider joining Club GreenSock which gives you some bonus classes, updates, and more. If you want to use one (or more) of my classes in your commerical software product which would entail distributing the class files, please get my permission first by e-mailing me at jack -at- greensock.com.

Need Help?

Feel free to e-mail me a question. Or post your question on the new forums. I'd highly recommend joining Club GreenSock to get prioritized access to my time in answering your question, and so that you receive updates and lots more. When you e-mail your question, please include a simplified FLA file (and any class files) that clearly demonstrates the problem and provide a brief explanation.

Author: Jack Doyle, (e-mail: jack -at- greensock.com)
Copyright 2008, GreenSock (This work is subject to the terms here.)

15 Responses to 'TweenFilterLite (AS2 Version) - Easily Tween Filters & Image Effects'

Subscribe to comments with RSS or TrackBack to 'TweenFilterLite (AS2 Version) - Easily Tween Filters & Image Effects'.

  1. Michael Dragich said,

    on May 26th, 2007 at 3:44 am

    Jack,

    I can only say that I wish you designed and developed vehicles, were in charge of the deficit, and ran an organically based fast food restaurant chain. Because if you did, by now, we would all be flying around in our government issued hover cars that ran on raw sewage and emitted nothing but water vapor while consuming conveniently prepared, organic gourmet meals, which contributed to each of us becoming the healthy, happy, active centurions God intended us to be.

    Yes, these classes are that idealistically good. Adobe(Macromedia) should give you millions. I wish that I could, but perhaps a pittance of 10$ will help set a precedence.

    This new class seems every bit as brilliant and compact as TweenLite (which I love). Can’t wait to start playing with it. Thank you, thank you, and thank you.

  2. Michael Dragich said,

    on May 26th, 2007 at 3:47 am

    P.S.
    Make it easy for people to give you money. Put up a direct PayPal link . Genorosity and laziness aren’t mutually exclusive traits :)

  3. Dale Sattler said,

    on June 7th, 2007 at 4:39 pm

    Great class. I was about to write a function to do this and thought I’d give google a try. Excellent!

  4. Eagle said,

    on July 3rd, 2007 at 8:23 am

    Wow!!! You got my fully respect!! D@mn you know something! :D It’s working great!! The only thing I don’t know is how to apply a color and a shadow modify at once. Cool though!

  5. jack said,

    on July 3rd, 2007 at 8:53 am

    Actually, Eagle, it’s pretty simple to apply a colorize filter tween and also a drop shadow tween (or any filter) - just use two tweens and make sure the second one sets the overwrite property to false, like:

    TweenFilterLite.to(my_mc, 2, {colorMatrixFilter:{colorize:0xFF0000}});
    TweenFilterLite.to(my_mc, 2, {dropShadowFilter:{blurX:5, blurY:5, color:0×00FF00}, overwrite:false});

  6. Daniel Course said,

    on August 29th, 2007 at 10:09 am

    Flash Genius again! Lovely thanks,

    Dan C

  7. Corey Calabresse said,

    on September 3rd, 2007 at 1:20 pm

    I’ve been teaching myself as2 & as3, as well as everything else that goes with interactive design… and there’s just some things that take a bit more than understanding the logic to figure out. I’ve been trying to understand the blurs and other filters for DAYS. It’s highly pertinent to a website i’m strying to create. You sir, are a miracle man in my book. Every question I’ve had with this project, you answered in entirety with this one blog alone.

    You’re a life saver… more importantly so, a sanity saver ;)

    Thank you VERY much for taking the time with this,

    C. W. Calabrese

  8. ciumexan said,

    on October 26th, 2007 at 4:44 pm

    you are the man! i’ve been lookin for one of this classes for a long time ;)
    kudos
    keep up the good work dude!

  9. Alex said,

    on January 21st, 2008 at 7:59 am

    I have been using TweenLite for about a month now and all I can say is that your classes are absolutely brilliant! Thanks a lot!

    One thing I’m curious about is how you apply several filters at the same time to an object, lets say you want to move it while adding some glow and removing a drop shadow.

  10. jack said,

    on January 21st, 2008 at 8:41 am

    Alex, you should be able to do that without a problem - just remember that unless you set the “overwrite” property to false, TweenLite (and TweenFilterLite) will always overwrite existing tweens of the same object. So to move a MovieClip while adding a glow and removing a drop shadow, you could do something like:

    TweenFilterLite.to(my_mc, 2, {glowFilter:{color:0xFF0000, strength:2, blurX:10, blurY:10}, _x:100, _y:300});
    TweenFilterLite.to(my_mc, 2, {dropShadowFilter:{alpha:0}, overwrite:false});

  11. Michiel said,

    on January 23rd, 2008 at 10:17 am

    I can think of just two more major functions. One would be the ability to pause (all) tweens. This would be wildly useful in some cases. Right now I’m making a video banner which uses vector animations, but people are going to be pausing and playing the video.

    Another possibility would be the ability to tween through a timeline animation. I once made an animation of a sunrise which used several motion tweens; the entire animation timeline was then tweened from start to end in a certain time, using a standard quadratic equation. It looked great, and works really well if the animation is long enough (to provide enough frames for low-movement parts of the equation).

  12. jack said,

    on January 23rd, 2008 at 10:53 am

    Michiel, I have avoiding adding pause/resume functionality to TweenLite in order to keep file size way down, but TweenMax is now officially released and it includes that feature (and many more). Check it out at http://www.TweenMax.com

    Also, it’s very easy to do the frame tween you’re talking about. As of version 6, frame tweening is built into TweenLite!

  13. sacha jerrems said,

    on February 24th, 2008 at 4:31 am

    dude.
    I’ve been tweening tings for years…I’ve been too complacent with the ol’ lmc_tween.as because you could write two tweens on the one movieclip without the first overwriting the second which I found no other tweener did…I just noticed you’re little snippet of code: overwrite:false in your tweener…You’re a F*&king legend!! I am a better deviner after visiting your website tonight.
    Radical

  14. heaversm said,

    on April 3rd, 2008 at 4:20 pm

    Hey - very cool! One question - is there an easy translation between the numbers you use for the color matrix and the numbers used in flash’s CS3’s built in filter tweener. I have some tweens I want to make to a color, and I have their exact values in flash (example: HUE: -63, SATURATION: 70) - but this doesn’t really translate over to Tweenfilter lite. How best to approximate those values? Nice work!

  15. jack said,

    on April 3rd, 2008 at 7:56 pm

    heaversm, here’s an easy way to match exactly what you created in the Flash CS3 (or Flash 8) authoring environment in terms of the ColorMatrixFilter. All you need to do is get the necessary values in the matrix array and pass it to the new version of TweenFilterLite (7.04). Here’s some code that grabs those values, traces them to your output window (in case you want to copy/paste), clears the filter, and tweens it back into place after a 1 second delay:

    import gs.*;
    import flash.filters.*;

    function getCurrentMatrix($mc:MovieClip):Array {
    var filters:Array = $mc.filters;
    for (var i:Number = 0; i < filters.length; i++) {
    if (filters[i] instanceof ColorMatrixFilter) {
    return filters[i].matrix;
    }
    }
    }

    var curMatrix:Array = getCurrentMatrix(mc);
    trace(”TweenFilterLite.to(mc, 3, {colorMatrixFilter:{matrix:[" + curMatrix + "]}})”);

    mc.filters = []; //clears filters;
    TweenFilterLite.to(mc, 3, {colorMatrixFilter:{matrix:curMatrix}, delay:1});

Leave a Reply