com.flagstone.transform
Class FSColorTransform

java.lang.Object
  extended by com.flagstone.transform.FSTransformObject
      extended by com.flagstone.transform.FSColorTransform
All Implemented Interfaces:
java.lang.Cloneable

public class FSColorTransform
extends FSTransformObject

The FSColorTransform is used to change the colour of a shape or button without changing the values in the original definition of the object.

Two types of transformation are supported: Add and Multiply

In Add transformations a value is added to each colour channel:

  newRed = red + addRedTerm
  newGreen = green + addGreenTerm
  newBlue = blue + addBlueTerm
  newAlpha = alpha + addAlphaTerm
 

In Multiply transformations each colour channel is multiplied by a given value:

  newRed = red * multiplyRedTerm
  newGreen = green * multiplyGreenTerm
  newBlue = blue * multiplyBlueTerm
  newAlpha = alpha * multiplyAlphaTerm
 

Add and Multiply transforms may be combined in which case the multiply terms are applied to the colour channel before the add terms.

  newRed = (red * multiplyRedTerm) + addRedTerm
  newGreen = (green * multiplyGreenTerm) + addGreenTerm
  newBlue = (blue * multiplyBlueTerm) + addBlueTerm
  newAlpha = (alpha * multiplyAlphaTerm) + addAlphaTerm
 

For each type of transform the result of the calculation is limited to the range 0..255. If the result is less than 0 or greater than 255 then it is clamped at 0 and 255 respectively.

Attributes
multiplyRed The multiply term for the red colour channel.
multiplyGreen The multiply term for the green colour channel.
multiplyBlue The multiply term for the blue colour channel.
multiplyAlpha The optional multiply term for the alpha colour channel.
addRed The add term for the red colour channel.
addGreen The add term for the green colour channel.
addBlue The add term for the blue colour channel.
addAlpha The optional add term for the alpha colour channel.

Not all objects containing a colour transform use the add or multiply terms defined for the alpha channel. The colour objects defined in an FSDefineButton, FSButtonColorTransform or FSPlaceObject object do not use the alpha channel. Transparent colours was introduced in Flash 3. The "parent" object that contains the colour transform controls whether the alpha channel information is encoded or not. Simplifying the alpha channel is not sufficient.

Examples

The class provides a range of constructors to support the different colour transformations. To create a colour transform object specify the values for colour channels in the following order: red, green, blue and optionally alpha:

 float multRed = 1.5f;
 
 float multGreen = 1.5f;
 
 float multBlue = 1.5f;
 
 float multAlpha = 1.5f;
 
 FSColorTransform multiply = new FSColorTransform(multRed, multGreen, multBlue);
 
 FSColorTransform multiplyWithAlpha = new FSColorTransform(multRed, multGreen,
                                multBlue, multAlpha);
 
 int addRed = 128;
 
 int addGreen = 128;
 
 int addBlue = 128;
 
 int addAlpha = 128;
 
 FSColorTransform add = new FSColorTransform(addRed, addGreen, addBlue);
 
 FSColorTransform addWithAlpha = new FSColorTransform(addRed, addGreen, addBlue,
                                addAlpha);
 

For transforms combining both multiply and add terms:

 int addRed = 128;
 
 int addGreen = 128;
 
 int addBlue = 128;
 
 int addAlpha = 128;
 
 float multRed = 1.5f;
 
 float multGreen = 1.5f;
 
 float multBlue = 1.5f;
 
 float multAlpha = 1.5f;
 
 FSColorTransform combined = new FSColorTransform(multRed, multGreen, multBlue,
                                addRed, addGreen, addBlue);
 
 FSColorTransform combinedWithAlpha = new FSColorTransform(multRed, multGreen,
                                multBlue, multAlpha, addRed, addGreen, addBlue, addAlpha);
 

History

The FSCoordTransform class represents the CXForm and CXFormWithAlpha data structures from the Macromedia Flash (SWF) File Format Specification. They were introduced in Flash 1 and Flash 3 respectively.


