moved gfxfont creation from GFXOutputDev to InfoOutputDev
[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  </section>
91
92  <section><title>A simple swfc example</title>
93
94   <p>
95    Let's create a simple SWF file, shall we?
96    The following script creates a red box with a yellow border. On the right side you
97    see the script used, on the left side the swf file that is generated.
98   </p>
99
100   <code lang="swfc">
101 .flash filename="box.swf"
102     .box b1 100 100 color=yellow fill=red
103     .put b1 pin=center scale=0%
104     .frame 100
105     .change b1 pin=center scale=100%
106     .frame 200
107     .change b1 pin=center scale=0%
108 .end
109   </code>
110
111   <p> 
112   The <c>.box</c> command creates the box. Every object that is created must also be explicitly
113   put into the scene using <c>.put</c> to become visible.
114   </p> 
115   <p>
116   Change, on the other hand, modifies an already existing object.
117   It works gradually: In the example above, the change happens over 100 frames.
118   If you want to change an object suddently from one frame to the next, you
119   would use the <c>.jump</c> command.
120   </p>
121
122  </section>
123  
124  <section><title>Color transforms</title>
125
126 <p>
127 You can define a number of parameters in the <c>.put</c>, <c>.change</c> and <c>.jump</c>
128 tags. Among those are the color transform parameters <c>red</c>, <c>green</c>,
129 <c>blue</c> and <c>alpha</c>.
130 Furthermore, for convenience, there's also <c>luminance</c>, which sets <c>red</c>, <c>green</c> and
131 <c>blue</c> in one go.
132 </p>
133 <p>
134 Each one of these consists of two parts: The multiplicator and the shift.
135 The syntax is
136 <c> &#177;&lt;multiplicator&gt;&#177;&lt;shift&gt; </c>.
137 So, for example, to make an object 50% brighter, you would use
138 <c>luminance=+128</c>. Notice that all color components inside the transformed object in the range 128-255
139 will be mapped to 255 with this. To map 0 to 128, 255 to 255, but 128 to 192, you would
140 use <c>luminance=0.5+128</c>.
141 </p>
142 <p>
143 You can also specify negative values for both <c>&lt;mutliplicator&gt;</c> and <c>&lt;shift&gt;</c>.
144 This makes it e.g. possible to invert an object: <c>luminance=-1+255</c>.
145 </p>
146 <p>
147 The following example demonstrates a few of the possible transforms:
148 </p>
149
150
151   <code lang="swfc">
152 .flash filename="cxform.swf" version=5 fps=25
153     
154     .jpeg s1 "photo.jpeg" quality=80%
155
156     .put s1 x=50 y=50 scalex=110 scaley=110
157     .frame 50
158     .change s1 x=0 y=0 scalex=210 scaley=210 red=-1+255 green=-1+255 blue=-1+255 #invert
159     .frame 100
160     .change s1 x=100 y=50 scalex=110 scaley=110 red=0 green=+0 blue=+0 #remove red
161     .frame 150
162     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=2 blue=-1+255 #amplify green, invert blue
163     .frame 200
164     .change s1 x=50 y=100 scalex=110 scaley=110 red=2-128 green=-2+255 blue=+0.7+40 #alien glow
165     .frame 250
166     .change s1 x=0 y=0 scalex=210 scaley=210 red=8-1024 green=8-1024 blue=8-1024 #palette reduce
167     .frame 300
168     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=+0 blue=+0 #back to normal
169     .frame 350
170     .change s1 x=105 y=105 scalex=0 scaley=0 luminance=0 #fadeout
171 .end
172   </code>
173
174 A very useful fact is also that you can color transform the alpha component.
175 So to fade any object into the background, you would simply transform it's
176 alpha color: E.g. <c>alpha=64</c> would make the object 75% transparent.
177 This is used in an example further below.
178  </section>
179  
180
181 </chapter>
182
183 <chapter title="Fonts">
184
185 <section>
186
187 swfc has font support. That means you can also insert texts into
188 your animations.
189 The easiest way to load a font is to do something like
190 <c>
191     .font Arial filename="Arial.ttf"
192 </c>
193 .
194 You now have a font named <c>Arial</c> to play with.
195 For example, for the obligatory hello world program:
196
197   <code lang="swfc">
198 .flash filename="helloworld.swf"
199     
200     .font Arial filename="Arial.ttf"
201     .text helloworld font=Arial text="Hello World!"
202     .put helloworld
203 .end
204   </code>
205
206 <note>
207 The text argument expects UTF-8 strings. So if you want to
208 pass any special characters (umlauts, digraphs etc.), they have to
209 be UTF-8 encoded.
210 </note>
211
212 Besides TrueType fonts, swfc also supports native SWF fonts.
213 If you have a SWF with a font you would like to use, do a 
214 <shell>
215     swfextract file.swf
216 </shell>
217 Then write down the font ID of the font, and do a
218 <shell>
219     swfextract -f &lt;fontid&gt; file.swf -o myfont.swf
220 </shell>
221 .
222 <p>
223 This will give you a file named myfont.swf which you can
224 also use in the <c>filename</c> parameter of <c>.font</c>.
225 </p>
226
227 <p>
228 Furthermore, you can convert TTF and Type1
229 fonts into SWF using <c>font2swf</c>:
230 <shell>
231     font2swf Arial.ttf -o Arial.swf
232 </shell>
233 The nice advantage of this is that you can play
234 Arial.swf in the flash player and see what the
235 font looks like.
236 (Also, loading a font in SWF format is slighly
237 faster than from a TTF file, as with TTFs spline
238 conversion has to take place).
239 </p>
240
241 </section>
242 <section>
243 <p>
244 So much for the basics. Now let's go to the more advanced
245 functionality around fonts.
246 </p>
247
248 <p>
249 Apart from being able to define text in your swfc files,
250 you can also define text <c>outlines</c>. 
251 Those are not real characters but rather abstract vector 
252 objects which you can use in other commands.
253 </p>
254
255 <code lang="swfc">
256 .flash filename="fontoutline.swf"
257     .font Arial "Arial.swf"
258     .textshape helloworld font=Arial size=200% text="Hello World"
259     .filled filled_helloworld outline=helloworld fill=blue line=3 color=green
260     .put filled_helloworld
261 .end
262 </code>
263
264 Here, <c>.textshape helloworld</c> defines an outline named "helloworld",
265 which is then used to construct a filled outline named filled_helloworld.
266
267 To make this a little more interesting, let's fill with a gradient instead
268 of a plain color:
269
270 <code lang="swfc">
271 .flash filename="fontgradient.swf"
272     .font Arial "Arial.swf"
273     .textshape helloworld font=Arial text="SHADE"
274     
275     .gradient whitefade:
276         0% black
277         50% #505050
278         100% yellow
279     .end
280
281     .filled filled_helloworld outline=helloworld fill=whitefade line=1 color=#2c2c2c
282     .put filled_helloworld scale=200%
283 .end
284 </code>
285
286 While at it, you can also fill with an image:
287
288 <code lang="swfc">
289 .flash filename="fontimage.swf"
290     .font courier "Courier.swf"
291     .jpeg beach "beach.jpg"
292     .textshape text font=courier text="HOLIDAY"
293     
294     .filled filled_text outline=text fill=beach line=1 color=#2c2c2c
295     .put filled_text scale=200%
296 .end
297 </code>
298
299 But let's get back to normal <c>.text</c> characters.
300 The following demonstrates that you can treat objects defined
301 with <c>.text</c> like normal shapes, i.e., scale them, move them, and use
302 them for clipping:
303
304   <code lang="swfc">
305 .flash filename="text5.swf"
306 .font courier "Courier.swf"
307 .text hithere text="HELLO" font=courier size=200%
308 .jpeg scenery "scenery.jpg"
309
310 .frame 1
311     .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
312         .put scenery scale=50%
313     .end
314 .frame 100
315      .change hithere rotate+=360 pin=center scale=100%
316
317 .end
318   </code>
319
320 <p>
321 The last two examples look similar, but their underlying structure
322 is different:  The first is a shape object filled with
323 image data (that is, a texture), while the second uses a normal
324 text object to clip an rectangular image. (More about clipping in
325 the next section)
326 </p>
327
328 <p>
329 Also, <c>.text</c> takes a color attribute (that's actually
330 the poor man's version of the more advanced filling options
331 that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
332 which is used here together with the alpha parameter of <c>.change</c>:
333 </p>
334
335   <code lang="swfc">
336 .flash filename="text6.swf"
337 .font times "Times.swf"
338 .text hello text="HELLO" font=times size=200% color=blue
339 .text world text="WORLD" font=times size=200% color=red
340
341 .frame 1
342         .put hello pin=center x=50 y=50 
343         .put world pin=center x=50 y=50 alpha=25%
344 .frame 200
345      .change hello rotate+=360 pin=center alpha=25% 
346      .change world rotate-=360 pin=center alpha=100% 
347 .end
348   </code>
349  
350  </section>
351
352 <section title="Clipping">
353
354 Another example for clipping against text:
355
356 <code lang="swfc">
357 .flash filename="textclip.swf" bbox=400x120 background=black version=6
358 .font times "Times.swf"
359 .textshape helloworld text="HELLO WORLD" font=times size=300%
360 .filled helloworld1 outline=helloworld fill=blue line=0
361 .filled helloworld2 outline=helloworld fill=green line=0
362
363 .frame 1
364 .put h3=helloworld1 y=100
365 .startclip h1=helloworld1 y=100
366     .put h2=helloworld2 y=100
367 .end
368
369 .frame 1000
370 .change h1 x=-1000
371 .change h2 x=-500
372 .change h3 x=-1000
373 .end
374 </code>
375  
376 </section>
377
378 <section title="Edittext">
379
380 A special type of text in SWF is the <c>edittext</c>, which
381 can be modified by the viewer. It's content can also be queried
382 and set from ActionScript (see below).
383 You can generate this type of text with the <c>.edittext</c> command:
384
385 <code lang="swfc">
386 .flash filename="edittext.swf" bbox=410x210
387     .font Arial "Arial.swf"
388     .edittext myedittext font=Arial size=50% 
389                          width=400 height=200 
390                          color=blue border multiline wordwrap
391                          text="Edit me!\nClick with your mouse on this text to edit it."
392     .put myedittext x=3 y=3
393 .end
394 </code>
395
396 </section>
397 </chapter>
398
399 <chapter title="Shapes">
400
401 <section title="Creating Outlines">
402
403 In the previous chapter, we learned how to create a text outline
404 using <c>.textshape</c>. The other way to create outlines is to
405 use the .outline command:
406
407 <code lang="swfc">
408 .flash filename="house.swf"
409
410     .outline house_outline:
411         M 36.99 29.93 L 15.52 51.39 L 20.44 51.39 L 20.44 81.91 
412                       L 39.73 81.91 L 39.73 62.33 L 48.36 62.33
413                       L 48.36 81.91 L 53.84 81.91 L 53.84 51.39
414                       L 58.45 51.39 L 36.99 29.93
415         M 28.79 53.70 L 34.55 53.70 L 34.55 60.60 L 28.79 60.60
416                       L 28.79 53.70
417     .end
418     .filled house outline=house_outline fill=grey color=grey
419     .put house
420 .end
421 </code>
422
423 The syntax of the paths inside the <c>.outline</c> command is the same as in svg.
424 That means you can use the svg editor of your choice (e.g.: <a href="http://inkscape.sourceforge.net">inkscape</a>)
425 to create these outlines. You then need to extract them out of the .xml/.svg file.
426 They are inside the "d" attribute of the "path" tag:
427
428 <code lang="xml">
429 ...
430   &lt;path
431      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;"
432      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 "
433      id="rect908" /&gt;
434 ...
435 </code>
436
437 </section>
438
439 <section title="Filling Outlines">
440
441 Outlines can be filled with gradients, bitmaps etc., just like
442 seen previously with <c>.textshape</c>:
443
444 <code lang="swfc">
445 .flash filename="gradients.swf"
446
447     .outline star:
448         M 521,640 C 502,678 370,546 328,554 C 270,566 152,731 93,722 
449                   C 51,716 147,549 127,512 C 98,460 -107,400 -117,341 
450                   C -124,299 63,339 93,308 C 133,265 127,50 180,23 
451                   C 218,3 238,195 276,213 C 330,238 532,166 575,208 
452                   C 605,238 429,316 424,358 C 416,417 547,587 521,640 
453     .end
454
455     .gradient rainbow:
456         0% blue
457         25% green
458         50% yellow
459         75% orange
460         100% red
461     .end
462     
463     .gradient fire radial:
464         0% white
465         50% yellow
466         100% red
467     .end
468     
469     .gradient horizon:
470         0% cyan
471         49% blue
472         50% green
473         100% peru
474     .end
475
476     .gradient transparent:
477         0% #ff000000
478         100% #ff0000ff
479     .end
480
481     .box scenery fill=horizon width=200 height=200
482     .box bar fill=transparent width=240 height=20
483     .filled star1 outline=star fill=rainbow line=1
484     .filled star2 outline=star fill=fire    line=1
485     
486     .put scenery rotate=90% 
487     .put star1 scale=10% x=-70
488     .put star2 scale=10% x=-180 y=110
489     .put bar x=-180 y=10 rotate=45
490 .end
491 </code>
492
493 <!-- TODO: bitmap filling -->
494
495 </section>
496
497 <section title="Some more words about gradients">
498
499 <p>
500 The previous example demonstrated how to fill an outline with
501 a gradient.
502 </p>
503
504 <p>
505 There are two types of gradients: radial and linear. radial gradients
506 have a center point and a radius (and are immune to rotations), and
507 linear gradients have a start point and a width (or height) and can
508 be rotated.
509 </p>
510
511 gradients can be freely positioned inside the object
512 you want to fill, by passing the <c>x</c>, <c>y</c> and <c>width</c> and <c>height</c> (or <c>r</c>) parameters
513 to <c>.gradient</c>.
514
515 <code lang="swfc">
516 .flash filename="gradients2.swf"
517
518     .outline o:
519         moveTo -50,-50
520
521         lineTo 0,-45
522         lineTo 50,-50
523
524         lineTo 45,0
525         lineTo 50,50
526
527         lineTo 0,45
528         lineTo -50,50
529
530         lineTo -45,0
531         lineTo -50,-50
532     .end
533
534     .gradient horizon1 radial x=-50 y=-50 r=100:
535         0% cyan
536         49% blue
537         50% green
538         100% cyan
539     .end
540     
541     .gradient horizon2 radial x=0 y=0 r=50:
542         0% cyan
543         49% blue
544         50% green
545         100% cyan
546     .end
547
548     .filled o1 outline=o fill=horizon1 line=0
549     .filled o2 outline=o fill=horizon2 line=0
550
551     .put o1 x=50 y=50
552     .put o2 x=150 y=50
553
554 .end
555 </code>
556
557 If you want to use a given gradient several times
558 with different <c>x</c> and <c>y</c> values, you can also first
559 define the gradient itself, and then position it with .texture:
560
561 <code lang="swfc">
562 .flash filename="gradients3.swf"
563
564     # same outline as above, only in more terse notation
565     .outline o:
566         M -50,-50
567         L 0,-45 L 50,-50
568         L 45,0  L 50,50
569         L 0,45  L -50,50
570         L -45,0 L -50,-50
571     .end
572
573     .gradient horizon radial:
574         0% cyan
575         50% blue
576         50% green
577         100% cyan
578     .end
579     
580     .texture horizon1=horizon x=-50 y=-50 r=100
581     .filled o1 outline=o fill=horizon1 line=0
582     .put o1 x=50 y=50
583
584     .texture horizon2=horizon x=0 y=0 r=50
585     .filled o2 outline=o fill=horizon2 line=0
586     .put o2 x=150 y=50
587
588     .texture horizon3=horizon x=0 y=50 r=10
589     .filled o3 outline=o fill=horizon3 line=0
590     .put o3 x=50 y=150
591
592     .texture horizon4=horizon x=50 y=50 r=200
593     .filled o4 outline=o fill=horizon4 line=0
594     .put o4 x=150 y=150
595     
596     .gradient bunt:
597         0% black
598         20% blue
599         40% magenta
600         60% orange
601         80% cyan 
602         100% white
603     .end
604     
605     .texture bunt1=bunt x=-50 y=-50 width=100
606     .filled oo1 outline=o fill=bunt1 line=0
607     .put oo1 x=50 y=250
608
609     .texture bunt2=bunt x=-50 y=-50 width=141 height=141 rotate=45
610     .filled oo2 outline=o fill=bunt2 line=0
611     .put oo2 x=150 y=250
612
613     .texture bunt3=bunt x=-50 y=50 width=141 height=141 rotate=-45
614     .filled oo3 outline=o fill=bunt3 line=0
615     .put oo3 x=50 y=350
616
617     .texture bunt4=bunt x=50 y=50 width=100 rotate=180
618     .filled oo4 outline=o fill=bunt4 line=0
619     .put oo4 x=150 y=350
620
621 .end
622 </code>
623
624
625 <!-- TODO: bitmap filling -->
626
627 </section>
628
629 </chapter>
630
631
632 <chapter title="ActionScript">
633
634 <section>
635     <c>swfc</c> has Actionscript support.
636     For normal actionscript, which is executed once a given frame
637     is reached, just open an <c>.action</c> block, and write
638     the ActionScript into the block:
639   
640 <code lang="swfc">
641 .flash filename="action.swf" bbox=300x300 fps=50
642
643 .box mybox color=blue fill=green width=100 height=100
644 .put mybox
645
646 .frame 1
647     .action:
648         _root.angle += 0.05;
649         mybox._x = 100*Math.cos(_root.angle)+100;
650         mybox._y = 100*Math.sin(_root.angle)+100;
651     .end
652 .frame 2
653     .action:
654         gotoFrame(0);
655         Play();
656     .end
657 .frame 3
658 .end
659 </code>
660
661 For much more interesting ActionScript examples, see
662 Laurent Lalanne's 
663 <a href="http://technoargia.free.fr/swftools/examples/flash_eyes/flash_eyes.html">Flash Eyes</a>
664 or the 
665 <a href="http://melusine.eu.org/syracuse/flash/20040429/fabrique/">source</a>
666 of Jean-Michel Sarlat's
667 <a href="http://melusine.eu.org/syracuse/flash/20040429/">Mandelbrot explorer</a>.
668 or
669 <a href="http://www.goldenxp.com/repo/swfr/index.htm">Sunder Iyer's swfc pages</a>.
670
671 </section>
672
673
674 </chapter>
675
676 <chapter title="Buttons">
677 <p>
678 Actionscript comes in handy when dealing with SWF Buttons.
679 </p>
680 <p>
681 A button defines, in SWF context, an object sensitive to mouse movement,
682 mouse buttons, and key presses.
683 </p>
684 <p>
685 The following is a trivial example: Four objects which change their shape
686 once the cursor is over it.
687 <code lang="swfc">
688 .flash filename="button1.swf" fps=50
689
690 .box box1 color=white fill=#336633 width=50 height=50 
691 .box box2 color=white fill=#99cc99 width=100 height=100
692 .button mybutton1
693     .show box1 as=shape x=25 y=25
694     .show box2 as=hover x=12.5 y=12.5
695 .end
696
697 .frame 1
698     .put b1=mybutton1
699     .put b2=mybutton1 x=100 red=+255
700     .put b3=mybutton1 y=100 green=+255
701     .put b4=mybutton1 x=100 y=100 blue=+255
702 .end
703 </code>
704 </p>
705
706 <p>
707 The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
708 very similar to <c>.put</c>. 
709 For every shape a button uses, you can specify the position, color transform, scaling,
710 rotation etc. just like with <c>.put</c>.
711 </p>
712 <p>
713 The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
714 with that you tell the button when to display that specific shape.
715 There are four allowed parameters to <c>as</c>:
716 <ul>
717     <li><b>idle</b> The shape to display when the button is idle, that is, the
718                     mouse is somewhere else, and not over the button.
719     </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
720                      What exactly is <i>"inside"</i> is defined by <b>area</b>:
721     </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
722                      bounding polygon) for the button. A button considers itself
723                      active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
724                      shape) if the mouse is inside this area. Also, mouse button clicks
725                      have to be in this area for this button.
726     </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
727                        is displayed as long as the mouse button is down.
728     </li>
729 </ul>
730 </p>
731
732 <!-- TODO: button actionscript -->
733
734 <!--
735 <section><title>Another button example: tooltips</title>
736
737 Due to the fact that button shapes can be put <i>anywhere</i> especially
738 outside the active area, it's easy to generate tooltips or subtitles.
739
740 <code lang="swfc">
741 .flash filename="tooltips.swf" fps=50
742
743 .jpeg pic fence.jpg
744 .put pic
745
746 .font arial Arial.ttf
747 .edittext tooltip_fence text="fence" readonly color=green font=arial width=200 height=50 size=20%
748 .edittext tooltip_wheel text="wheel" readonly color=green font=arial width=200 height=50 size=20%
749 .edittext tooltip_tree text="tree" readonly color=green font=arial width=200 height=50 size=20%
750 .edittext tooltip_mountain text="mountain" readonly color=green font=arial width=200 height=50 size=20%
751
752 .box box1 fill=red width=1 height=1
753 .button mybutton1
754     .show box1 as=area x=0 y=0
755     .show tooltip_fence as=hover x=25 y=25 scalex=100 scaley=100 alpha=50%
756     .show tooltip_fence as=idle x=25 y=25 scalex=100 scaley=100 alpha=50%
757 .end
758
759 .frame 1
760     .put mybutton1
761 .end
762 </code>
763
764 </section>
765 -->
766
767 </chapter>
768
769 <chapter title="Blend Modes">
770
771 Blend modes were introduced in Flash 8. They allow to use different alrithmetrics when
772 it comes to putting transparent (or semi transparent) shapes or images on top of each
773 other.
774 The diffent blend modes are:
775
776 <shell>
777 normal
778 layer
779 multiply
780 screen
781 lighten
782 darken
783 add
784 substract
785 difference
786 invert
787 alpha
788 erase
789 overlay
790 hardlight
791 </shell>
792
793 For example, in order to set a "invert" blend mode:
794
795 <code lang="swfc">
796 .flash filename="invert.swf" fps=50 bbox=511x127
797 .jpeg pic stripe.jpg
798 .put pic
799 .font arial Arial.ttf
800 .text txt font=arial text="Test inverted blend mode... ABCDEFGHIJKLMNOPQRSTUVWXYZ" size=200%
801
802 .put txt x=512 y=120 blend=invert
803 .frame 700
804 .change txt x=-4096
805 .end
806 </code>
807
808 The <c>layer</c> blend modes is especially useful, if you want to 
809 make sprite transparent. Compare the two stacks of rectangles
810 in the next example. In the left one (set without <c>layer</c>), when
811 the sprite is made transparent via <c>alpha=50%</c>, the rectangles
812 also are transparent in respect to each other- i.e., you don't get
813 a transparent image of a stack of rectangles, you get an image
814 of a stack of transparent rectangles. On the right side, the
815 stack is set with <c>layer</c>, and only the whole sprite get's
816 transparent.
817
818 <code lang="swfc">
819 .flash filename="layer.swf" fps=50 bbox=511x127
820 .jpeg background stripe.jpg
821 .put background
822
823 .box b1 fill=green width=100 height=100
824 .box b2 fill=cyan width=100 height=100
825 .box b3 fill=blue width=100 height=100
826 .sprite s1
827     .put b1
828     .put b2 x=25 y=25
829     .put b3 x=50 y=50
830 .end
831 .sprite s2
832     .put b1
833     .put b2 x=25 y=25
834     .put b3 x=50 y=50
835 .end
836
837 .put s1 alpha=50%
838 .put s2 alpha=50% x=300 blend=layer
839
840 .end
841 </code>
842
843 </chapter>
844
845 <chapter title="Filters">
846
847 <p>
848 An especially nice new feature of Flash 8 are filters.
849 </p>
850 <p>
851 The current version of swfc supports the following filters:
852 </p>
853
854 <shell>
855 dropshadow
856 blur
857 gradientglow
858 bevel
859 </shell>
860
861 <section><title>The "dropshadow" filter</title>
862
863 <c>dropsshadow</c> can be used to add shadows below (or above) flash
864 objects.
865 Every shadow has a color, and a direction/distance parameter (<c>angle</c>,<c>distance</c>),
866 which controls where the shadow will be placed.
867 The shadow is calculated by blurring (radios <c>blur</c> the alpha layer of the corresponding object,
868 strengthening it (multiplication with <c>strength</c>), filling it with <c>color</c> 
869 and then merging it with the background.
870 If the optional <c>knockout</c> option is given, the original object is removed, only the shadow
871 is visible. If the <c>innershadow</c> parameter is given, the shadow will be <b>inside</b> the
872 object.
873
874 <code lang="swfc">
875 .flash filename="shadow.swf" version=8 bbox=430x140 background=blue
876     .font myfont "Times.ttf"
877     .text mytext text="SHADOW" font=myfont size=140% color=yellow
878     .dropshadow myshadow color=black blur=5 angle=45 distance=50 passes=2 strength=1
879     .put mytext filter=myshadow y=75
880 .end
881 </code>
882
883 </section>
884 <section><title>The "bevel" filter</title>
885
886 <p>
887 The <c>bevel</c> filter essentially applies two shadows at once, at opposite directions.
888 It supports the same arguments as the <c>dropshadow</c> filter, and also the optional
889 <c>ontop</c> argument, which, if given, moves the "shadows" above the image. (useful
890 together with <c>knockout</c>).
891 </p>
892
893 The following example demonstrates another feature of the swfc filter implementation: filters
894 can also be animated.
895
896 <code lang="swfc">
897 .flash filename="bevel.swf" version=8 background=blue fps=12
898     .font arial "Arial.ttf"
899     .text abc text="FILTERS" font=arial size=130% color=red
900     .text beveltxt text="BEVEL" font=arial size=130% color=red
901     
902     .bevel bevel0 highlight=white shadow=black blur=9 angle=45 distance=4 passes=2 strength=2 knockout
903     .bevel bevel1 highlight=white shadow=black blur=14 angle=45 distance=6 passes=2 strength=2 knockout
904     
905     .bevel bevel2 highlight=white shadow=black blur=7 angle=0 distance=6 passes=2 strength=1 innershadow knockout
906     .bevel bevel3 highlight=white shadow=black blur=7 angle=360 distance=6 passes=2 strength=1 innershadow knockout
907
908     .put beveltxt filter=bevel0
909     .put abc filter=bevel2 y=80
910     .frame 50
911     .change beveltxt filter=bevel1
912     .frame 100
913     .change beveltxt filter=bevel0
914     .change abc filter=bevel3
915 .end
916 </code>
917
918 </section>
919 <section><title>The "blur" filter</title>
920
921 The <c>blur</c> filter is probably the most simple filter- it only
922 takes a blur radius and a number of passes. It then performs a blur effect
923 by smoothening an area of <c>blurx</c> times <c>blury</c> pixels.
924
925 <code lang="swfc">
926 .flash filename="blur.swf" version=8 fps=50 bbox=200x200
927     .font arial "Arial.ttf"
928     .blur myblur1 blur=100 passes=2 # blur=100 is an abbreviation for blurx=100 blury=100
929     .blur myblur2 blurx=0 blury=0 passes=2
930     .blur myblur3 blurx=0 blury=100 passes=2
931     .textshape abc text="BLUR" font=arial size=100% 
932     .filled fabc outline=abc line=2 color=blue fill=white
933     .filled fabc2 outline=abc line=2 color=red fill=yellow
934     .sprite mysprite
935         .put fabc pin=center x=100 y=100
936         .put fabc2 pin=center x=100 y=100
937         .frame 200
938         .change fabc pin=center rotate=360
939         .change fabc2 pin=center rotate=-360
940     .end
941     .put mysprite filter=myblur1
942     .frame 200
943     .change mysprite filter=myblur2
944     .frame 400
945     .change mysprite filter=myblur3
946 .end
947 </code>
948
949 </section>
950 <section><title>The "gradientglow" filter</title>
951
952 <c>gradientglow</c> is like the <c>shadow filter</c>, only that the
953 resulting shadow color is calculated from a gradient instead of a single color.
954
955 <code lang="swfc">
956 .flash filename="filters.swf" version=8
957     .font times "Times.ttf"
958     .text abc text="Gradientglow" font=times size=100% color=blue
959     .gradient fire:
960         0% black/00
961         25% red/40
962         50% orange/80
963         75% yellow/c0
964         100% white/ff
965     .end
966     .gradientglow fireglow1 gradient=fire blur=20 innershadow angle=1 distance=20
967     .gradientglow fireglow2 gradient=fire blur=20 angle=0 distance=2 passes=1 knockout
968     .gradientglow fireglow3 gradient=fire blur=20 angle=0 distance=2 passes=1 ontop
969
970     .put abc1=abc filter=fireglow1
971     .put abc2=abc y=50 filter=fireglow2
972     .put abc3=abc y=100 filter=fireglow3
973 .end
974
975 </code>
976
977 </section>
978
979 </chapter>
980
981 </guide>