Acorn User 10

home *** CD-ROM | disk | FTP | other *** search

/ Acorn User 10 / AU_CD10.iso / Archived / Updates / Flash / writeflash / !MakeFlash / !Help < prev next >

Wrap

Text File | 2000-06-04 | 30KB | 980 lines

writeflash 0.10 =============== writeflash creates Flash 3 files from simple script-files. !MakeFlash is a simple frontend for writeflash. Copyright ========= The program is copyright © Henrik Bjerregaard Pedersen, 2000 and is released under the GPL (any version). Using writeflash ================ writeflash is a command-line program and may be run from a task-window, shell or obey-file or from another program. writeflash [-pl] <input> [<output>] If no output file is specified, the result will be output to the standard output stream - either the screen (bad idea) or a file, depending on redirection. Switches: -pl print lines as they are being read by the parser; this is very useful if the parser reports an error, as it allows you to easily find which line contains the error Using !MakeFlash ================ MakeFlash is a simple frontend for writeflash. When run, it installs itself on the iconbar, and you may then drag a script-file to its icon - a save-box will then pop up. Script file syntax ================== A script-file is a text file containing a textual description of the flash file you want to create. The script-file may also contain commands for the script-processor; the script-processor greatly simplifies many trivial operation when creating the script-file. The script-file is read line by line but is parsed one token at a time. A token is either a tag (eg. "FileVersion" or "DefineShape") or a fieldname (eg. "id" or "matrix") or a value or left or right curly brackets. Tokens must be seperated by a white-space (space, linefeed, carriage-return or TAB). Tags and fieldnames are case-insensitive. Comments may be included in a script-file: // indicates that the rest of the line is a comment. All tags except FileVersion, FrameRate and BackgroundColour require a structure as argument. A structure contains a number of fieldnames/values. A structure starts with a "{" (left curly bracket), then follows pairs of fieldnames and values (values may be structures themselves, although in that case the are no fieldnames in the structure) and the list is terminated by a "}" (right curly bracket); eg.: PlaceObject { depth 1 id 1 matrix { 65536 65536 0 0 0 0 } } Types ===== The following data types are supported: U8 unsigned 8 bit integer S8 signed 8 bit integer U16 unsigned 16 bit integer S16 signed 16 bit integer U32 unsigned 32 bit integer S32 signed 32 bit integer bbox { S32 S32 S32 S32 } matrix { S32 S32 S32 S32 S32 S32 } cxform { S16 S16 S16 S16 S16 S16 S16 S16} RGB { U8 U8 U8 } or 24 bit integer (written as hex: BBGGRR) RGBA { U8 U8 U8 U8 } or 32 bit integer (written as hex: AABBGGRR) gradient 1..8 pairs of U8 RGBA string string, enclosed in " " RGBA ==== RGBA values are specified as either A) a structure with 3 or 4 values { R G B A }, eg. { 0 128 64 255 } for R (red) = 0 (0%) G (green) = 128 (50%) B (blue) = 64 (25%) A (alpha) = 255 (100%) if only 3 values are specified, A is set to 255 or B) an 8 digit hexadecimal value, eg 00446688 for A (alpha) = 0 (0x00) (0%) B (blue) = 68 (0x44) (26%) G (green) = 102 (0x66) (40%) R (red) = 136 (0x88) (53%) An alpha value of 0 means completely transparent, 255 (0xff) means completely opaque. Matrix ====== Often matrices only contain scaling or scaling/translation. To make entry of these easier, you may specify less than the usual 6 values in a matrix. The remaining values are set to their default values, which are: scalex 65536 scaley 65536 rotate0 0 rotate1 0 translatex 0 translatey 0 no. of values treated as 0 (default values) 1 scaling (both scalex and scaley) 2 scalex , scaley 3 scaling, translatex, translatey 4 scalex, scaley, translatex, translatey 5 NOT ALLOWED Colour Transforms (cxform) ========================== A colour-transform transform RGBA values in a shape, using the formulaes R = R*MULR/255 + ADDR G = G*MULG/255 + ADDG B = B*MULB/255 + ADDB A = A*MULA/255 + ADDA The format of a colourtransform is { MULR MULG MULB MULA ADDR ADDG ADDB ADDA } IDs === Flash uses 16 bit IDs to reference objects, characters, bitmaps, fonts etc. IDs should be unique within a Flash-file. writeflash will assume that IDs from 20000 to 49999 are reserved for future use by writeflash, IDs from 50000 to 59999 are reserved for fonts and IDs from 60000 to 65535 are reserved for other pre-defined shapes. Supported tags ============== The following tags are supported: aliases FileVersion FrameArea FrameRate BackgroundColour BgColour DefineShape Shape PlaceObject Place RemoveObject Remove DefineSound Sound PlaySound ShowFrame DoAction Protect Text Font JPEG Button End Tags ==== FileVersion ----------- Defines the version of the file. There should only be one "FileVersion" tag in a script. Argument: U8 Example: FileVersion 1 FrameArea --------- Specifies the size of the display area for the Flash file; also defines the scaling factors for all coordinates in the script-file. Argument: framearea-structure Example: FrameArea { width 5000 height 4000 scalex 1000 scaley -1000 // flip y } The framearea-structure may include any of the following fields: name argumenttype width U16 height U16 scalex S32 scaley S32 The default value for scalex and scaley is 1000 (100%). The scale/rotateskew values in a matrix cannot be scaled using scalex and scaley; instead, they are all scaled using SQRT(ABS(scalex*scaley)). You may include more than one FrameArea tag in a script-file. FrameRate ---------- Specifies the framerate for the Flash file. Argument: U8.U8 Example: FrameRate 10.0 BackgroundColour / BGColour ----------------------------- Specifies the background colour for the Flash file. Argument: RGB Examples: BackgroundColour ff0000 // blue BackgroundColour { 0 0 255 } // blue DefineShape / Shape --------------------- Defines a shape which is added to the dictionary of defined characters. Argument: shape-structure Example: DefineShape { id 1 fillstyle { solid ff00ff00 // fillestyle #1 linear { // fillestyle #2 matrix { 65536 65536 0 0 0 0 } gradient { 0 00ff00 255 008000 } } } linestyle { 80 ffff0000 // define linestyle#1 80 ff000000 } // define linestyle#2 selectlinestyle 1 // default is 0, which fill0 2 // means "don't draw" fill1 1 moveby { 200 200 } lineby { 200 0 } } Possible fields in the shape-structure: name argumenttype id U16 (required) bbox bbox (only used in v0.02) linestyle linestyle-structure fillstyle fillstyle-structure selectlinestyle U32 selectfillstyle0 fill0 U32 selectfillstyle1 fill1 U32 moveto { S32 S32 } moveby { S32 S32 } lineby { S32 S32 } curveby { S32 S32 S32 S32 } Each fillstyle/linestyle structure defines a number of fill- or line-styles. You may have multiple fillstyle/linestyle structures. A fillstyle-structure contains any combination of the following fields: name argumenttype solid RGBA linear gradient-fill-structure radial gradient-fill-structure tiled bitmap-fill-structure clipped bitmap-fill-structure A linestyle-structure one or more pairs of linestyle-values - first value is the linewidth (U16), second value is the colour (RGBA). A gradient-fill-structure contains the following fields: name argumenttype matrix matrix gradient gradient A bitmap-fill-structure contains the following fields: name argumenttype id U16 matrix matrix PlaceObject / Place --------------------- Places a character (a shape from from the dictionary) on the screen. Argument: place-object-structure Example: PlaceObject { id 1 depth 1 matrix { 32768 32768 0 0 0 0 } } The place-object-structure must contain the following fields: name argumenttype depth U16 and may also contain: id U16 matrix matrix cxform cxform clip U16 frame U16 Only one object can exist at a given depth. If no id is given in the place-object-structure, it is assumed that the matrix (and cxform) modify the object at the specified depth. Notice, you cannot place bitmaps (eg. JPEGs) on the screen this way. You have to create a shape which uses the bitmap for filling and then place that object. If a frame number is given in the structure, the object will be placed in the specified frame; you can only address previously defined frames this way. 'clip' allows a shape to mask out shapes on lower levels. RemoveObject / Remove ----------------------- Removes an object (a character) from the screen. Argument: remove-object-structure Example: RemoveObject { id 5 // not needed, ignored depth 5 } The remove-object structure must contain the following fields: name argumenttype depth U16 and may also contain the following fields: frame U16 If a frame number is given in the structure, the object will be removed from the screen at the specified frame; you can only address previously defined frames this way. ShowFrame --------- Displays the frame. Argument: an empty structure Example: ShowFrame { } Protect ------- Protect the file from editing in editors. Argument: an empty structure Example: Protect { } DoAction -------- Adds a number of actions to the current frame. Argument: action-list structure Examples: DoAction { gotoframe 0 play } DoAction { geturl { url "http://www.hanseman-luchter.net" target "__new" // or whatever... } } The action-list structure contains a list of actions; each action starts with the actionname and is followed by the arguments (if any) to the action. Currently supported actions are: name argumenttype gotoframe U16 (frame no.) play - stop - nextframe - previousframe - stopsounds - geturl geturl-structure The geturl-structure must include the following fields: url string and may optionlly also include the following fields: target string Action-list structures are also used when defining buttons. JPEG ---- Adds a JPEG to the dictionary. Argument: JPEG-structure Example: JPEG { id 54 file "test2.jpg" width 200 height 160 alphafile "test2.alpha" } The JPEG-structure must include the following fields: name argumenttype id U16 file string and may also include the following fields: alphafile string width U16 height U16 If the alphafile field is included, the file is assumed to contain a ZLIB compressed 8 bits-per-pixel image with the same dimensions as the JPEG. The width and height fields MUST be present if the alphafile field is included. Button ------ Creates a button. Argument: button-structure Example: Button { id 9 up { id 6 depth 6 // not quite sure what this does } actions { gotoframe 15 play } } The button-structure must contain the following fields: name argumenttype id U16 up buttonstate structure actions action-list structure (see DoAction) and may also contain these fields: over buttonstate structure down buttonstate structure activearea buttonstate structure The buttonstate structures contain the following fields: id U16 depth U16 and may also include the following fields: matrix matrix The various buttonstate structures define which character (which must also be defined in the script-file) to use for the various states of the button. The activearea structure defines which character to use to detect when the mouse is over the button. You may include multiple up/over/down/activearea structure in a button. The over/down/activearea structures default to the same as the up structure. Font ---- Defines a font. Argument: font-structure Example: Font { id 55 glyph { char "A" moveby { 100 1000 } curveby { 1000 1000 1000 -1000 } lineby { -1000 -1000 } lineby { -1000 1000 } } glyph { char "x" moveby { 100 1000 } curveby { 1000 1000 1000 -1000 } lineby { -1000 -1000 } lineby { -1000 1000 } } scale { 46200 45600 } spacing 100 } The font-structure must contain the 'id' field, and a least one glyph structure: name argumenttype char string (one char) or U8 A glyph-structure must also contains a shape, in the form of a sequence of moveto { }, moveby { }, lineby { } and curveby { } structures. The font-structure may also include the following fields: scale { S32 S32 } spacing S16 The scale field specifies how to scale the coordinates in the glyph-shapes. The glyph-coordinates should be scaled so that all glyphs fit inside a 1024x1024 box (the EM square). The spacing is inserted between each char/letter. A font-defintion for all letters, numbers etc. may take up several kbytes; therefore writeflash doesn't save a glyph (the shape defining a letter or number or sign) if it isn't being used by any of the text-objects in the file; eg. if you define a font with 100 glyphs, but only use the glyphs for the letters in the word 'Hello', then only the glyphs for the letters 'H', 'e', 'l', and 'o' will be saved. However, this can be disabled by defining the macro INCLUDE_ALL_GLYPHS, ie. by including the line '#define INCLUDE_ALL_GLYPHS' in the script. DefineSound / Sound ------------------- Adds a sound to the dictionary. Argument: sound-structure Example: Sound { id 123 file "$.samplefile" format "LIN8" channels 1 freq 22 } The sound-structure must include the following fields: name argumenttype id U16 file string format string channels U16 freq U16 format must be either "LIN8", "LIN16", "ADPCM2", "ADPCM3", "ADPCM4" or "ADPCM5" (case-sensitive). The value of the channels field must be either 1 (mono) or 2 (stereo). The freq field specifies the sample rate. It must be either 5 (5.5kHz), 11 (11kHz), 22 (22kHz) or 44 (44kHz). The file will simply be inserted as the SoundData field in the DefineSound structure, ie. it will not be processed or converted in any way, and if the file has some kind of header, that will be included as well. ADPCM and stereo formats have not been tested. PlaySound --------- Plays a sound. Argument: playsound-structure Example: PlaySound { id 123 loops 3 frame 45 } The playsound-structure must contain the id field, and may also contain any of the following fields: name argumenttype loops U16 frame U16 If a frame number is given in the structure, the sound will be played at the specified frame; you can only address previously defined frames this way. Text ---- Defines a text-string. Argument: text-structure Example: Text { id 56 // to be used by PlaceObject { } matrix { } // default matrix style { font 55 size 48 colour ffffff00 move { 10261 0 } } text "Hello, world!" } The text-structure must include the 'id' field, and may also include a transformation matrix. Besides that, the text-structure must also contain at least one style- and one text-field. name argumenttype text string style textstyle-structure There must be a style-field before the first text-field, otherwise the player will not know which font/fontsize/colour/position to use. The textstyle-structure may contain any of these fields (the first textstyle-structure in a text-structure must contain all fields): name argumenttype font U16 size U16 colour RGBA move { S16 S16 } Preprocessor/Script-processor ============================== The script-processor provides both a simple one-pass preprocessor and allows you to do things like looped and conditional parsing. Preprocessor ------------ Lines starting with the character '#' are considered preprocessor-directives and are processed when the script-file is read into memory before parsing. That the pre-processor is 'one-pass' means that macros may refer to other macros that have been define earlier in the file, but they may not refer to macros that are defined later on in the file. The following preprocessor-directives are supported: #include <filename> ------------------- Inserts the specified file in the script; this allows you to build a library of commonly used shapes (eg. fonts or logos) and reuse them in any script-file. Example: #include FlashLib:Fonts.Homerton.Medium #define <macroname> [<value>] ----------------------------- Defines a macro, and optionally assignes a value to it. Whenever the script-file parser finds a reference to the macro, it is replaced with the value of the macro. It may also be used together with #ifdef and #ifndef to force the parser to ignore parts of the script-file. Examples: #define INCLUDE_LOGO #define FONTSIZE 45 #define FILLSTYLE3 { solid ff00ff00 } Macronames must start with a letter or the character '_', and may only include letters, numbers and the character '_'. #ifdef <macroname> ------------------ The script-file lines following the #ifdef lines (until an #endif) are only parsed if the macro has been defined. #ifdef .. #endif may be nested. Example: #ifdef INCLUDE_LOGO PlaceObject { id LOGOID depth LOGODEPTH matrix { } } #endif #ifndef <macroname> ------------------- Similar to #ifdef, except the lines are only parsed if the macro hasn't been defined. #else ----- Used between #ifdef .. #endif or between #ifndef .. #endif Example: #ifdef USE_UPPER_CASE text "HELLO WORLD" #else text "Hello world" #endif #undef <macroname> ------------------ Un-defines a macro. Script-file processor --------------------- Whereas the preprocessor is used when the script-file is loaded into memory, the script-file processor is used when the parser reads a line from the file in memory. Lines starting with the character ':' are executed by the script-file processor, rather than being parsed by the parser. The script-file processor recognises the following statements and keywords: :for <variable> = <expression> to <expression> :next :if <expression> :endif :print "string" :print <expression> Variables can be declared and assigned values using the following syntax: :var <variable> [,<variable>] :<variable> = <expression> :<variable> += <expression> :<variable> -= <expression> :<variable> *= <expression> :<variable> /= <expression> Variablenames have the following restrictions: * max 15 chars * must start with a letter (A..Z or a..z) or '_' * may only include letters, digits and '_' Variables must be declared (using ':var <variable>') before they can be used. The exception is the variables used for :for .. :next loops. The loop-variable is created automatically and ceases to exist when the loop has finished. Whenever you specify a value in eg. a matrix or shape-definition etc., you may use an expression instead; expressions are terminated by a space or when there are the same number of ( and ) in an expression; thus x*12+43 is legal x*12 + 43 is illegal (x*12 + 43) is legal The following functions and operators are available: + - * / sin(<expression>) cos(<expression>) tan(<expression>) log(<expression>) exp(<expression>) abs(<expression>) sqr(<expression>) rnd(<expression>) Comparisons == <= >= != < > && || The comparisions will return 1 if true or 0 if false. Notice that expressions are evaluated using floating point, but the value returned is always an integer. The variable 'frameno' always contains the number of frames defined so far; the variables 'framesizex' and 'framesizey' are set when the parser encounters a 'FrameArea { }' tag. The following example demonstrates how to use loops and expressions: #define FRAMES 4 :for i = 1 to FRAMES PlaceObject { depth i+1 id CIRCLE_ID matrix { 23000*i+4560 } // one value -> scaling } // do something here... :if i == 2 // do something here :endif :next ShowFrame { } Missing features, known bugs, etc. ================================== * not all features have been tested Creating fonts etc. =================== The directory !Flash.Tools contains a few command-line tools that may be useful. * Draw2Flash creates library-files or full script-files from Draw files * MakeFont creates library-files from an outline font * readflash deconstructs a Flash file Draw2Flash ---------- Syntax: *Draw2Flash [switches] <drawfile> <scriptfile> Switches: -v verbose -s split grouped paths -c center objects around 0,0 -full output full scriptfile -id <id> id of first objects Example: *Draw2Flash -s -c -id 400 -full $.drawfile $.script MakeFont -------- Syntax: *MakeFont [switches] <fontname> <id> Switches: -v verbose -nosave don't save anything Example: *MakeFont -v Homerton.Medium 50230 You should add the name/id of the font to the file !Flash.Library.Fonts.IDs Notice that some fonts may need manual adjustment afterwards. readflash --------- Syntax: *readflash [switches] <flashfile> Switches: -t display only tag-id/size History ======= 0.10 2000-06-04 * support for DefineSound and PlaySound * improved Draw2Flash * tidied a few things 0.09 2000-04-25 * minor cosmetic changes * improved the bezier-conversion in Draw2Flash and MakeFont 0.08 2000-04-24 * tidied the handling of the dictionary * fonttext.c now calculates and writes the no. of bits required to store a glyph-index and advance-value * now always includes a matrix in PlaceObject - the GPL player appears to require this 0.07 2000-04-21 * improved the script-processor * implemented bracket-matching in expressions 0.06 2000-04-20 * tidied a few things * fixed serious bug in shape.c * the bit-bucket is now being flushed before writing a matrix or cxform * aliases for selectfillstyle0 and selectfillstyle1 0.05 2000-04-19 * fixed a few bugs in evaluate.c and preprocess.c * aliases for DefineShape, PlaceObject, RemoveObject and BackgroundColour * cxform's are now parsed correctly 0.04 2000-04-18 * :for .. next loop extended to allow expressions * added :print to the script-processor (for script-debugging) * added -pl commandline switches (for script-debugging) * fixed bug in the parsing of 'moveby { }' * added 'moveto { }' to shape-structures * allowed RGBA values to be specifed as { R G B A } * changed 'letter' field in glyph-structure to 'char' * added more helpful error-messages 0.03 2000-04-17 * added support for buttons * added support for fonts/text (not sure if it works 100%) * script-processor added * now allows multiple line/fillstyles in a single structure * automatically calculates the bbox of shapes * objects may be placed in and removed from previous frames * tidied the code 0.02 2000-04-09 * first release