Constructor Summary
FSColorTransform()
          Constructs an FSColorTransform object defining a unity transform.
FSColorTransform(float redTerm, float greenTerm, float blueTerm)
          Constructs a FSColorTransform object initialised with the specified multiply terms.
FSColorTransform(float redTerm, float greenTerm, float blueTerm, float alphaTerm)
          Constructs a FSColorTransform object initialised with the specified multiply terms, including the alpha channel.
FSColorTransform(float multRedTerm, float multGreenTerm, float multBlueTerm, float multAlphaTerm, int addRedTerm, int addGreenTerm, int addBlueTerm, int addAlphaTerm)
          Constructs a FSColorTransform object initialised with the specified addition and multiplication terms, including alpha channel values.
FSColorTransform(float multRedTerm, float multGreenTerm, float multBlueTerm, int addRedTerm, int addGreenTerm, int addBlueTerm)
          Constructs a FSColorTransform object initialised with the specified addition and multiplication terms.
FSColorTransform(FSCoder coder)
          Construct an FSColorTransform object an initialise with the values decoded from an encoded colour transform
FSColorTransform(FSColorTransform obj)
          Construct an FSColorTansform object and initialize it using a copy of the values from another colour transform.
FSColorTransform(int redTerm, int greenTerm, int blueTerm)
          Constructs an FSColorTransform object with the specified add terms.
FSColorTransform(int redTerm, int greenTerm, int blueTerm, int alphaTerm)
          Constructs an FSColorTransform object with the specified add terms, including the alpha channel.
 
Method Summary
 void appendDescription(java.lang.StringBuffer buffer, int depth)
          AppendDescription is used to present a string description of the object including all nested objects up to a specified depth.
 void decode(FSCoder coder)
           
 void encode(FSCoder coder)
           
 boolean equals(java.lang.Object anObject)
          Returns true if anObject is equal to this one.
 int getAddAlpha()
          Gets the value of the add term for the alpha channel.
 int getAddBlue()
          Gets the value of the add term for the blue channel.
 int getAddGreen()
          Gets the value of the add term for the green channel.
 int getAddRed()
          Gets the value of the add term for the red channel.
 float getMultiplyAlpha()
          Gets the value of the multiply term for the alpha channel.
 float getMultiplyBlue()
          Gets the value of the multiply term for the blue channel.
 float getMultiplyGreen()
          Gets the value of the multiply term for the green channel.
 float getMultiplyRed()
          Gets the value of the multiply term for the red channel.
 boolean isUnityTransform(FSCoder coder)
          Returns true if the values for the add and multiply terms represent a unity transform - one which will not change the colour of a shape.
 int length(FSCoder coder)
           
 void setAddAlpha(int aNumber)
          Sets the value for the addTerm which will be applied to the alpha colour channel.
 void setAddBlue(int aNumber)
          Sets the value for the addTerm which will be applied to the blue colour channel.
 void setAddGreen(int aNumber)
          Sets the value for the addTerm which will be applied to the green colour channel.
 void setAddRed(int aNumber)
          Sets the value for the addTerm which will be applied to the red colour channel.
 void setAddTerms(int redTerm, int greenTerm, int blueTerm)
          Sets the values for the add terms for the red, green and blue colour channels.
 void setAddTerms(int redTerm, int greenTerm, int blueTerm, int alphaTerm)
          Sets the values for the add terms for each of the colour channels.
 void setMultiplyAlpha(float aNumber)
          Sets the value for the multiplyTerm which will be applied to the alpha colour channel.
 void setMultiplyBlue(float aNumber)
          Sets the value for the multiplyTerm which will be applied to the blue colour channel.
 void setMultiplyGreen(float aNumber)
          Sets the value for the multiplyTerm which will be applied to the green colour channel.
 void setMultiplyRed(float aNumber)
          Sets the value for the multiplyTerm which will be applied to the red colour channel.
 void setMultiplyTerms(float redTerm, float greenTerm, float blueTerm)
          Sets the values for the multiply terms for the red, green and blue colour channels
 void setMultiplyTerms(float redTerm, float greenTerm, float blueTerm, float alphaTerm)
          Sets the values for the multiply terms for each of the colour channels
 
