------------------------------------------------------------ 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<x> 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.