------------------------------------------------------------
  Release Notes for Transform SWF for Java, Version 2.1.
------------------------------------------------------------

This release brings forward a lot of changes discussed in the roadmap for 
Version 3.0. The two most important ones are:

Transform Utilities classes are included in the package structure.
Lazy decoding of actions and shapes which brings huge performance gains.

Other changes are mostly administrative, cleaning up code and generally 
resolving minor technical issues and improving support and use of TestNG for 
testing and verification.

The project is also open to code contributed by other developers. A new 
package transform.contrib is now included in the source tree for code not 
covered by Flagstone's copyright. This package is open for any code which maybe 
useful for developers - as long as it is compatible with the BSD licence.

Bug Fixes          
    FSPush: FSProperty objects are cloned correctly.     
    FSTextConstructor handles file names in upper case.     
 
New Classes 
    FSCharacterTable providing character sets for FSTextConstructor     
    FSCoderException to handle and report encoding or decoding errors.     

Class Changes   
    FSMovieTest: Added methods to benchmark code performance.     
    FSTransformObject: methods used to encode/decode classes are public.     
    Added copy constructors on all classes.     
    Removed redundant exception declarations.
    Added the constructor public FSTextConstructor(int, Font).
    FSTextConstructor: added reset method.
    FSTextConstructor: added willDisplay method.
    Tidied up FSCoder class and deprecated FSCodec.
    TransformUtil is deprecated.
    Deprecated the FSMovieListener interface.

Internal Class Changes     
    Canonical objects are now used.     
    Added lazy decoding of shapes and actions.     
    Improved decoding of JPEG image data.     
 
Package Changes      
    Merged Transform and Transform Utilities.     
    Added a package for contrubuted code.     
 
 
-------------
  Bug Fixes  
-------------

1. FSPush: FSProperty objects are cloned correctly.  

FSProperty objects are now copied into the cloned array. Previously the 
cloned array "dropped" any FSPropert objects. 

2. FSTextConstructor handles file names in upper case.  

File names in upper case are now handled - this makes using TrueType files 
from Windows systems much easier.


---------------
  New Classes  
---------------

1. FSCharacterTable providing character sets for FSTextConstructor  

The willDisplay() method on FSTextConstructor (see below) is used to 
define the characters that will be encoded in a font. The FSCharacterTable 
class provided arrays of characters that can be used with the willDisplay
method. Different character sets are provided for ISO 8859-1 as well as 
characters for the main European languages. 

2. FSCoderException to handle and report encoding or decoding errors.  

Added a new exception class, FSCoderException to report when underflow or
overflow errors occur when encoding or decoding objects. Previously only the 
more general IOException was reported. FSCoderException contains information on 
the location of the data structure in the file that caused the error making 
diagnosis much easier.

-----------------
  Class Changes  
-----------------

1. FSMovieTest: Added methods to benchmark code performance.  

Updated FSMovieTest.java to record the time taken to decode and encode
Flash files. TestNG scripts for running the tests were added to the directory
test\benchmarks. The benchmark tests use Flash files stored in the directories
text\data\movies\swf&lt;x&gt;

The benchmarks measure the time taken to decode or encode a given Flash file
100 times and are best suited to measure relative improvements when optimizing 
the code in the Transform classes.

2. FSTransformObject: methods used to encode/decode classes are public.  

The methods used to encode and decode objects:

    int length(FSCoder)
    void decode(FSCoder)
    void encode(FSCoder)


along with the constructor for each class that initialised an object with
binary data decoded from an FSCoder object are all "upgraded" to public to 
support testing with TestNG.

3. Added copy constructors on all classes.  

All classes now have copy constructors to complement the clone()
method.

4. Removed redundant exception declarations.  

Removed redundant exceptions declarations from method signatures:
FileNotFoundException is covered by IOException. Applies to FSMovie,
FSSoundConstructor, FSImageConstructor. This change is simply aesthetic all the 
removed exceptions are subclasses of IOException.

5. Added the constructor public FSTextConstructor(int, Font).  

FSTextConstructor had a single constructor FSTextConstructor(int, String)
which was used to pass names of files and names of fonts. This new constructor
was added to clearly differentiate fonts from files. Existing code is unaffected
and will continue to operate in all future releases however use of this new
method is encouraged when using AWT font definitions.

6. FSTextConstructor: added reset method.  

Added a reset(int) method to allow FSTextConstructor objects to be reused 
when generating objects for more than one Flash file. The reset method clears
the internal table used to track the order in which characters are used. This 
allows the same FSTextConstructor object to be used to generate multiple font
definitions. This is particularly useful when using AWT based fonts where the 
time taken to decode the font definitions is relatively large.

7. FSTextConstructor: added willDisplay method.  