Methods inherited from class com.flagstone.transform.FSTransformObject
clone, name, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FSColorTransform

public FSColorTransform(FSCoder coder)
Construct an FSColorTransform object an initialise with the values decoded from an encoded colour transform

Parameters:
coder - an FSCoder object containing the encoded colour transform.

FSColorTransform

public FSColorTransform()
Constructs an FSColorTransform object defining a unity transform. If the transform is applied to a shape its colour will not change.


FSColorTransform

public FSColorTransform(int redTerm,
                        int greenTerm,
                        int blueTerm)
Constructs an FSColorTransform object with the specified add terms. Each colour channel is transformed by the following calculation:
            newRed = red + addRedTerm
            newGreen = green + addGreenTerm
            newBlue = blue + addBlueTerm
        
 
The add term value for the alpha channel defaults to 0 so if the transform is added to an object that uses alpha channel information then the alpha channel will remain unchanged. In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
redTerm - value to add to the red colour channel.
greenTerm - value to add to the green colour channel.
blueTerm - value to add to the blue colour channel.

FSColorTransform

public FSColorTransform(int redTerm,
                        int greenTerm,
                        int blueTerm,
                        int alphaTerm)
Constructs an FSColorTransform object with the specified add terms, including the alpha channel. Each colour channel is transformed by the following calculation:
            newRed = red + addRedTerm
            newGreen = green + addGreenTerm
            newBlue = blue + addBlueTerm
            newAlpha = alpha + addAlphaTerm
        
 
In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
redTerm - value to add to the red colour channel.
greenTerm - value to add to the green colour channel.
blueTerm - value to add to the blue colour channel.
alphaTerm - value to add to the alpha colour channel.

FSColorTransform

public FSColorTransform(float redTerm,
                        float greenTerm,
                        float blueTerm)
Constructs a FSColorTransform object initialised with the specified multiply terms. Each colour channel is transformed by the following calculation:
            newRed = red * multiplyRedTerm
            newGreen = green * multiplyGreenTerm
            newBlue = blue * multiplyBlueTerm
        
 
The multiply term value for the alpha channel defaults to 1.0 so if the transform is added to an object that uses alpha channel information then the alpha channel will remain unchanged. In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
redTerm - value to multiply the red colour channel by.
greenTerm - value to multiply the green colour channel by.
blueTerm - value to multiply the blue colour channel by.

FSColorTransform

public FSColorTransform(float redTerm,
                        float greenTerm,
                        float blueTerm,
                        float alphaTerm)
Constructs a FSColorTransform object initialised with the specified multiply terms, including the alpha channel. Each colour channel is transformed by the following calculation:
            newRed = red * multiplyRedTerm
            newGreen = green * multiplyGreenTerm
            newBlue = blue * multiplyBlueTerm
            newAlpha = alpha * multiplyAlphaTerm
        
 
In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
redTerm - value to multiply the red colour channel by.
greenTerm - value to multiply the green colour channel by.
blueTerm - value to multiply the blue colour channel by.
alphaTerm - value to multiply the alpha colour channel by.

FSColorTransform

public FSColorTransform(float multRedTerm,
                        float multGreenTerm,
                        float multBlueTerm,
                        int addRedTerm,
                        int addGreenTerm,
                        int addBlueTerm)
Constructs a FSColorTransform object initialised with the specified addition and multiplication terms. Each colour channel is transformed by the following calculation:
            newRed = (red * multiplyRedTerm) + addRedTerm
            newGreen = (green * multiplyGreenTerm) + addGreenTerm
            newBlue = (blue * multiplyBlueTerm) + addBlueTerm
        
 
