object extension is now determined by configure. ($(O))
[swftools.git] / doc / swfc.xml
1 <?xml version='1.0'?>
2 <guide>
3     
4 <title>SWFC Manual</title>
5
6 <abstract>
7 swfc is a tool for generating flash files. You can write small simple scripts
8 and then have them compiled to SWF Flash Animations.
9 </abstract>
10
11
12 <!--
13
14 This comment aims to give a short overview over the tags defined in guide.xslt.
15 Most are like html.
16
17 Markups and Highlights:
18
19     <i>italic</i>
20     <b>bold</b>
21     <ul>Underline</ul>
22
23     <f>filename or pathname</f>
24     <c>variable name, command</c> ("c" stands for "code")
25
26 Paragraphs:
27
28     <p>
29     Paragraph
30     </p>
31
32 Line breaking:
33
34     <br/>
35
36 Links:
37
38     <a>http://www.quiss.org</a> OR
39     <a href=http://www.quiss.org>Quiss</a>
40
41 Shell scripts, commands to execute:
42
43     <shell>tail /var/log/messages</shell>
44
45 Code:
46     
47     <code lang="sc">   (The lang= is optional)
48         .flash
49             .box b1 100 100
50         .end
51     </code>
52
53 Tables:
54
55     <table>
56     <tr><td>Apples</td><td>Pears</td></tr>
57     <tr><td>3</td><td>4</td></tr>
58     </table>
59
60 Boxes:
61     <note>
62     Something interesting
63     </note>
64
65     <impo>
66     Something important
67     </impo>
68     
69     <warn>
70     Something to be careful about
71     </warn>
72
73 -->
74
75 <chapter title="Basic usage of swfc">
76
77  <section><title>Calling swfc</title>
78
79  <p>
80
81   swfc is command line based. You call it via
82
83   <shell>$ swfc file.sc</shell>
84
85   The filename of what is generated depends on the filename of the script (<f>file.sc</f>),
86   the filename given inside the script, and the optional <c>-o</c> passed to swfc.
87
88  </p>
89
90  <note>
91   Though swfc is a command-line utility, there also exists a nice graphical
92   frontend for it, called Swifty.
93  </note>
94
95  </section>
96
97  <section><title>A simple swfc example</title>
98
99   <p>
100    Let's create simple SWF file, shall we?
101    The following script creates a red box with a yellow border. On the right side you
102    see the script used, on the left side the swf file that is generated.
103   </p>
104
105   <code lang="swfc">
106 .flash name="box.swf"
107     .box b1 100 100 color=yellow fill=red
108     .put b1 pin=center scale=0%
109     .frame 100
110     .change b1 pin=center scale=100%
111     .frame 200
112     .change b1 pin=center scale=0%
113 .end
114   </code>
115
116   <p> 
117   The <c>.box</c> command creates the box. Every object that is created must also be explicitly
118   put into the scene using <c>.put</c> to become visible.
119   </p> 
120   <p>
121   Change, on the other hand, modifies an already existing object.
122   It works gradually: In the example above, the change happens over 100 frames.
123   If you want to change an object suddently from one frame to the next, you
124   would use the <c>.jump</c> command.
125   </p>
126
127  </section>
128  
129  <section><title>Color transforms</title>
130
131 <p>
132 You can define a number of parameters in the <c>.put</c>, <c>.change</c> and <c>.jump</c>
133 tags. Among those are the color transform parameters <c>red</c>, <c>green</c>,
134 <c>blue</c> and <c>alpha</c>.
135 Furthermore, for convenience, there's also <c>luminance</c>, which sets <c>red</c>, <c>green</c> and
136 <c>blue</c> in one go.
137 </p>
138 <p>
139 Each one of these consists of two parts: The multiplicator and the shift.
140 The syntax is
141 <c> &#177;&lt;multiplicator&gt;&#177;&lt;shift&gt; </c>.
142 So, for example, to make an object 50% brighter, you would use
143 <c>luminance=+128</c>. Notice that all color components inside the transformed object in the range 128-255
144 will be mapped to 255 with this. To map 0 to 128, 255 to 255, but 128 to 192, you would
145 use <c>luminance=0.5+128</c>.
146 </p>
147 <p>
148 You can also specify negative values for both <c>&lt;mutliplicator&gt;</c> and <c>&lt;shift&gt;</c>.
149 This makes it e.g. possible to invert an object: <c>luminance=-1+255</c>.
150 </p>
151 <p>
152 The following example demonstrates a few of the possible transforms:
153 </p>
154
155
156   <code lang="swfc">
157 .flash name="cxform.swf" version=5 fps=25
158     
159     .jpeg s1 "photo.jpeg" quality=80%
160
161     .put s1 x=50 y=50 scalex=110 scaley=110
162     .frame 50
163     .change s1 x=0 y=0 scalex=210 scaley=210 red=-1+255 green=-1+255 blue=-1+255 #invert
164     .frame 100
165     .change s1 x=100 y=50 scalex=110 scaley=110 red=0 green=+0 blue=+0 #remove red
166     .frame 150
167     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=2 blue=-1+255 #amplify green, invert blue
168     .frame 200
169     .change s1 x=50 y=100 scalex=110 scaley=110 red=2-128 green=-2+255 blue=+0.7+40 #alien glow
170     .frame 250
171     .change s1 x=0 y=0 scalex=210 scaley=210 red=8-1024 green=8-1024 blue=8-1024 #palette reduce
172     .frame 300
173     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=+0 blue=+0 #back to normal
174     .frame 350
175     .change s1 x=105 y=105 scalex=0 scaley=0 luminance=0 #fadeout
176 .end
177   </code>
178
179 A very useful fact is also that you can color transform the alpha component.
180 So to fade any object into the background, you would simply transform it's
181 alpha color: E.g. <c>alpha=64</c> would make the object 75% transparent.
182 This is used in an example further below.
183  </section>
184  
185
186 </chapter>
187
188 <chapter title="Fonts">
189
190 <section>
191
192 swfc has font support. That means you can also insert texts into
193 your animations.
194 The easiest way to load a font is to do something like
195 <c>
196     .font Arial filename="Arial.ttf"
197 </c>
198 .
199 You now have a font named <c>Arial</c> to play with.
200 For example, for the obligatory hello world program:
201
202   <code lang="swfc">
203 .flash name="helloworld.swf"
204     
205     .font Arial filename="Arial.ttf"
206     .text helloworld font=Arial text="Hello World!"
207     .put helloworld
208 .end
209   </code>
210
211 <note>
212 The text argument expects UTF-8 strings. So if you want to
213 pass any special characters (umlauts, digraphs etc.), they have to
214 be UTF-8 encoded.
215 </note>
216
217 Besides TrueType fonts, swfc also supports native SWF fonts.
218 If you have a SWF with a font you would like to use, do a 
219 <shell>
220     swfextract file.swf
221 </shell>
222 Then write down the font ID of the font, and do a
223 <shell>
224     swfextract -f &lt;fontid&gt; file.swf -o myfont.swf
225 </shell>
226 .
227 <p>
228 This will give you a file named myfont.swf which you can
229 also use in the <c>filename</c> parameter of <c>.font</c>.
230 </p>
231
232 <p>
233 Furthermore, you can convert TTF and Type1
234 fonts into SWF using <c>font2swf</c>:
235 <shell>
236     font2swf Arial.ttf -o Arial.swf
237 </shell>
238 The nice advantage of this is that you can play
239 Arial.swf in the flash player and see what the
240 font looks like.
241 (Also, loading a font in SWF format is slighly
242 faster than from a TTF file, as with TTFs spline
243 conversion has to take place).
244 </p>
245
246 </section>
247 <section>
248 <p>
249 So much for the basics. Now let's go to the more advanced
250 functionality around fonts.
251 </p>
252
253 <p>
254 Apart from being able to define text in your swfc files,
255 you can also define text <c>outlines</c>. 
256 Those are not real characters but rather abstract vector 
257 objects which you can use in other commands.
258 </p>
259
260 <code lang="swfc">
261 .flash name="fontoutline.swf"
262     .font Arial "Arial.swf"
263     .textshape helloworld font=Arial size=200% text="Hello World"
264     .filled filled_helloworld outline=helloworld fill=blue line=3 color=green
265     .put filled_helloworld
266 .end
267 </code>
268
269 Here, <c>.textshape helloworld</c> defines an outline named "helloworld",
270 which is then used to construct a filled outline named filled_helloworld.
271
272 To make this a little more interesting, let's fill with a gradient instead
273 of a plain color:
274
275 <code lang="swfc">
276 .flash name="fontgradient.swf"
277     .font Arial "Arial.swf"
278     .textshape helloworld font=Arial text="SHADE"
279     
280     .gradient whitefade:
281         0% black
282         50% #505050
283         100% yellow
284     .end
285
286     .filled filled_helloworld outline=helloworld fill=whitefade line=1 color=#2c2c2c
287     .put filled_helloworld scale=200%
288 .end
289 </code>
290
291 While at it, you can also fill with an image:
292
293 <code lang="swfc">
294 .flash name="fontimage.swf"
295     .font courier "Courier.swf"
296     .jpeg beach "beach.jpg"
297     .textshape text font=courier text="HOLIDAY"
298     
299     .filled filled_text outline=text fill=beach line=1 color=#2c2c2c
300     .put filled_text scale=200%
301 .end
302 </code>
303
304 But let's get back to normal <c>.text</c> characters.
305 The following demonstrates that you can treat objects defined
306 with <c>.text</c> like normal shapes, i.e., scale them, move them, and use
307 them for clipping:
308
309   <code lang="swfc">
310 .flash name="text5.swf"
311 .font courier "Courier.swf"
312 .text hithere text="HELLO" font=courier size=200%
313 .jpeg scenery "scenery.jpg"
314
315 .frame 0
316     .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
317         .put scenery scale=50%
318     .end
319 .frame 100
320      .change hithere rotate+=360 pin=center scale=100%
321
322 .end
323   </code>
324
325 <p>
326 The last two examples look similar, but their underlying structure
327 is different:  The first is a shape object filled with
328 image data (that is, a texture), while the second uses a normal
329 text object to clip an rectangular image. 
330 </p>
331
332 <p>
333 Also, <c>.text</c> takes a color attribute (that's actually
334 the poor man's version of the more advanced filling options
335 that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
336 which is used here together with the alpha parameter of <c>.change</c>:
337 </p>
338
339   <code lang="swfc">
340 .flash name="text6.swf"
341 .font times "Times.swf"
342 .text hello text="HELLO" font=times size=100% color=blue
343 .text world text="WORLD" font=times size=100% color=red
344
345 .frame 0
346         .put hello pin=center x=50 y=50 
347         .put world pin=center x=50 y=50 alpha=25%
348 .frame 200
349      .change hello rotate+=360 pin=center alpha=25% 
350      .change world rotate-=360 pin=center alpha=100% 
351 .end
352   </code>
353  
354  </section>
355
356 <section title="Edittext">
357
358 A special type of text in SWF is the <c>edittext</c>, which
359 can be modified by the viewer. It's content can also be queried
360 and set from ActionScript (see below).
361 You can generate this type of text with the <c>.edittext</c> command:
362
363 <code lang="swfc">
364 .flash name="edittext.swf" bbox=210x110
365     .font Arial "Arial.swf"
366     .edittext myedittext font=Arial size=20% 
367                          width=200 height=100 
368                          color=blue border multiline wordwrap
369                          text="Edit me!\nClick with your mouse on this text to edit it."
370     .put myedittext x=3 y=3
371 .end
372 </code>
373
374 </section>
375 </chapter>
376
377 <chapter title="Shapes">
378
379 <section title="Creating Outlines">
380
381 In the previous chapter, we learned how to create a text outline
382 using <c>.textshape</c>. The other way to create outlines is to
383 use the .outline command:
384
385 <code lang="swfc">
386 .flash name="house.swf"
387
388     .outline house_outline:
389         M 36.99 29.93 L 15.52 51.39 L 20.44 51.39 L 20.44 81.91 
390                       L 39.73 81.91 L 39.73 62.33 L 48.36 62.33
391                       L 48.36 81.91 L 53.84 81.91 L 53.84 51.39
392                       L 58.45 51.39 L 36.99 29.93
393         M 28.79 53.70 L 34.55 53.70 L 34.55 60.60 L 28.79 60.60
394                       L 28.79 53.70
395     .end
396     .filled house outline=house_outline fill=grey color=grey
397     .put house
398 .end
399 </code>
400
401 The syntax of the paths inside the <c>.outline</c> command is the same as in svg.
402 That means you can use the svg editor of your choice (e.g.: <a href="http://inkscape.sourceforge.net">inkscape</a>)
403 to create these outlines. You then need to extract them out of the .xml/.svg file.
404 They are inside the "d" attribute of the "path" tag:
405
406 <code lang="xml">
407 ...
408   &lt;path
409      style="fill:#0000ff;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;"
410      d="M 369.90625 299.31250 L 155.21875 513.96875 L 204.40625 513.96875 L 204.40625 819.15625 L 397.31250 819.15625 L 397.31250 623.37500 L 483.68750 623.37500 L 483.68750 819.15625 L 538.40625 819.15625 L 538.40625 513.96875 L 584.56250 513.96875 L 369.90625 299.31250 z M 287.90625 537.00000 L 345.50000 537.00000 L 345.50000 606.09375 L 287.90625 606.09375 L 287.90625 537.00000 z "
411      id="rect908" /&gt;
412 ...
413 </code>
414
415 </section>
416
417 <section title="Filling Outlines">
418
419 Outlines can be filled with gradients, bitmaps etc., just like
420 seen previously with <c>.textshape</c>:
421
422 <code lang="swfc">
423 .flash name="gradients.swf"
424
425     .outline star:
426         M 521,640 C 502,678 370,546 328,554 C 270,566 152,731 93,722 
427                   C 51,716 147,549 127,512 C 98,460 -107,400 -117,341 
428                   C -124,299 63,339 93,308 C 133,265 127,50 180,23 
429                   C 218,3 238,195 276,213 C 330,238 532,166 575,208 
430                   C 605,238 429,316 424,358 C 416,417 547,587 521,640 
431     .end
432
433     .gradient rainbow:
434         0% blue
435         25% green
436         50% yellow
437         75% orange
438         100% red
439     .end
440     
441     .gradient fire radial:
442         0% white
443         50% yellow
444         100% red
445     .end
446     
447     .gradient horizon:
448         0% cyan
449         49% blue
450         50% green
451         100% peru
452     .end
453
454     .gradient transparent:
455         0% #ff000000
456         100% #ff0000ff
457     .end
458
459     .box scenery fill=horizon width=200 height=200
460     .box bar fill=transparent width=240 height=20
461     .filled star1 outline=star fill=rainbow line=1
462     .filled star2 outline=star fill=fire    line=1
463     
464     .put scenery rotate=90% 
465     .put star1 scale=10% x=-70
466     .put star2 scale=10% x=-180 y=110
467     .put bar x=-180 y=10 rotate=45
468 .end
469 </code>
470
471 <!-- TODO: bitmap filling -->
472
473 </section>
474
475 </chapter>
476
477 <chapter title="ActionScript">
478
479 <section>
480     <c>swfc</c> has Actionscript support.
481     For normal actionscript, which is executed once a given frame
482     is reached, just open an <c>.action</c> block, and write
483     the ActionScript into the block:
484   
485 <code lang="swfc">
486 .flash name="action.swf" bbox=300x300 fps=50
487
488 .box mybox color=blue fill=green width=100 height=100
489 .put mybox
490
491 .frame 0
492     .action:
493         _root.angle += 0.05;
494         mybox._x = 100*Math.cos(_root.angle)+100;
495         mybox._y = 100*Math.sin(_root.angle)+100;
496     .end
497 .frame 1
498     .action:
499         gotoFrame(0);
500         Play();
501     .end
502 .frame 2
503 .end
504 </code>
505
506 For much more interesting ActionScript examples, see
507 Laurent Lalanne's 
508 <a href="http://technoargia.free.fr/swftools/examples/flash_eyes/flash_eyes.html">Flash Eyes</a>
509 or the 
510 <a href="http://melusine.eu.org/syracuse/flash/20040429/fabrique/">source</a>
511 of Jean-Michel Sarlat's
512 <a href="http://melusine.eu.org/syracuse/flash/20040429/">Mandelbrot explorer</a>.
513 or
514 <a href="http://www.goldenxp.com/repo/swfr/index.htm">Sunder Iyer's swfc pages</a>.
515
516 </section>
517
518
519 </chapter>
520
521 <chapter title="Buttons">
522 <p>
523 Actionscript comes in handy when dealing with SWF Buttons.
524 </p>
525 <p>
526 A button defines, in SWF context, an object sensitive to mouse movement,
527 mouse buttons, and key presses.
528 </p>
529 <p>
530 The following is a trivial example: Four objects which change their shape
531 once the cursor is over it.
532 <code lang="swfc">
533 .flash name="button1.swf" fps=50
534
535 .box box1 color=white fill=#336633 width=50 height=50 
536 .box box2 color=white fill=#99cc99 width=100 height=100
537 .button mybutton1
538     .show box1 as=shape x=25 y=25
539     .show box2 as=hover x=12.5 y=12.5
540 .end
541
542 .frame 0
543     .put b1=mybutton1
544     .put b2=mybutton1 x=100 red=+255
545     .put b3=mybutton1 y=100 green=+255
546     .put b4=mybutton1 x=100 y=100 blue=+255
547 .end
548 </code>
549 </p>
550
551 <p>
552 The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
553 very similar to <c>.put</c>. 
554 For every shape a button uses, you can specify the position, color transform, scaling,
555 rotation etc. just like with <c>.put</c>.
556 </p>
557 <p>
558 The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
559 with that you tell the button when to display that specific shape.
560 There are four allowed parameters to <c>as</c>:
561 <ul>
562     <li><b>idle</b> The shape to display when the button is idle, that is, the
563                     mouse is somewhere else, and not over the button.
564     </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
565                      What exactly is <i>"inside"</i> is defined by <b>area</b>:
566     </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
567                      bounding polygon) for the button. A button considers itself
568                      active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
569                      shape) if the mouse is inside this area. Also, mouse button clicks
570                      have to be in this area for this button.
571     </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
572                        is displayed as long as the mouse button is down.
573     </li>
574 </ul>
575 </p>
576
577 <!-- TODO: button actionscript -->
578
579 <!--
580 <section><title>Another button example: tooltips</title>
581
582 Due to the fact that button shapes can be put <i>anywhere</i> especially
583 outside the active area, it's easy to generate tooltips or subtitles.
584
585 <code lang="swfc">
586 .flash name="tooltips.swf" fps=50
587
588 .jpeg pic fence.jpg
589 .put pic
590
591 .font arial Arial.ttf
592 .edittext tooltip_fence text="fence" readonly color=green font=arial width=200 height=50 size=20%
593 .edittext tooltip_wheel text="wheel" readonly color=green font=arial width=200 height=50 size=20%
594 .edittext tooltip_tree text="tree" readonly color=green font=arial width=200 height=50 size=20%
595 .edittext tooltip_mountain text="mountain" readonly color=green font=arial width=200 height=50 size=20%
596
597 .box box1 fill=red width=1 height=1
598 .button mybutton1
599     .show box1 as=area x=0 y=0
600     .show tooltip_fence as=hover x=25 y=25 scalex=100 scaley=100 alpha=50%
601     .show tooltip_fence as=idle x=25 y=25 scalex=100 scaley=100 alpha=50%
602 .end
603
604 .frame 0
605     .put mybutton1
606 .end
607 </code>
608
609 </section>
610 -->
611
612 </chapter>
613
614 </guide>