Added the method, willDisplay(char[]) to allow sets of characters to be 
defined before creating any text objects.

This solves the bug where characters were encoded in the order they were used 
but not in ascending order of character code. This also simplifies using 
FSTextConstructor class where previously text objects had to be defined before 
the font definition was created.

A corresponding canDisplay(char[]) method was added to verify that a given
font can display all of the characters in a given set.

8. Tidied up FSCoder class and deprecated FSCodec.  

Tidied up the FSCoder class, making all methods more reliable and merging in
functionality from Transform Utilities FSCodec. All decoding and encoding of 
data is now performed using FSCoder. FSCodec is deprecated.

9. TransformUtil is now deprecated.  

with the merging of the Transform and Transform Utilities packages the 
class TransformUtil is no longer required to provide basic version information
and is now deprecated.

10. Deprecated the FSMovieListener interface.  

Deprecated the FSMovieListener interface, FSMovieEvent class and the methods 
on the FSMovie class that used them.

The FSMovieListener interface was originally used to support Describe. When 
a movie was parsed the values decoded were reported to a FSMovieListener. This 
allowed Describe to build a tree of objects so the contents of a Flash file 
could be browsed.

The interface also allowed errors to be reported so a file could be decoded 
even if part of it was corrupted - some third-party tools are known to contain 
bugs that generate errors. The Flash Player is robust when encountering this 
type of error so the Movie Listener interface was an attempt to introduce 
robustness into Transform.

In practice the value of the interface was limited. Files containing errors
 which would cause errors were relatively unusual and when an error was detected 
 it was not obvious that recovering form the error was useful.


--------------------------
  Internal Class Changes  
--------------------------

1. Canonical objects are now used.  

Added canonical version of objects that can be safely shared since they 
contain no editable attributes. The classes affected are FSNull, FSVoid, 
FSAction, FSCall, FSShowFrame and FSPathsArePostscript. The most significant is 
FSAction which specifies byte-codes for stack-based actionsand so will boost 
performance when decoding files. The numbers of objects involved for other
classes are much smaller in comparison but are included for completeness.

2. Added lazy decoding of shapes and actions.  

Added lazy decoding of actions to FSButtonEvent, FSClipEvent, FSDoAction, 
FSDefineButton and FSInitialize. The encoded actions will be stored in binary
form in these objects until accessed using the getActions() or addAction()
methods. When either of these methods are used the encoded actions will be 
decoded into an array of FSAction objects. This reduces the number of objects
created when a file is decoded so that only the actions accessed are decoded.

Similarly for classes that define shapes. The array of FSLine, FSCurve and 
FSShapeStyle objects are stored in binary form then decoded only when the array
is accessed. The classes that define shapes are FSDefineShape, FSDefineShape2, 
FSDefineShape3, FSDefineMorphShape, FSDefineFont and FSDefineFont2. Accessing
shape objects is relatively unusual so lazy decoding speeds up processing by 
only decoding objects that are used.

Lazy decoding provides an enormous increase in performance. Benchmark tests
when decoding files gave average performance increases of 15 times - with a 
range between 0 and 420 times. Larger files gave larger performance gains.

This is particularly important when using existing Flash files as a 
template for customization. Simply replacing images, text and sound in a file
does not typically need font glyphs and shapes to be decoded and using lazy 
decoding can dramatically increase performance.

Lazy decoding and encoding does not require any API changes.

3. Improved decoding of JPEG image data.  

Improved the algorithm when decoding the encoding table in the classes
FSDefineJPEGImage2 and FSDefineJPEGImage3. The encoding table is now processed 
correctly, even when the encoding table is empty and the start of image (SOI) 
and end of image (EOI) markers are incorrectly specified.


-------------------
  Package Changes  
-------------------

1. Merged Transform and Tranform Utilities.

Merged the classes from Transform Utilities into the Transform framework to 
create a single release. All future releases will include the Utilities classes.
Transform Utilities will no longer be released as a separate framework.

Consequently the class, TransformUtil, which contains version number 
information is deprecated and will be dropped in Transform 2.2.

2. Added a package for contributed code.

A new package transform.contrib is included for code from third-parties
that can be used with the classes in the Transform framework but which is not 
subject to the same licencing terms or copyright ownership.

Contributed code can be found in the directory src/transform/contrib. Any 
code may be contributed to the project as long as it is compatible with the 
terms of the BSD licence. All rights are retained by the author(s). Flagstone 
specifically disclaims any rights to the code.

The first contributed class is the code to compress WAV files to ADPCM. The 
code is a Java port of C code released by Jack Jansen, Stichting Mathematisch 
Centrum, Amsterdam, The Netherlands. This code was previously available on the 
Flagstone web site and will now be included in future releases.