The multiply and add terms for the alpha channel default to 1.0 and 0 respectively so for objects that use the alpha channel information then the alpha channel will remain unchanged. In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
multRedTerm - value to multiply the red colour channel by.
multGreenTerm - value to multiply the green colour channel by.
multBlueTerm - value to multiply the blue colour channel by.
addRedTerm - value to add to the red colour channel.
addGreenTerm - value to add to the green colour channel.
addBlueTerm - value to add to the blue colour channel.

FSColorTransform

public FSColorTransform(float multRedTerm,
                        float multGreenTerm,
                        float multBlueTerm,
                        float multAlphaTerm,
                        int addRedTerm,
                        int addGreenTerm,
                        int addBlueTerm,
                        int addAlphaTerm)
Constructs a FSColorTransform object initialised with the specified addition and multiplication terms, including alpha channel values. Each colour channel is transformed by the following calculation:
            newRed = (red * multiplyRedTerm) + addRedTerm
            newGreen = (green * multiplyGreenTerm) + addGreenTerm
            newBlue = (blue * multiplyBlueTerm) + addBlueTerm
            newAlpha = (alpha * multiplyAlphaTerm) + addAlphaTerm
        
 
In the Flash Player the value assigned to the respective colour channel is clamped to the range 0..255.

Parameters:
multRedTerm - value to multiply the red colour channel by.
multGreenTerm - value to multiply the green colour channel by.
multBlueTerm - value to multiply the blue colour channel by.
multAlphaTerm - value to multiply the alpha colour channel by.
addRedTerm - value to add to the red colour channel.
addGreenTerm - value to add to the green colour channel.
addBlueTerm - value to add to the blue colour channel.
addAlphaTerm - value to add to the alpha colour channel.

FSColorTransform

public FSColorTransform(FSColorTransform obj)
Construct an FSColorTansform object and initialize it using a copy of the values from another colour transform.

Parameters:
obj - a colour transform.
Method Detail

getMultiplyRed

public float getMultiplyRed()
Gets the value of the multiply term for the red channel.

Returns:
the value that will be multiplied with the red colour channel's value.

getMultiplyGreen

public float getMultiplyGreen()
Gets the value of the multiply term for the green channel.

Returns:
the value that will be multiplied with the green colour channel's value.

getMultiplyBlue

public float getMultiplyBlue()
Gets the value of the multiply term for the blue channel.

Returns:
the value that will be multiplied with the blue colour channel's value.

getMultiplyAlpha

public float getMultiplyAlpha()
Gets the value of the multiply term for the alpha channel.

Returns:
the value that will be multiplied with the alpha colour channel's value.

getAddRed

public int getAddRed()
Gets the value of the add term for the red channel.

Returns:
the value that will be added to the red colour channel's value.

getAddGreen

public int getAddGreen()
Gets the value of the add term for the green channel.

Returns:
the value that will be added to the green colour channel's value.

getAddBlue

public int getAddBlue()
Gets the value of the add term for the blue channel.

Returns:
the value that will be added to the blue colour channel's value.

getAddAlpha

public int getAddAlpha()
Gets the value of the add term for the alpha channel.

Returns:
the value that will be added to the alpha colour channel's value.

setMultiplyRed

public void setMultiplyRed(float aNumber)
Sets the value for the multiplyTerm which will be applied to the red colour channel.

Parameters:
aNumber - the value to be multiplied with the red colour channel's value.

setMultiplyGreen

public void setMultiplyGreen(float aNumber)
Sets the value for the multiplyTerm which will be applied to the green colour channel.

Parameters:
aNumber - the value to be multiplied with the green colour channel's value.

setMultiplyBlue

public void setMultiplyBlue(float aNumber)
Sets the value for the multiplyTerm which will be applied to the blue colour channel.

Parameters:
aNumber - the value to be multiplied with the blue colour channel's value.

setMultiplyAlpha

public void setMultiplyAlpha(float aNumber)
Sets the value for the multiplyTerm which will be applied to the alpha colour channel.

Parameters:
aNumber - the value to be multiplied with the alpha colour channel's value.

setMultiplyTerms

