Tweener AS3 extension for color properties “_brightness”, “_contrast” and “_saturation”
August 28th, 2007
IMPORTANT NOTE [10/07/07]: Tweeners SpecialPropertiesDefault.as has been deprecated since Tweener version 1.27.62. All listed color properties (_brightness, _contrast, _saturation) are now included in Tweener version 1.30.66 and higher. For more information check Tweeners changelog on Google Code. Kudos to Zeh Fernando for the latest releases.
There are a lot of AS3 Animation packages out there, all with pros and cons. One of my favorite tools is Tweener AS3, but at its current version (v.1.0.1) it supports only few color properties such as _color, _color_ra, _color_rb and so on. However, you have the option to create your own special properties using Tweener.registerSpecialProperty. So I decided to write an extension for missing color properties _brightness, _contrast and _saturation based on the awesome ColorMatrix by Mario Klingemann. Check it out!
Example
Instruction
- Download the latest AS3 version of Tweener on Google Code.
-
Copy the following
ColorMatrix.asto {yourTweenerFolder}/caurina/transitions.ColorMatrix.as ( Download code )
-
/**
-
* ColorMatrix class, which provides special color properties
-
* called "_contrast", "_brightness", "_saturation"
-
* using Tweener AS3 (http://code.google.com/p/tweener/).
-
*
-
* Based on Mario Klingemanns awesome AS2 ColorMatrix v1.2
-
* (http://www.quasimondo.com/archives/000565.php)
-
*
-
* @author Jens Krause [www.websector.de]
-
* @date 08/28/07
-
* @see http://www.websector.de/blog/2007/08/28/tweener-as3-extension-for-color-properties-_brightness-_contrast-and-_saturation/
-
*
-
*/
-
-
package caurina.transitions
-
{
-
import flash.filters.ColorMatrixFilter;
-
-
public class ColorMatrix
-
{
-
//
-
// Luminance conversion constants
-
private static const R_LUM:Number = 0.212671;
-
private static const G_LUM:Number = 0.715160;
-
private static const B_LUM: Number = 0.072169;
-
//
-
// min / max values for special tween properties called "_contrast"
-
private static const MIN_CONTRAST: Number = -200;
-
private static const MAX_CONTRAST: Number = 500;
-
private static const STANDARD_CONTRAST: Number = 0;
-
//
-
// min / max values for special tween properties called "_brightness"
-
private static const MIN_BRIGHTNESS: Number = -100;
-
private static const MAX_BRIGHTNESS: Number = 100;
-
private static const STANDARD_BRIGHTNESS: Number = 0;
-
//
-
// min / max values for special tween properties called "_saturation"
-
private static const MIN_SATURATION: Number = -300;
-
private static const MAX_SATURATION: Number = 300;
-
private static const STANDARD_SATURATION: Number = 100;
-
//
-
// standard matrix
-
private static const IDENTITY:Array = [ 1,0,0,0,0,
-
0,1,0,0,0,
-
0,0,1,0,0,
-
0,0,0,1,0 ];
-
//
-
// matrix
-
public var matrix:Array;
-
-
/**
-
* Constructor of ColorMatrix
-
*
-
* @param mat Object A ColorMatrix instance or an array
-
*
-
*/
-
function ColorMatrix (mat:Object = null)
-
{
-
if (mat is ColorMatrix)
-
{
-
matrix = mat.matrix.concat();
-
}
-
else if (mat is Array)
-
{
-
matrix = mat.concat();
-
}
-
else
-
{
-
reset();
-
}
-
}
-
-
/**
-
* Resets the matrix to its IDENTITY
-
*
-
*/
-
public function reset():void
-
{
-
matrix = IDENTITY.concat();
-
}
-
-
/**
-
* Clones the instance of ColorMatrix
-
*
-
*/
-
public function clone():ColorMatrix
-
{
-
return new ColorMatrix( matrix );
-
}
-
-
///////////////////////////////////////////////////////////
-
// brightness
-
///////////////////////////////////////////////////////////
-
-
/**
-
* Calculate an average of particular indexes of its matrix
-
*
-
* @return Number Value of a brightness value for using Tweener
-
*
-
*/
-
public function getBrightness (): Number
-
{
-
// average of "brightness"-indexes within matrix
-
var value: Number = (matrix[4] + matrix[9] + matrix[14]) / 3;
-
// convert back to a "valid" tween property between min and max values
-
if (value != 0) value = value * 100 / 255;
-
return Math.round(value);
-
}
-
-
/**
-
* Changes matrix to alter brightness
-
*
-
* @param Number Value of Tweeners brightness property
-
*
-
*/
-
public function setBrightness (value: Number):void
-
{
-
var brightness: Number = checkValue(MIN_BRIGHTNESS, MAX_BRIGHTNESS, value);
-
// converts tween property to a valid value for the matrix
-
brightness = 255 * brightness / 100;
-
-
var mat:Array = [ 1,0,0,0, brightness,
-
0,1,0,0, brightness,
-
0,0,1,0, brightness,
-
0,0,0,1, 0 ];
-
-
concat(mat);
-
}
-
-
///////////////////////////////////////////////////////////
-
// contrast
-
///////////////////////////////////////////////////////////
-
/**
-
* Calculate an average of particular indexes of its matrix
-
*
-
* @return Number Value of a contrast value for using Tweener
-
*
-
*/
-
public function getContrast (): Number
-
{
-
// average of "contrast"-indexes within matrix
-
var value: Number = (matrix[0] + matrix[6] + matrix[12]) / 3;
-
// converts back to a "valid" tween property between min and max values
-
value = (value – 1) * 100;
-
return value;
-
}
-
-
/**
-
* Changes matrix to alter contrast
-
*
-
* @param Number Value of Tweeners brightness property
-
*
-
*/
-
public function setContrast (value: Number):void
-
{
-
var contrast: Number = checkValue(MIN_CONTRAST, MAX_CONTRAST, value);
-
// convert tween property to a valid value for the matrix
-
contrast /= 100;
-
var scale: Number = contrast + 1;
-
var offset : Number = 128 * (1 – scale);
-
-
var mat: Array = [ scale, 0, 0, 0, offset,
-
0, scale, 0, 0, offset,
-
0, 0, scale, 0, offset,
-
0, 0, 0, 1, 0 ];
-
-
concat(mat);
-
}
-
-
///////////////////////////////////////////////////////////
-
// saturation
-
///////////////////////////////////////////////////////////
-
/**
-
* Calculate an average of particular indexes of its matrix
-
*
-
* @return Number Value of a saturation value for using Tweener
-
*
-
*/
-
public function getSaturation (): Number
-
{
-
//
-
// uses 3 "saturation"-indexes within matrix – once per color channel – ignore the others…
-
var s1: Number = 1 – matrix[1] / G_LUM;
-
var s2: Number = 1 – matrix[2] / B_LUM;
-
var s5: Number = 1 – matrix[5] / R_LUM;
-
// average of these "saturation"-indexes
-
var value: Number;
-
value = Math.round((s1 + s2 + s5) / 3);
-
value *= 100;
-
-
return value;
-
}
-
-
/**
-
* Changes matrix to alter contrast
-
*
-
* @param Number Value of Tweeners saturation property
-
*
-
*/
-
public function setSaturation (value: Number): void
-
{
-
var saturation: Number = checkValue(MIN_SATURATION, MAX_SATURATION, value);
-
-
saturation /= 100;
-
-
var isValue: Number = 1-saturation;
-
-
var irlum: Number = isValue * R_LUM;
-
var iglum: Number = isValue * G_LUM;
-
var iblum: Number = isValue * B_LUM;
-
-
var mat:Array = [ irlum + saturation, iglum, iblum, 0, 0,
-
irlum, iglum + saturation, iblum, 0, 0,
-
irlum, iglum, iblum + saturation, 0, 0,
-
0, 0, 0, 1, 0 ];
-
-
concat(mat);
-
}
-
-
-
/**
-
* Concatenates the elements of a matrix specified in the parameter with the elements in an array and creates a new matrix
-
*
-
* @param Array Altered Matrix
-
*
-
*/
-
public function concat(mat:Array):void
-
{
-
var temp:Array = new Array ();
-
var i:Number = 0;
-
-
for (var y:Number = 0; y < 4; y++ )
-
{
-
-
for (var x:Number = 0; x < 5; x++ )
-
{
-
temp[i + x] = mat[i] * matrix[x] +
-
mat[i+1] * matrix[x + 5] +
-
mat[i+2] * matrix[x + 10] +
-
mat[i+3] * matrix[x + 15] +
-
(x == 4 ? mat[i+4] : 0);
-
}
-
i+=5;
-
}
-
-
matrix = temp;
-
}
-
-
/**
-
* Instanciates a ColorMatrixFilter using ColorMatrix matrix
-
*
-
* @return ColorMatrixFilter ColorMatrixFilter using the matrix of a ColorMatrix instance
-
*
-
*/
-
public function get filter():ColorMatrixFilter
-
{
-
return new ColorMatrixFilter(matrix);
-
}
-
-
/**
-
* Helper method to check a value for min. and max. values within a specified range
-
*
-
* @param Number min. value of its range
-
* @param Number max. value of its range
-
* @param Number checked value
-
*/
-
private function checkValue(minValue: Number, maxValue: Number, value: Number):Number
-
{
-
return Math.min(maxValue, Math.max(minValue, value));
-
}
-
}
-
}
-
-
Open
SpecialPropertiesDefault.aslocated in {yourTweenerFolder}/caurina/transitions. Copy and paste the following lines to the method calledinit().snippet1.txt ( Download code )
-
// color brightness
-
Tweener.registerSpecialProperty("_brightness", __brightness_get, __brightness_set);
-
// color contrast
-
Tweener.registerSpecialProperty("_contrast", __contrast_get, __contrast_set);
-
// color saturation
-
Tweener.registerSpecialProperty("_saturation", __saturation_get, __saturation_set);
-
-
-
Add the following methods to
SpecialPropertiesDefault.asafter the methodinit()mentioned above. Don’t forget to importflash.display.DisplayObjectandflash.filters.ColorMatrixFilteras well. -
// ———————————————————————————————————————————-
-
// _brightness_*
-
-
/**
-
* Gets brightness using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @return Number Value of the brightness property
-
*/
-
public static function __brightness_get (p_obj: DisplayObject):Number
-
{
-
return getColorMatrix(p_obj).getBrightness();
-
};
-
-
/**
-
* Changes brightness of a DisplayObject using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @param p_value Number Value of the brightness property (min: -100 / max: 100 / standard: 0)
-
*/
-
public static function __brightness_set (p_obj:DisplayObject, p_value:Number):void
-
{
-
var colorMatrix: ColorMatrix = new ColorMatrix();
-
colorMatrix.setBrightness(p_value);
-
setColorMatrix(p_obj, colorMatrix);
-
};
-
-
// ———————————————————————————————————————————-
-
// _contrast_*
-
/**
-
* Gets contrast using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @return Number Value of the contrast property
-
*/
-
public static function __contrast_get (p_obj: DisplayObject):Number
-
{
-
return getColorMatrix(p_obj).getContrast();
-
};
-
-
/**
-
* Changes contrast of a DisplayObject using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @param p_value Number Value of the contrast property (min: -200 / max: 500 / standard: 0)
-
*/
-
public static function __contrast_set (p_obj:DisplayObject, p_value:Number):void
-
{
-
var colorMatrix: ColorMatrix = new ColorMatrix();
-
colorMatrix.setContrast(p_value);
-
setColorMatrix(p_obj, colorMatrix);
-
};
-
-
// ———————————————————————————————————————————-
-
// _saturation_*
-
/**
-
* Gets saturation using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @return Number Value of the saturation property
-
*/
-
public static function __saturation_get (p_obj: DisplayObject):Number
-
{
-
return getColorMatrix(p_obj).getSaturation();
-
};
-
-
/**
-
* Changes saturation of a DisplayObject using ColorMatrix
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @param p_value Number Value of the saturation property (min: -300 / max: 300 / standard: 100)
-
*/
-
public static function __saturation_set (p_obj:DisplayObject, p_value:Number):void
-
{
-
var colorMatrix: ColorMatrix = new ColorMatrix();
-
colorMatrix.setSaturation(p_value);
-
setColorMatrix(p_obj, colorMatrix);
-
};
-
-
-
// ———————————————————————————————————————————-
-
// COLORMATRIX helper functions —————————————————————————————————–
-
-
/**
-
* Helper method for getting the ColorMatrix of a DisplayObject
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @return ColorMatrix ColorMatrix of the Display Object
-
*/
-
private static function getColorMatrix(p_obj: DisplayObject): ColorMatrix
-
{
-
var filters: Array = p_obj.filters;
-
var colorMatrix: ColorMatrix = new ColorMatrix();
-
-
var i:int = filters.length;
-
-
while(–i > -1)
-
{
-
if(filters[i] is ColorMatrixFilter)
-
{
-
colorMatrix.matrix = filters[i].matrix.concat();
-
break;
-
}
-
}
-
return colorMatrix;
-
}
-
-
/**
-
* Helper method for setting the ColorMatrix of a DisplayObject
-
*
-
* @param p_obj DisplayObject A Display Object instance
-
* @param p_value ColorMatrix A ColorMatrix instance
-
*/
-
private static function setColorMatrix(p_obj: DisplayObject, value: ColorMatrix): void
-
{
-
var filters: Array = p_obj.filters;
-
var tFilters: Array = new Array();
-
var colorMatrix: ColorMatrix = value;
-
-
var i:int = filters.length;
-
-
while(–i > -1)
-
{
-
if(!(filters[i] is ColorMatrixFilter))
-
{
-
tFilters.push(filters[i]);
-
}
-
}
-
-
tFilters.push(colorMatrix.filter);
-
p_obj.filters = tFilters;
-
-
}
-
That’s all
. And here are some examples using the special color properties:snippet3.txt ( Download code )
-
//
-
// brightness example
-
Tweener.addTween(myDisplayObject, { _brightness: 100,
-
time: 2,
-
transition: Quintic.easeOut
-
});
-
-
//
-
// contrast example
-
Tweener.addTween(myDisplayObject, { _contrast: -100,
-
time: 2,
-
delay: 2,
-
transition: Quintic.easeOut
-
});
-
-
//
-
// saturation example
-
Tweener.addTween(myDisplayObject, { _saturation: 0,
-
time: 2,
-
delay: 4,
-
transition: Quintic.easeOut
-
});
-
-
snippet2.txt ( Download code )
Download full source
TweenerColorMatrixExample.zip
(Downloads: 2287)
Have fun



