added as3/pool.c, removed as3/utils.c
[swftools.git] / doc / fileformat.sc
1 # ===========================================================================
2 #
3 # swfc(1) File format specification
4 #
5 # Warning: not all of this is actually implemented yet- if there's a
6 # "TODO" behind a command, it has yet to be integrated into swfc.
7 #
8 # ===========================================================================
9
10 # File header
11 # -----------
12
13 .flash bbox=200x200 version=6 fps=50 name="spec.swf" compress
14
15 # bbox=200x200         : set bounding box to 200x200
16 # bbox=200x200:100:100 : set bounding box to (100,100)-(300,300)
17 # bbox=autocrop        : (default) - make bbox just big enough so that nothing ever get's clipped
18 #
19 # all coordinates are in pixels, not in twips. fixed point values like 1.25, 333.40 are allowed.
20 #
21 # version=6    : generate flash mx movie
22 # fps=50       : set framerate to 50 frames/second
23 # name="..."   : save result to spec.flash. (Default: input file with extension 
24 #                                          changed to .flash, or the value of the -o command line 
25 #                                          parameter if given)
26
27 # inherit swf movies:
28 # ---------------------
29
30 .swf mymovie1 "choo1.swf"
31 .swf mymovie2 filename="choo1.swf" # long form
32 .swf mymovie3 filename=choo1.swf # long form, without quotes
33 .swf mymovie4 choo1.swf # short form, without quotes
34
35 # Notice: An embedded animation can't have a different framerate than
36 # the frame rate from the surrounding animation.
37
38 #TODO: Those files currently come from the current directory- they should come from the script directory.
39
40 # load an image:
41 # --------------
42
43 .jpeg background "panorama.jpg"
44 .jpeg background2 "panorama.jpg" quality=30% #reduces jpeg quality
45
46 .png background3 "choochoo.png" #TODO
47
48 # (you can put this directly (generating a shape), or insert it into a shape via the fill= argument
49
50 # define a texture from an image:
51 # -------------------------------
52
53 .texture text1=background scale=50% rotate=45
54
55 # define a gradient
56 # -----------------
57
58 .gradient mygradient:
59     0% red
60     50% green
61     75% aquamarine
62     100% #ffffff
63 .end
64
65 # with a hard edge:
66
67 .gradient mygradient:
68     0% red
69     50% green
70     50% red
71     75% aquamarine
72     100% #ffffff
73 .end
74
75 # with alpha:
76
77 .gradient mygradient:
78     0%   #00000000
79     50%  #0000ff40
80     75%  #0000ff80
81     100% #0000ffc0
82 .end
83
84 # define a texture from a gradient:
85 # ---------------------------------
86
87 .texture grad2=mygradient x=0 y=0 width=125 height=200 rotate=45
88
89 # Create simple objects:
90 # ----------------------
91
92 .box mybox1 width=100 height=50 color=black fill=none #unfilled rectangle (just the lines)
93 .box mybox2 width=100 height=50 color=black           #same as above
94 .box mybox3 width=100 height=50 color=black fill      #filled black rectangle
95 .box mybox4 width=100 height=50 color=red line=2 fill=blue #blue rectangle with red edges
96 .box mybox5 width=100 height=50 color=red line=2 fill=background #filled with image "background", with red edges
97
98 .circle mycircle1 r=50 color=#aa33ff fill=mygradient # filled with gradient (defined above)
99 .circle mycircle1 r=50 color=#aa33ff fill=grad2      # filled with gradient texture
100
101 # Sounds:
102 # -------
103
104 .sound sound1 "LocoStart.wav"
105
106 .frame 16
107     .play sound1 loop=1 #other arguments supported: nomultiple (don't start if already playing)
108 .frame 55
109     .stop sound1
110
111 .frame 66
112     # this starts a synchronized soundtrack at this frame position. The command
113     # expects a filename, not a sound object, as it would be duplicating the
114     # sound object otherwise, and I'd rather have that done explicitly.
115     .soundtrack "LocoStart.wav" # TODO
116
117 # Elements of the movie should be animated by various means 
118 # moving (x,y and zoom) 
119 # ---------------------
120
121 .box obj1 width=200.0 height=100.0
122
123 .frame 100
124     .put obj1 x=0 y=0 #object starts at (0,0)
125
126 .frame 140
127     .change obj1 x+=100 y=0 scale=120% # smoothly move obj1 100 pixels to the right over 40 frames,
128                                        # scaling it to 120% of it's original size
129 .frame 170
130     .jump obj1 x=200 y=200 # make object to suddenly change to 200,200 at frame 70.
131
132 .frame 190
133     .qchange obj1 x=300 y=200 # TODO # make obj1 move towards 300,200...
134 .frame 210
135     .qchange obj1 x=300 y=300 # TODO # ... and then smoothly over to 300,300 using bspline interpolation
136
137 #.frame 220   #TODO
138 #    .jump obj1 x=reset y=reset
139
140 .frame 230
141     .del obj1   #Remove object again
142
143 # morphing
144 # --------
145
146 .outline shape1:
147     #define shape 1
148 .end
149 .outline shape2:
150     #define shape 2
151 .end
152 .morphshape morphthing start=shape1 end=shape2
153 .frame 250
154     .put morphthing ratio=0%
155 .frame 270
156     .change morphthing ratio=100%
157
158 # interpolation between crude manual animation frames
159 # ---------------------------------------------------
160
161 .circle ball r=50 color=blue fill=violet
162
163 # now draw two balls, which fly around each other.
164
165 .frame 300
166 .put myball1=ball x=0 y=100 blue=0
167 .put myball2=ball x=100 y=100 red=0
168
169 .frame 310
170 # the .qchange means, "interpolate to this position and frame, using quadratic splines".
171          .qchange myball1 x=50 y=0 #TODO
172          .qchange myball2 x=50 y=100 #TODO
173
174 .frame 320
175 # We could also use coordinates relative to start position: .change myball1 x+=100 y+=0
176          .qchange myball1 x=100 y=100 #TODO
177          .qchange myball2 x=0 y=100 #TODO
178
179 .frame 330
180          .qchange myball1 x=50 y=100 #TODO
181          .qchange myball2 x=50 y=0 #TODO
182  
183 .frame 340
184 # Hmmm. This frame is the same as frame 0. How to prevent duplicating that one?
185          .qchange myball1 x=0 y=100 #TODO
186          .qchange myball2 x=100 y=100 #TODO
187
188 # color transforms (fading)
189 # -------------------------
190
191 # .put, .change, .qchange, .jump all support params which result in color transform.
192 # Everything up to the + is multiplicated, the rest summed.
193
194 .put obj1 blue=50% #(scale blue color component to 50%)
195 .change obj1 blue=128 #(same as above)
196 .change obj1 red=+25% #(shift blue color component by 25%)
197 .change obj1 red=+64 #(same as above)
198 .change obj1 green=50%+50% #(scale green color component to 50% and then shift it by 50%)
199 .change obj1 green=128+128 #(same as above)
200 .change obj1 green=-1+255 #(invert green color component)
201 .change obj1 green=2-128  #(reduce spectrum for green to the upper 50%)
202 .change obj1 luminance=50% #(fade all color components 50% to black, same as red=50% green=50% blue=50%)
203 .change obj1 alpha=50% #(make object 50% transparent)
204
205 # scaling
206 # -------
207
208 .change obj1 scale=50%   # change an object to 50% of it's size
209 .change obj1 scaley=50%  # flatten object to 50% of it's height
210 .change obj1 scaley=110% scalex=75% #(funhouse mirror!)
211
212 # rotating
213 # --------
214
215 .change obj1 rotate=45  # tilt object, counterclockwise
216
217 # shearing
218 # --------
219
220 .change obj1 shear=100%  # shear object
221
222 # sprites (a.k.a. movieClips)
223 # -------
224
225 .sprite spr1
226     .frame 1    .put ball1=ball 0 0
227     .frame 2    .change ball1 100 100
228 .end
229
230 .sprite spr2
231     .frame 1    .put ball2=ball 100 0
232     .frame 7    .change ball2 0 100
233 .end
234
235 .frame 400
236     .put spr1
237     .put spr2
238
239 # so spr1 has three frames, spr2 has seven. The whole animation loops after 21 frames.
240
241 # multi-level nesting: (sprites can be nested to any depth)
242
243 .sprite mspr1
244     .sprite mspr2
245         .sprite spr3
246         .put ball 100 0
247         .end
248     .end
249 .end
250
251 # clipping an animation inside a star-shaped sprite:
252
253 .swf mystar1 "star.swf"
254 .swf anim1 "penguins.swf"
255
256 .sprite cspr1
257     .startclip mystar1
258         .put anim1
259     .end
260 .end
261 .frame 401
262     .put cspr1 rotate=0
263 .frame 402
264     .change cspr1 rotate=360
265
266 # buttons
267 # -------
268
269 .png play "Play.png" #TODO
270 .png play_pressed "Play_pressed.png" #TODO
271 .png stoplogo "Stop.png" #TODO
272
273 .button playbutton
274     .show play as=idle
275     .show play as=area
276     .show play_pressed as=pressed
277     .show play_pressed as=hover
278 .end
279
280 .button playbutton2
281     .show play as=idle
282     .on_press inside
283     .on_release inside
284     .on_release outside
285     .on_move_in pressed
286     .on_move_out pressed
287     .on_move_in
288     .on_move_out
289     .on_key "a":
290         # actionscript...
291     .end
292 .end
293
294 .button mybutton
295     .show play as=idle
296     .show obj1 x=300 y=400 scale=110% pivot=center 
297          as=pressed
298 .end
299
300 .box blueshape 10 10
301 .box greenshape 10 10
302 .box whiteshape 10 10
303 .box activearea 10 10
304 .box emtpyshape 10 10
305 .box window1 10 10
306 # button which is blue, get's green when the mouse hovers over it, and
307 # white when it is pressed:
308 .button b1
309     .show blueshape as=idle
310     .show greenshape as=hower
311     .show whiteshape as=press
312 .end
313
314 # button where the button position is not identical to the active area:
315 .button b2
316     .show activearea as=area
317     .show blueshape as=idle
318     .show greenshape as=hower
319     .show whiteshape as=press
320 .end
321
322 # (if area is not set, it's the same as shape)
323
324 # the above put into use: pop up a window if the mouse cursor enters a certain
325 # area:
326 .button b3
327     .show activearea as=area
328     .show emtpyshape as=idle
329     .show window1 as=hower
330 .end
331
332 # fonts
333 # -----
334 .font font1 "myfont.swf"
335 .font font1 "myfont.ttf"
336 .font font1 "myfont.pfa"
337
338 # text fields
339 # -----------
340 .text mytext1 font=font1 text="I am a happy little scroll message" color=blue size=100%
341
342 # edittext
343 # --------
344 #(field where the flash animation can get input from the user)
345
346 .font helvetica "helvetica-bold.swf"
347 .edittext edittext1 text="Type something here" color=blue maxlength=200 font=helvetica size=24 width=320 height=200 #TODO
348 # width/height: dimensions of the box
349 # text: The text which appears initally in the box, and can be overwritten by the user
350 # maxlength: max. length of the text the user can type
351 # color/font/size: Font appeareance
352 # variable: Name of the actionscript variable the text is stored in
353 # The following boolean options are also supported:
354 # password (show input only as stars), wordwrap, multiline, html, noselect, readonly
355
356 # actionscript
357 # ------------
358
359 .action:
360     _root.play();
361 .end
362
363 # depth control
364 # -------------------
365 # .put, .change, .qchange, .jump, .startclip take before and after parameters,
366 # which can be used to specify the depth of an object
367
368 .put o1=obj1 #TODO
369 .put o2=obj1 below=o1 x=50 #TODO
370 .frame
371 .change o1 #TODO
372 .change o2 above=o1 x=50 #TODO
373
374 # newline conventions
375 # -------------------
376
377 # All Newlines are treated as normal whitespace. Therefore, splitting
378 # commands over several lines, like
379 .put obj2=obj1 x=300
380              y=300
381              red=100%
382              green=50%
383              blue=50%
384 # is allowed.
385
386 # Furthermore, having more than one command in one line is also possible:
387
388 .frame 600  .change obj1 x+=700  .change obj2 x+=300
389 .frame 601  .change obj1 x+=500  .change obj2 x+=500
390 .frame 602  .change obj1 x+=300  .change obj2 x+=700
391
392 .end # end of first file
393