public void setMultiplyTerms(float redTerm,
                             float greenTerm,
                             float blueTerm)
Sets the values for the multiply terms for the red, green and blue colour channels

Parameters:
redTerm - value to multiply the red colour channel by.
greenTerm - value to multiply the green colour channel by.
blueTerm - value to multiply the blue colour channel by.

setMultiplyTerms

public void setMultiplyTerms(float redTerm,
                             float greenTerm,
                             float blueTerm,
                             float alphaTerm)
Sets the values for the multiply terms for each of the colour channels

Parameters:
redTerm - value to multiply the red colour channel by.
greenTerm - value to multiply the green colour channel by.
blueTerm - value to multiply the blue colour channel by.
alphaTerm - value to multiply the alpha colour channel by.

setAddRed

public void setAddRed(int aNumber)
Sets the value for the addTerm which will be applied to the red colour channel.

Parameters:
aNumber - the value to be added to the red colour channel's value.

setAddGreen

public void setAddGreen(int aNumber)
Sets the value for the addTerm which will be applied to the green colour channel.

Parameters:
aNumber - the value to be added to the green colour channel's value.

setAddBlue

public void setAddBlue(int aNumber)
Sets the value for the addTerm which will be applied to the blue colour channel.

Parameters:
aNumber - the value to be added to the blue colour channel's value.

setAddAlpha

public void setAddAlpha(int aNumber)
Sets the value for the addTerm which will be applied to the alpha colour channel.

Parameters:
aNumber - the value to be added to the alpha colour channel's value.

setAddTerms

public void setAddTerms(int redTerm,
                        int greenTerm,
                        int blueTerm,
                        int alphaTerm)
Sets the values for the add terms for each of the colour channels.

Parameters:
redTerm - value to add to the red colour channel.
greenTerm - value to add to the green colour channel.
blueTerm - value to add to the blue colour channel.
alphaTerm - value to add to the alpha colour channel.

setAddTerms

public void setAddTerms(int redTerm,
                        int greenTerm,
                        int blueTerm)
Sets the values for the add terms for the red, green and blue colour channels.

Parameters:
redTerm - value to add to the red colour channel.
greenTerm - value to add to the green colour channel.
blueTerm - value to add to the blue colour channel.

equals

public boolean equals(java.lang.Object anObject)
Returns true if anObject is equal to this one. Objects are considered equal if they would generate identical binary data when they are encoded to a Flash file.

Overrides:
equals in class FSTransformObject
Returns:
true if this object would be identical to anObject when encoded.

appendDescription

public void appendDescription(java.lang.StringBuffer buffer,
                              int depth)
Description copied from class: FSTransformObject
AppendDescription is used to present a string description of the object including all nested objects up to a specified depth. This method provide a more controlled way of creating a string representation of an object since large objects such as font or shape definitions can contain dozens of nested objects. The representation of the object is appended to the StringBuffer, showing the name of the class and values of the attributes it contains. If the object contains any attributes that are objects then the object graph will be traversed up to the specified depth. If objects are nested at a level less than specified depth then the full string representation of the object is displayed. For objects at the specified depth only the name of the class is displayed. Any objects below this depth are not displayed.

Specified by:
appendDescription in class FSTransformObject
Parameters:
buffer - a StringBuffer to which the description of each object is appended.
depth - the maximum level of nesting up to which objects will be displayed.

length

public int length(FSCoder coder)
Specified by:
length in class FSTransformObject

encode

public void encode(FSCoder coder)
Specified by:
encode in class FSTransformObject

decode

public void decode(FSCoder coder)
Specified by:
decode in class FSTransformObject

isUnityTransform

public boolean isUnityTransform(FSCoder coder)
Returns true if the values for the add and multiply terms represent a unity transform - one which will not change the colour of a shape. Whether the alpha channel is included is determined by the context associated with the FSCoder object.

Parameters:
coder - the FSCoder used to encoded the transform.
Returns:
true if the object represents a unity transform, false otherwise.