August 28th, 2007 at 9:36 pm
Hey, great job! If you could just get rid of that one “l” too many in my name
-
August 29th, 2007 at 2:42 am
Excellent. I have also done this but only for brightness. You should contact Zeh Fernando or have this commited into the google code library so it is official.
August 29th, 2007 at 3:27 am
[...] Comments WS-Blog Tweener AS… on Updated: List of Best Animatio…mondo on Image Manipulation Using ̵…felisan on Image [...]
August 29th, 2007 at 4:03 am
One small typo….
When you say on snippet 2: “Add the following methods to ColorMatrix.as after the method init()mentioned above. Don’t forget to import flash.display.DisplayObject as well.”
You mean in the SpecialPropertiesDefault.as class just so it doesn’t confuse people for a bit.
Good work on the contrast and saturation additions.
August 29th, 2007 at 8:54 am
Yeah! Thanks!
August 29th, 2007 at 9:05 am
Step4 … Don’t forget to import flash.display.DisplayObject as well. AND flash.filters.ColorMatrixFilter;
August 29th, 2007 at 11:14 am
[...] Jens Krause gibt es eine kleine Erweiterung für den Tweener, so dass man auch brightness, _contrast und [...]
August 29th, 2007 at 8:19 pm
Thanks for the contribution Jens!
September 3rd, 2007 at 10:55 am
Hi !!
Very great Job and usefull !!!
Be careful, some errors in your post…
1) Add the following methods to SpecialPropertiesDefault.as (snippet2.txt) not ColorMatrix.as
2) “…Don’t forget to import flash.display.DisplayObject as well…” and flash.filters.ColorMatrixFilter too !!!
Thx
Bye_
September 9th, 2007 at 8:40 pm
[...] colour – brightness, contrast, saturation http://www.websector.de/blog/2007/08/28/tweener-as3-extension-for-color-properties- _brightness-_con… [...]
September 11th, 2007 at 7:07 pm
I had to import flash.filters.ColorMatrixFilter in the SpecialPropertiesDefault.as class, but after that it worked great.
Thanks!
September 11th, 2007 at 9:07 pm
demo looks very cool, but I can’t get it to work…
isn’t there an error on point 4 :
“Add the following methods to ColorMatrix.as after the method init() mentioned above..”
no method init() in ColorMatrix…
thanks !
September 13th, 2007 at 10:22 pm
I’ve converted your code to work with AS2, but it doesn’t seem to be working correctly. I’ve tried tweening the brightness values of a movieclip, without luck. For instance, if I tween the brightness to 100, and then back to 0, it will tween to 100, but will not reset back to 0. Any ideas what might be missing?
September 18th, 2007 at 4:34 am
Very cool class! Thank you!
September 19th, 2007 at 7:03 pm
[...] Krause has an extension to use contrast, saturation and other color properties in Tweener. It’s based on Mario [...]
September 21st, 2007 at 8:16 pm
Could you release this extension for AS2 Tweener version? Nice job man…
September 22nd, 2007 at 2:44 pm
@all: Sorry for my late reply, but I’ve forgotten that I have to login to approve all comments after moving my blog
Anyway, thanks for your great feedback and all helpful tips
@[draw.logic], @Jacob, @Moon, Rob: Thanks for your hints about my typos. I’ve modified them.
@[draw.logic]: I’ve contacted Zeh Fernando, he has already known this extension
@laurent: Sorry, I meant the the init() method within SpecialPropertiesDefault.as
@Quentin: Sorry, I haven’t any idea…
@Alan: Sorry, I’ve not intended to release an AS2 version of this extension.
October 1st, 2007 at 11:52 pm
Great stuff this.
Is there a way i can tween saturation and brightness at the same time?
October 3rd, 2007 at 10:27 am
@Tom: That’s not a simple task, but I think in the next version of Tweener it will be included. Zeh Fernando has something posted about it: http://labs.zeh.com.br/blog/?p=121
October 9th, 2007 at 9:44 pm
[...] a little sample on how to use the tweener class (with some add-ons I found on WS-Blog). I recommend the Tweener to everybody who wants to add some more flavour to flex use the tweener [...]
October 10th, 2007 at 10:00 am
[...] пример иÑÐ¿Ð¾Ð»ÑŒÐ·Ð¾Ð²Ð°Ð½Ð¸Ñ ÐºÐ»Ð°ÑÑа Tweener (Ñ Ð½ÐµÐºÑ‚Ð¾Ñ€Ñ‹Ð¼Ð¸ дополнениÑми), очень Ð¿Ð¾Ð»ÐµÐ·Ð½Ð°Ñ ÑˆÑ‚ÑƒÐºÐ°, как [...]
October 22nd, 2007 at 10:56 am
@Tom: the problem is that this class needs to be reistantiated each time we want apply a new value to a property that was previously modified.
I suppose that this problem can be solved saving a matrix array for each property and in the method concat concats all matrixes in only one (each time a property is modified).
what do you think?
November 29th, 2007 at 2:18 pm
Hey, I’m trying to use your extension with the latest version of tweener, and I can’t seem to make it work. I did everything exactly as described above, and i get some errors. It seems to fail in the two while loops:
while(–i > -1) in line
I tried to change this to: while((i*-1) > -1)
then it got in to an infinite loop and my flash crashed.
I would really appreciate any help i can get.
November 29th, 2007 at 2:25 pm
@Kim: Check out the “IMPORTANT NOTE” described at the beginning of my post using the latest version of Tweener
-sectore
January 17th, 2008 at 6:12 am
Thanks so much!
You just gave me hours of sleeping time!
Great coding!
March 4th, 2008 at 1:39 am
Hi all, i hope someone is still alive and can help me
I’ve sucessfully installed and used this extension but i want to do something that im not understanding how…how can i start with a mc that ha 100% brightness and then bring it down to 0% ?? The contrary way is easy but this…it must be easy too but i’m learning and cant figure it out!
Thanks
March 5th, 2008 at 6:00 pm
@andreb: Please check the note at to top of this post and use the latest version of Tweener instead
. It has already implemented all the color properties mentioned above.
-sectore
March 18th, 2008 at 6:42 pm
Hi, I get this error when using your extension:
ReferenceError: Error #1069:
_brightness is not found at flash.display.Sprite
whats wrong?
April 3rd, 2008 at 9:56 pm
Fernando’s Tweener version for as3 is only at 1.26, not at 1.30 like you say… Also “_saturation” does not work in the latest version, man..
April 4th, 2008 at 8:07 am
Mrtn,
don’t use the *.zip file located on Tweeners project at Google Code. Check out the latest version mentioned above using the source available at its Repository:
http://code.google.com/p/tweener/source/checkout
-Jens
July 22nd, 2008 at 5:24 pm
[...] Krause has an extension to use contrast, saturation and other color properties in Tweener. It’s based on Mario [...]
October 27th, 2008 at 11:32 pm
Hi!
Nice job! I get two errors though in the “snippet2.txt” on lines 97 and 122. The “while(–i > -1)” gives me an error in FlashCS3.
So I had to change that to “while(i > -1)”, and then it worked fine?
Any ideas why this happened?
October 27th, 2008 at 11:35 pm
Hi again!
I just noticed that when I copied the code from above, somehow the “-” sign changed into a longer version of the “-” sign??? Don’t ask me how this happened? So I had to change the “-” sign in the as file into a normal “-” sign, to get it to work… strange computers, sometimes I think they are “alive”…
Cheers
November 5th, 2008 at 9:29 pm
hi, I downloaded the latest version of tweener but I absolutely have no luck getting this extension to work. Can anyone kind enough to have a a working version (using the above FLA/source) send me a zip file? Perhaps Im not doing it right, but spending almost an hour on trying different things I just couldnt get this to work. My email is flashbam@yahoo.com, thanks.
April 17th, 2009 at 9:54 am
@rich
You can use the latest version. Before you can use special properties, you must initialize it first.. This is what i did when i using brightness tween.
//if you want to use brightness, then you need ColorShortcuts..
import caurina.transitions.properties.ColorShortcuts;
//initialize once..
ColorShortcuts.init();
//play around..
Tweener.addTween(aaa, { _brightness:1, time:1} );
Cheers
May 4th, 2010 at 9:29 am
[...] caurina.transitions.ColorMatrix class created by Jens Krause [...]