1
2=head1 NAME
3
4SWF::Element - Classes of SWF tags and elements.
5
6=head1 SYNOPSIS
7
8  use SWF::Element;
9  use SWF::BinStream;
10
11  $swf_stream=SWF::BinStream::Write;
12  ....
13  $rect=SWF::Element::RECT->new;
14  $rect->configure(Xmin=>0, Ymin=>0, Xmax=>100, Ymax=>100);
15  $rect->pack($swf_stream);
16  ....
17
18=head1 DESCRIPTION
19
20I<SWF::Element> module handles SWF tags and any other sub elements
21to create, configure, clone, pack to bit strings, and unpack from bit strings.
22
23=head2 SWF::Element::*
24
25I<SWF::Element> class is a base class of SWF element, such as Tag, RECT, SHAPE, etc.
26Each SWF::Element object has one or more fields.
27
28=head3 METHODS
29
30=over 4
31
32=item $element=SWF::Element::* ->new([parameters]);
33
34creates a new element. The new element is configured with parameters.
35
36=item $element->clone;
37
38duplicates the element.
39
40=item $element->configure( [name[=>value, ...]] );
41
42gets and sets fields of the element.
43
44When calling without any parameter, the method returns all field names and values of the element as hash.
45
46When calling with a field name, the method returns the field value of the element.
47
48When calling with one or more pair of name and value, the method sets the field of the element
49and returns the element itself.
50If I<value> is an array reference, recursively configure the field element.
51
52=item $element->defined;
53
54returns whether I<$element> is defined or not.
55The I<$element> is I<NOT defined> if all of its field are not defined.
56
57=item $element->dumper([\&outputsub, $indent]);
58
59dumps the element as a perl script which can re-create the element.
60It can take the subroutine reference and initial indent width for output.
61The subroutine is called with the script string and the indent width.
62In default, prints the script to the selected filehandle (usually STDOUT).
63
64=item $element->pack($stream);
65
66writes the element to I<$stream> as bit string SWF format.
67I<$stream> should be I<SWF::BinStream::Write> object.
68
69=item $element->unpack($stream);
70
71reads the bit string data from I<$stream> and unpack the element.
72I<$stream> should be I<SWF::BinStream::Read> object.
73
74=item $element->I<FieldName>([configure parameters...]);
75
76Each field of I<$element> can access by field name.
77When calling without parameter, it returns the field object or value.
78when calling with parameters, it calls I<configure> method to set the field with the parameters and returns the field object or value.
79
80=item $element->I<FlagName>([value]);
81
82Some fields are sets of flags.  A flag is not an object but a simple scalar value, and is accessed by flag accessor method.
83When calling without value, it returns the flag value.
84When calilng with the value, it sets proper bit(s) of the I<Flags> field with the value and returns the flag value.
85Some flags are read only.
86
87=back
88
89=head2 SWF::Element::Scalar derivatives
90
91I<SWF::Element::Scalar> derivatives represent a scalar field which have their own pack/unpack method.
92
93  SWF::Element::STRING    - null-terminated string.
94  SWF::Element::PSTRING   - pascal type string (string with its length).
95  SWF::Element::ID        - 16bit ID of SWF characters (shapes, bitmaps, sounds, etc.)
96  SWF::Element::Depth     - 16bit Depth of SWF characters.
97  SWF::Element::BinData   - Binary Data (described later).
98
99=head3 METHODS
100
101I<SWF::Element::Scalar> inherits all methods of I<SWF::Element> except any
102field/flag accessors.  Here described the difference.
103
104=over 4
105
106=item $scalar->configure([value])
107
108When calling without any parameter, the method returns the value of the object.
109When calling with a value, the method sets the value to the object and returns the value.
110
111=item $scalar->value
112
113returns the value of the object.
114
115=back
116
117=head2 SWF::Element::BinData
118
119represents a binary data.
120
121=head3 METHODS
122
123It has the same methods as I<SWF::Element::Scalar>.
124The other methods are described here.
125
126=over 4
127
128=item $bindata->Length
129
130returns the length of the data.
131
132=item $bindata->add( string )
133
134adds a string to the data.
135
136=item $bindata->substr( offset [, length , [replace]] )
137
138Extracts a substring out of the data.  It behaves similar to
139CORE::substr.
140
141=item $bindata->save( file )
142
143saves the data to the file.  It takes a file name or a file handle.
144
145=item $bindata->load( file )
146
147loads the data from the file. It takes a file name or a file handle.
148
149=back
150
151=head2 SWF::Element::Array::*
152
153I<SWF::Element::Array> is a base class which represents an array of the SWF element.
154The I<SWF::Element::Array> object is an array reference.
155
156=head3 METHODS
157
158I<SWF::Element::Array> has all methods of I<SWF::Element> except any
159field/flag accessors.  Here described the difference.
160
161=over 4
162
163=item $array->configure( list... )
164
165adds I<list> to the array.  Each element of the list must be a proper element object or an array reference.
166
167=item $array->new_element
168
169creates a proper new element for the array.
170The new element is not add the array automatically.  You should do 'push @$array, $new' if you want to add
171the new element.
172
173=back
174
175=head2 SUBCLASSES
176
177Here is the list of all subclasses representing the SWF element.
178'SWF::Element::' is omitted from each class name.
179ex. RECT means SWF::Element::RECT class.
180'$' represents a simple scalar.
181The I<field> whose class is '(Flags)' is a flag accessor handling bits in the I<Flags>.
182'-' indicates it is read only.
183See 'Macromedia Flash (SWF) File Format Specifications' for further information about SWF elements and fields.
184You can get the document from http://www.macromedia.com/software/flash/open/licensing/fileformat/ .
185
186=head3 Basic Types
187
188=over 4
189
190=item RGB / RGBA
191
192represents a color without/with alpha channel.
193
194  field    class
195  Red      $
196  Green    $
197  Blue     $
198  Alpha    $  - RGBA only
199
200=item RECT
201
202represents a rectanglular region.
203
204  field    class
205  Xmin     $
206  Ymin     $
207  Xmax     $
208  Ymax     $
209
210=item MATRIX
211
212represents a matrix for scale, rotation, and translation.
213
214 field        class
215 ScaleX       $
216 ScaleY       $
217 RotateSkew0  $
218 RotateSkew1  $
219 TranslateX   $
220 TranslateY   $
221
222There are three methods.
223
224=over 4
225
226=item $matrix->scale([xscale, [yscale]]);
227
228scales up and down by I<xscale> and I<yscale> for X-axis and Y-axis, respectively.
229If omitting I<yscale>, I<xscale> is used for both axis.
230
231=item $matrix->moveto(x,y);
232
233moves to (I<x>, I<y>).
234
235=item $matrix->rotate(degree);
236
237rotates I<degree> degree.
238
239=back
240
241=item CXFORM / CXFORMWITHALPHA
242
243represents a color transform value.
244
245 field          class
246 Flags          $
247   HasAddTerms  (Flags)
248   HasMultTerms (Flags)
249 RedMultTerm    $
250 GreenMultTerm  $
251 BlueMultTerm   $
252 AlphaMultTerm  $  - CXFORMWITHALPHA only.
253 RedAddTerm     $
254 GreenAddTerm   $
255 BlueAddTerm    $
256 AlphaAddTerm   $  - CXFORMWITHALPHA only.
257
258Usually it is not necessary to set HasAddTerms and HasMultTerms.
259They are set whether the terms are defined.
260When you want to reset CXFORM, reset both flags without defining any term as follows:
261
262 $cxform = SWF::Element::CXFORM->new;
263 $cxform->HasAddTerms(0);
264 $cxform->HasMultTerms(0);
265
266or
267
268 $cxform = SWF::Element::CXFORM->new;
269 $cxform->Flags(0);
270
271
272=back
273
274=head3 SWF Tags
275
276=over 4
277
278=item Tag
279
280A base class of all SWF tags.
281When it is unpacked from SWF stream, it is re-blessed the proper tag class.
282
283=over 4
284
285=item $tag->lookahead_I<FieldName>($stream)
286
287You can read some field from the stream before unpacking the tag by
288lookahead_I<FieldName> method.
289The field for which a lookahead method is prepared is marked with '*'
290in the lookahead column of the following tables.
291It should be run subsequently to parsing the tag header and before
292unpacking the tag data.
293
294=item $tag->tag_number
295
296returns the tag ID number.
297
298=item $tag->tag_name
299
300returns the tag name.
301
302=item $tag->is_tagtype( $type )
303
304returns true if $tag inherits a type $type.
305
306 Tag types        Tags
307
308 Definition       ImportAsset, DoInitAction
309  + Shape         DefineShape/2/3, DefineMorphShape
310  + Bitmap
311  |  + LosslessBitmap   DefineBitsLossless/2
312  |  + JPEG       DefineBits, JPEGTables, DefineBitsJPEG2/3
313  + Font          DefineFont/2, DefineFontInfo/2
314  + Text          DefineText/2, DefineEditText
315  + Sound         DefineSound
316  + Button        DefineButton/2, DefineButtonCxform,
317  |               DefineButtonSound
318  + Sprite        DefineSprite
319  + Video         DefineVideo, VideoFrame
320
321 DisplayList      PlaceObject/2, RemoveObject/2, ShowFrame
322
323 Control          SetBackgroundColor, FrameLabel, Protect,
324                  EnableDebugger/2, ScriptLimits, SetTabIndex,
325                  ExportAssets, ImportAssets, End
326
327 ValidInSprite    PlaceObject/2, RemoveObject/2, ShowFrame,
328                  FrameLabel, StartSound, SoundStreamBlock,
329                  SoundStreamHead/2, DoAction, End
330
331 ActionContainer  DoAction, DoInitAction, DefineButton/2,
332                  PlaceObject2
333
334
335=item Tag::Packed
336
337represents packed tag.
338
339 field  class
340 Tag    $
341 Data   BinData
342
343=item Tag::Unknown
344
345represents the unknown tags.
346
347 field  class
348 Tag    $
349 Data   BinData
350
351=back
352
353=head4 Display List
354
355=over 4
356
357=item Tag::PlaceObject
358
359places the object.
360
361 Type: DisplayList, ValidInSprite
362
363 field           class   lookahead
364 CharacterID     ID          *
365 Depth           $           *
366 Matrix          MATRIX
367 ColorTransform  CXFORM
368
369=item Tag::PlaceObject2
370
371places the object.
372
373 Type: DisplayList, ValidInSprite, ActionContainer
374
375 field                     class    lookahead
376 Flags                     $           *
377   PlaceFlagMove           (Flags)
378 - PlaceFlagHasCharacter   (Flags)
379 - PlaceFlagHasMatrix      (Flags)
380 - PlaceFlagColorTransform (Flags)
381 - PlaceFlagHasRatio       (Flags)
382 - PlaceFlagHasName        (Flags)
383 - PlaceFlagClipDepth      (Flags)
384 - PlaceFlagClipActions    (Flags)
385 Depth                     $           *
386 CharacterID               ID          *
387 Matrix                    MATRIX
388 ColorTramsform            CXFORMWITHALPHA
389 Ratio                     $
390 Name                      STRING
391 ClipDepth                 $
392 ClipActions               Array::CLIPACTIONRECORDARRAY
393
394=item Array::CLIPACTIONRECORDARRAY
395
396An array of CLIPACTIONRECORD.
397
398=item CLIPACTIONRECORD
399
400represents a clip action triggered by clip event.
401
402 field                     class
403 EventFlags                $
404   ClipEventConstruct      (EventFlags) - SWF7
405   ClipEventKeyPress       (EventFlags) - SWF6 or higher
406   ClipEventDragOut        (EventFlags) - SWF6 or higher
407   ClipEventDragOver       (EventFlags) - SWF6 or higher
408   ClipEventRollOut        (EventFlags) - SWF6 or higher
409   ClipEventRollOver       (EventFlags) - SWF6 or higher
410   ClipEventReleaseOutside (EventFlags) - SWF6 or higher
411   ClipEventRelease        (EventFlags) - SWF6 or higher
412   ClipEventPress          (EventFlags) - SWF6 or higher
413   ClipEventInitialize     (EventFlags) - SWF6 or higher
414   ClipEventData           (EventFlags)
415   ClipEventKeyUp          (EventFlags)
416   ClipEventKeyDown        (EventFlags)
417   ClipEventMouseUp        (EventFlags)
418   ClipEventMouseDown      (EventFlags)
419   ClipEventMouseMove      (EventFlags)
420   ClipEventUnload         (EventFlags)
421   ClipEventEnterFrame     (EventFlags)
422   ClipEventLoad           (EventFlags)
423 KeyCode                   $
424 Actions                   Array::ACTIONRECORDARRAY
425
426=item Tag::RemoveObject / Tag::RemoveObject2
427
428removes the object.
429
430 Type: DisplayList, ValidInSprite
431
432 field        class  lookahead
433 CharacterID  ID         *        - RemoveObject only
434 Depth        $          *
435
436=item Tag::ShowFrame
437
438shows current frame.
439
440 Type: DisplayList, ValidInSprite
441
442=back
443
444=head4 Controls
445
446=over 4
447
448=item Tag::SetBackgroundColor
449
450sets the background color.
451
452 Type: Control
453
454 field            class
455 BackgroundColor  RGB
456
457=item Tag::FrameLabel
458
459sets the frame label.
460
461 Type: Control, ValidInSprite
462
463 field          class
464 Name           STRING
465 NameAnchorFlag $
466
467=item Tag::Protect
468
469prevents the file from editing in the authoring tool.
470
471 Type: Control
472
473 field     class  lookahead
474 Reserved  $          *      always 0 (?)
475 Password  STRING
476
477=item Tag::End
478
479marks the end of the file.
480
481 Type: Control, ValidInSprite
482
483=item Tag::ExportAssets
484
485exports SWF characters to use in other SWFs.
486
487 Type: Control
488
489 field   class
490 Assets  Array::ASSETARRAY
491
492=item Tag::ImportAssets
493
494imports SWF characters from another SWF.
495
496 Type: Control, Definition
497
498 field   class
499 URL     STRING
500 Assets  Array::ASSETARRAY
501
502=item Array::ASSETARRAY
503
504An array of ASSET.
505
506=item ASSET
507
508An ID and name pair of SWF character for export/import.
509
510 field   class
511 ID      ID
512 Name    STRING
513
514=item Tag::EnableDebugger / 2
515
516enables debugging.
517EnableDebugger is for SWF 5, and EnableDebugger2 is for SWF 6 or later.
518
519 Type: Control
520
521 field     class  lookahead
522 Reserved  $          *      always 0
523 Password  STRING
524
525=item Tag::ScriptLimits
526
527sets the maximum recurtion depth and ActionScript time-out.
528
529 Type: Control
530
531 field                class lookahead
532 MaxRecurtionDepth      $     *
533 ScriptTimeoutSeconds   $     *
534
535=item Tag::SetTabIndex
536
537sets the tab order of the object placed on the specified depth.
538
539 Type: Control
540
541 field     class  lookahead
542 Depth     Depth    *
543 TabIndex  $        *
544
545=back
546
547=head4 Actions
548
549=over 4
550
551=item Tag::DoAction
552
553sets the frame action.
554
555 Type: ValidInSprite, ActionContainer
556
557 field    class
558 Actions  Array::ACTIONRECORDARRAY
559
560=item Tag::DoInitAction
561
562performs the actions to initialize a sprite.
563
564 Type: Definition, ActionContainer
565
566 field    class      lookahead
567 SpriteID ID             *
568 Actions  Array::ACTIONRECORDARRAY
569
570=item Array::ACTIONRECORDARRAY
571
572An array of ACTIONRECORD
573
574=item ACTIONRECORD
575
576Base class of action tags.
577Action tags without any parameter belongs this class.
578
579 field  class
580 Tag    ACTIONTagNumber
581
582And it has a pseudo-field, 'LocalLabel', which can be used as
583destination of ActionIf, ActionJump, and ActionWaitForFrame/2,
584and CodeSize of DefineFunction.
585Label string must not start with digits and not contain '#'.
586
587=item ACTIONTagNumber
588
589represents an action tag number or name.
590
591=item ACTIONRECORD::ActionUnknown
592
593represents an undefined actiontag.
594
595 field  class
596 Tag    ACTIONTagNumber
597 Data   BinData
598
599=item ACTIONRECORD::ActionGotoFrame
600
601goes to the specified frame.
602
603 field  class
604 Tag    ACTIONTagNumber
605 Frame  $
606
607=item ACTIONRECORD::ActionGetURL
608
609directs the player to get the specified URL.
610
611 field         class
612 Tag           ACTIONTagNumber
613 UrlString     STRING
614 TargetString  STRING
615
616=item ACTIONRECORD::ActionWaitForFrame
617
618waits until the specified frame otherwise skip the specified number of actions.
619
620 field      class
621 Tag        ACTIONTagNumber
622 Frame      $
623 SkipCount  $[label]
624
625I<unpack> method calculate the destination of I<SkipCount>, insert LocalLabel
626into the destination action, and set the I<SkipCount> value to 'label#original value'
627such as 'A#45'.  When the action is I<pack>ed to SWF stream, '#' and the following
628letters are ignored.
629
630=item ACTIONRECORD::ActionSetTarget
631
632sets context of action.
633
634 field       class
635 Tag         ACTIONTagNumber
636 TargetName  STRING
637
638=item ACTIONRECORD::ActionGotoLabel
639
640goes to frame associated with the specified label.
641
642 field  class
643 Tag    ACTIONTagNumber
644 Label  STRING
645
646=item ACTIONRECORD::ActionWaitForFrame2
647
648waits until the frame specified in the stack otherwise skip the specified number of actions.
649
650 field      class
651 Tag        ACTIONTagNumber
652 SkipCount  $[label]
653
654See also the note of WaitForFrame about the label.
655
656=item ACTIONRECORD::ActionPush
657
658pushes data on the stack.
659
660 field     class
661 Tag       ACTIONTagNumber
662 DataList  Array::ACTIONDATAARRAY
663
664=item Array::ACTIONDATAARRAY
665
666An array of ACTIONDATA
667
668=item ACTIONDATA
669
670A base class of data for action script.
671If you configure this element, the element is re-blessed with proper
672subclass.
673
674=over 4
675
676=item $actiondata->configure([type => data])
677
678sets the data and re-blessed itself to the type.
679Types are String, Property (FLASH 4 only), Register, Boolean, Double, Integer, Lookup.
680
681=back
682
683=item ACTIONRECORD::ActionJump / ActionIf
684
685branches action script always / if stack top is true.
686
687 field         class
688 BranchOffset  $[label]
689
690I<unpack> method calculate the destination of I<BranchOffset>, insert LocalLabel
691into the destination action, and set the I<BranchOffset> value to 'label#original value'
692such as 'A#45'.  When the action is I<pack>ed to SWF stream, '#' and the following
693letters are ignored.
694
695
696=item ACTIONRECORD::ActionGetURL2
697
698directs the player to get the URL specified in the stack.
699
700 field   class
701 Tag     ACTIONTagNumber
702 Method  $
703
704=item ACTIONRECORD::ActionGotoFrame2
705
706goes to the frame specified in the stack.
707
708 field    class
709 Tag      ACTIONTagNumber
710 PlayFlag $
711
712=item ACTIONRECORD::ActionConstantPool
713
714defines word set which can be referred by index.
715
716 field  class
717 Tag    ActionTagNumber
718 ConstantPool  Array::STRINGARRAY
719
720=item Array::STRINGARRAY
721
722an array of STRING.
723
724=item ACTIONRECORD::ActionDefineFunction
725
726defines a function.
727
728 field     class
729 Tag       ActionTagNumber
730 FunctionName  STRING
731 Params        Array::STRINGARRAY
732 CodeSize      $[label]
733
734CodeSize can take the label which indicates the action next to
735the function definition.
736
737=item ACTIONRECORD::ActionStoreRegister
738
739stores the stack top to the register.
740
741 field     class
742 Tag       ActionTagNumber
743 Register  $
744
745=item ACTIONRECORD::ActionWith
746
747refers to the object on the top of stack for the script
748written in the I<CodeSize>.
749
750 field      class
751 CodeSize   $[label]
752
753CodeSize can take the label which indicates the action next to
754the end of the block.
755
756=item ACTIONRECORD::ActionDefineFunction2
757
758defines a function, which can use local registers.
759
760 field                   class
761 FuncitonName            STRING
762 RegisterCount           $
763 Flags                   $
764   PreloadGlobalFlag     (Flags)
765   PreloadParentFlag     (Flags)
766   PreloadRootFlag       (Flags)
767   SuppressSuperFlag     (Flags)
768   PreloadSuperFlag      (Flags)
769   SuppressArgumentsFlag (Flags)
770   PreloadArgumentsFlag  (Flags)
771   SuppressThisFlag      (Flags)
772   PreloadThisFlag       (Flags)
773 Parameters              Array::REGISTERPARAMARRAY
774 CodeSize                $[label]
775
776CodeSize can take the label which indicates the action next to
777the function definition.
778
779=item Array::REGISTERPARAMARRAY
780
781an array of REGISTERPARAM.
782
783=item REGISTERPARAM
784
785shows the correspondence of a register to a named parameter.
786
787 field      class
788 Register   $
789 ParamName  STRING
790
791=item ACTIONRECORD::ActionTry
792
793defines handlers for exception.
794
795 field         class
796 TrySize       $[label]
797 CatchSize     $[label]
798 FinallySize   $[label]
799 CatchName     STRING
800 CatchRegister $
801
802TrySize, CatchSize, and FinallySize can take the label which indicates
803the action next to the end of each block.
804Either CatchName or CatchRegister should be set, not both.
805
806=item ACTIONRECORD::ActionStrictMode
807
808sets the strict mode (obsolete).
809
810 field       class
811 StrictMode  $
812
813
814=back
815
816=head4 Shapes
817
818=over 4
819
820=item Array::FILLSTYLEARRAY1 / 2 / 3
821
822An array of fill styles.
823FILLSTYLEARRAY1 and 2 have FILLSTYLE1, and FILLSTYLEARRAY3 has FILLSTYLE3.
824
825=item FILLSTYLE1 / 3
826
827represents fill style of shapes.
828FILLSTYLE3 has alpha channels in its field elements.
829
830 field           class
831 FillStyleType   $
832 Color           RGB / RGBA
833 GradientMatrix  MATRIX
834 Gradient        Array::GRADIENT1 / 3
835 BitmapID        ID
836 BitmapMatrix    MATRIX
837
838=item Array::LINESTYLEARRAY1 / 2 / 3
839
840An array of line styles.
841LINESTYLEARRAY1 and 2 have LINESTYLE1, and LINESTYLEARRAY3 has LINESTYLE3.
842
843=item LINESTYLE1 / 3
844
845represents a line style of shapes.
846LINESTYLE3 has an alpha channel.
847
848 field  class
849 Width  $
850 Color  RGB / RGBA
851
852=item SHAPE
853
854represents a shape without styles for DefineFont/2, and DefineMorphShape.
855
856 field         class
857 ShapeRecords  Array::SHAPERECARRAY1
858
859=item SHAPEWITHSTYLE1 / 2 / 3
860
861represents a shape with styles.
862SHAPEWITHSTYLE3 has alpha channels.
863
864 field         class
865 FillStyles    Array::FILLSTYLEARRAY1 / 2 / 3
866 LineStyles    Array::LINESTYLEARRAY1 / 2 / 3
867 ShapeRecords  Array::SHAPERECARRAY1 / 2 / 3
868
869=item Array::SHAPERECORDARRAY1 / 2 / 3
870
871An array of SHAPERECORD1 / 2 / 3.
872
873=item SHAPERECORD1 / 2 / 3
874
875is a base class of the edges of a shape.
876If you configure this element, the element is re-blessed with proper
877subclass.
878
879=item SHAPERECORD1/2/3::STYLECHANGERECORD
880
881represents a start point and style of new edge.
882
883 field       class
884 MoveDeltaX  $
885 MoveDeltaY  $
886 FillStyle0  $
887 FillStyle1  $
888 LineStyle   $
889 FillStyles  Array::FILLSTYLEARRAY2 / 3  - SHAPERECORD2/3 only
890 LineStyles  Array::LINESTYLEARRAY2 / 3  - SHAPERECORD2/3 only
891
892=item SHAPERECORDn::STRAIGHTEDGERECORD
893
894represents a straight edge.
895This is common subclass of SHAPERECORD1/2/3.
896
897 field   class
898 DeltaX  $
899 DeltaY  $
900
901=item SHAPERECn::CURVEDEDGERECORD
902
903represents a curved edge.
904This is common subclass of SHAPEREC1/2/3.
905
906 field          class
907 ControlDeltaX  $
908 ControlDeltaY  $
909 AnchorDeltaX   $
910 AnchorDeltaY   $
911
912=item Tag::DefineShape / Tag::DefineShape2 / Tag::DefineShape3
913
914defines shape. DefineShape2/3 can have more than 255 styles.
915DefineShape3 contains alpha channels.
916
917 Type: Shape
918
919 field        class     lookahead
920 ShapeID      ID            *
921 ShapeBounds  RECT
922 Shapes       SHAPEWITHSTYLE1 / 2 / 3
923
924=back
925
926=head4 Gradients
927
928=over 4
929
930=item Array::GRADIENT1 / 3
931
932represents a gradient information.
933Each of them is an array of GRADRECORD1 / 3.
934
935=item GRADRECORD1 / 3
936
937represents one of the colors making gradient.
938GRADRECORD3 has an alpha channel.
939
940 field  class
941 Ratio  $
942 Color  RGB / RGBA
943
944=back
945
946=head4 Bitmaps
947
948=over 4
949
950=item Tag::DefineBits
951
952defines JPEG image data.
953
954 Type: JPEG
955
956 field        class    lookahead
957 CharacterID  ID           *
958 JPEGImage    BinData
959
960=item Tag::JPEGTable
961
962defines JPEG encoding table.
963
964 Type: JPEG
965
966 field     class
967 JPEGData  BinData
968
969=item Tag::DefineBitsJPEG2 / 3
970
971defines JPEG data including both the encoding table and the image data.
972DefineBitsJPEG3 has an alpha data table.
973
974 Type: JPEG
975
976 field            class    lookahead
977 CharacterID      ID           *
978 JPEGData         BinData
979 BitmapAlphaData  BinData             - JPEG3 only.
980
981=item Tag::DefineBitsLossless / Tag::DefineBitsLossless2
982
983defines a loss-less bitmap.
984DefineBitsLossless2 contains alpha channels.
985
986 Type: LosslessBitmap
987
988 field                 class   lookahead
989 CharacterID           ID          *
990 BitmapFormat          $           *
991 BitmapWidth           $           *
992 BitmapHeight          $           *
993 BitmapColorTableSize  $           *
994 ZlibBitmapData        BinData
995
996=back
997
998=head4 Morphing
999
1000=over 4
1001
1002=item Tag::DefineMorphShape
1003
1004defines the start and end states of a morph sequence.
1005
1006 Type: Shape
1007
1008 field            class  lookahead
1009 CharacterID      ID         *
1010 StartBounds      RECT
1011 EndBounds        RECT
1012 MorphFillStyles  Array::MORPHFILLSTYLEARRAY
1013 MorphLineStyles  Array::MORPHLINESTYLEARRAY
1014 StartEdges       SHAPE
1015 EndEdges         SHAPE
1016
1017=item Array::MORPHFILLSTYLEARRAY
1018
1019An array of MORPHFILLSTYLE.
1020
1021=item MORPHFILLSTYLE
1022
1023represents fill styles at start and end.
1024
1025 field                class
1026 FillStyleType        $
1027 StartColor           RGBA     (FillStyleType == 0x00)
1028 EndColor             RGBA     (FillStyleType == 0x00)
1029 StartGradientMatrix  MATRIX   (FillStyleType == 0x10[linear] or 0x12[radial])
1030 EndGradientMatrix    MATRIX   (FillStyleType == 0x10[linear] or 0x12[radial])
1031 Gradient             Array::MORPHGRADIENT
1032                               (FillStyleType == 0x10[linear] or 0x12[radial])
1033 BitmapID             ID       (FillStyleType == 0x40[tiled] or 0x41[clipped])
1034 StartBitmapMatrix    MATRIX   (FillStyleType == 0x40[tiled] or 0x41[clipped])
1035 EndBitmapMatrix      MATRIX   (FillStyleType == 0x40[tiled] or 0x41[clipped])
1036
1037=item Array::MORPHGRADIENT
1038
1039An array of MORPHGRADRECORD.
1040
1041=item MORPHGRADRECORD
1042
1043represents one of the colors making gradient at start and end.
1044
1045 field      class
1046 StartRatio $
1047 StartColor RGBA
1048 EndRatio   $
1049 EndColor   RGBA
1050
1051=item Array::MORPHLINESTYLEARRAY
1052
1053An array of MORPHLINESTYLE.
1054
1055=item MORPHLINESTYLE
1056
1057represents a line style of shapes at start and end.
1058
1059 field      class
1060 StartWidth $
1061 StartColor RGBA
1062 EndWidth   $
1063 EndColor   RGBA
1064
1065=back
1066
1067=head4 Fonts and Text
1068
1069=over 4
1070
1071=item Tag::DefineFont
1072
1073defines font glyphs.
1074
1075 Type: Font
1076
1077 field            class        lookahead
1078 FontID           ID               *
1079 GlyphShapeTable  GLYPHSHAPEARRAY1
1080
1081=item Array::GLYPHSHAPEARRAY1 / 2
1082
1083An array of SHAPE.
1084
1085=item Tag::DefineFontInfo / 2
1086
1087defines font information.
1088
1089 Type: Font
1090
1091 field                class    lookahead
1092 FontID               ID           *
1093 FontName             PSTRING
1094 FontFlags            $
1095   FontFlagsSmallText (FontFlags)
1096   FontFlagsShiftJIS  (FontFlags)
1097   FontFlagsANSI      (FontFlags)
1098   FontFlagsItalic    (FontFlags)
1099   FontFlagsBold      (FontFlags)
1100 - FontFlagsWideCodes (FontFlags)
1101 LanguageCode         $                 - DefineFontInfo2 only
1102 CodeTable            Array::FONTCODETABLE
1103
1104=item Tag::DefineFont2
1105
1106defines font glyphs and other information.
1107
1108 Type: Font
1109
1110 field                  class       lookahead
1111 FontID                 ID              *
1112 FontFlags              $               *
1113 - FontFlagsHasLayout   (FontFlags)
1114   FontFlagsShiftJIS    (FontFlags)
1115   FontFlagsSmallText   (FontFlags)
1116   FontFlagsANSI        (FontFlags)
1117 - FontFlagsWideOffsets (FontFlags)
1118   FontFlagsWideCodes   (FontFlags)
1119   FontFlagsItalic      (FontFlags)
1120   FontFlagsBold        (FontFlags)
1121 LanguageCode           $               *
1122 FontName               PSTRING
1123 GlyphShapeTable        Array::GLYPHSHAPEARRAY2
1124 CodeTable              Array::FONTCODETABLE
1125 FontAscent             $
1126 FontDescent            $
1127 FontLeading            $
1128 FontAdvanceTable       Array::FONTADVANCETABLE
1129 FontBoundsTable        Array::FONTBOUNDSTABLE
1130 FontKerningTable       FONTKERNINGTABLE
1131
1132=item Array::FONTCODETABLE / FONTADVANCETABLE / FONTBOUNDSTABLE
1133
1134are arrays of a code, an advance value, and a bounding box of each glyph corresponding to the shape table, respectively.
1135A code and an advance value are scalar, and a bounding box is a RECT.
1136
1137=item FONTKERNINGTABLE
1138
1139represents a table of kerning pairs of the font.
1140Each kerning pair is described as 'code1-code2'.
1141For example, a pair of 'T'(code 84) and 'o'(111) is '84-111'.
1142
1143=over 4
1144
1145=item $kern->configure([ pair [=> adjustment, ...]])
1146
1147When calling without any parameter, it returns all kerning pair and its adjustment.
1148When calling with a kerning pair, it returns the adjustment of the pair.
1149When calling with the list of a kerning pair and its adjustment, it adds the kerning data to the table.
1150
1151=back
1152
1153=item Tag::DefineText / Tag::DefineText2
1154
1155defines text.
1156
1157 Type: Text
1158
1159 field         class   lookahead
1160 CharacterID   ID          *
1161 TextBounds    RECT
1162 TextMatrix    MATRIX
1163 TextRecords   Array::TEXTRECORDARRAY1 / 2
1164
1165=item Array::TEXTRECORDARRAY1 / 2
1166
1167An array of TEXTRECORD1 / 2
1168
1169=item TEXTRECORD1 / 2
1170
1171A base class of text records.
1172If you configure this element, the element is re-blessed with proper
1173subclass.
1174
1175=item TEXTRECORD1/2
1176
1177represents a text style and string.
1178
1179 field         class
1180 FontID        ID
1181 TextColor     RGB / RGBA
1182 XOffset       $
1183 YOffset       $
1184 TextHeight    $
1185 GlyphEntries  Array::GLYPHENTRYARRAY
1186
1187=item Array::GLYPHENTRYARRAY
1188
1189An array of GLYPHENTRY.
1190
1191=item GLYPHENTRY
1192
1193represents a glyph entry for a letter of the text.
1194
1195 field         class
1196 GlyphIndex    $
1197 GlyphAdvance  $
1198
1199=item Tag::DefineEditText
1200
1201defines an edit box.
1202
1203 Type: Text
1204
1205 field          class   lookahead
1206 CharacterID    ID          *
1207 Bounds         RECT
1208 Flags          $
1209   WordWrap     (Flags)
1210   Multiline    (Flags)
1211   Password     (Flags)
1212   ReadOnly     (Flags)
1213 - HasTextColor (Flags)
1214 - HasMaxLength (Flags)
1215 - HasFont      (Flags)
1216   AutoSize     (Flags)
1217 - HasLayout    (Flags)
1218   NoSelect     (Flags)
1219   Border       (Flags)
1220   HTML         (Flags)
1221   UseOutlines  (Flags)
1222 FontID         ID
1223 FontHeight     $
1224 TextColor      RGBA
1225 MaxLength      $
1226 Align          $
1227 LeftMargin     $
1228 RightMargin    $
1229 Indent         $
1230 Leading        $
1231 VariableName   STRING
1232 InitialText    STRING
1233
1234=back
1235
1236=head4 Sounds
1237
1238=over 4
1239
1240=item Tag::DefineSound
1241
1242defines sound.
1243
1244 Type: Sound
1245
1246 field             class    lookahead
1247 SoundID           ID           *
1248 Flags             $            *
1249   SoundFormat     (Flags)
1250   SoundRate       (Flags)
1251   SoundSize       (Flags)
1252   SoundType       (Flags)
1253 SoundSampleCount  $            *
1254 SoundData         BinData
1255
1256=item Tag::StartSound
1257
1258starts playing sound.
1259
1260 Type: ValidInSprite
1261
1262 field      class      lookahead
1263 SoundID    ID             *
1264 SoundInfo  SOUNDINFO
1265
1266=item SOUNDINFO
1267
1268represents sound information.
1269
1270 field            class
1271 SyncFlags        $
1272 - HasInPoint     (SyncFlags)
1273 - HasOutPoint    (SyncFlags)
1274 - HasLoops       (SyncFlags)
1275 - HasEnvelope    (SyncFlags)
1276   SyncNoMultiple (SyncFlags)
1277   SyncStop       (SyncFlags)
1278 InPoint          $
1279 OutPoint         $
1280 LoopCount        $
1281 EnvelopeRecords  Array::SOUNDENVELOPEARRAY
1282
1283=item Array::SOUNDENVELOPEARRAY
1284
1285An array of SOUNDENVELOPE.
1286
1287=item SOUNDENVELOPE
1288
1289represents sound envelope information.
1290
1291 field       class
1292 Pos44       $
1293 LeftLevel   $
1294 RightLevel  $
1295
1296=item Tag::SoundStreamHead / Tag::SoundStreamHead2
1297
1298defines the format of streaming sound.
1299
1300 Type: ValidInSprite
1301
1302 field                    class   lookahead
1303 Flags                    $           *
1304   PlaybackSoundRate      (Flags)
1305   PlaybackSoundSize      (Flags)
1306   PlaybackSoundType      (Flags)
1307   StreamSoundCompression (Flags)
1308   StreamSoundRate        (Flags)
1309   StreamSoundSize        (Flags)
1310   StreamSoundType        (Flags)
1311 StreamSoundSampleCount   $           *
1312 LatencySeek              $           *
1313
1314=item Tag::SoundStreamBlock
1315
1316defines the sound data which is interleaved with the frame.
1317
1318 Type: ValidInSprite
1319
1320 field            class
1321 StreamSoundData  BinData
1322
1323=back
1324
1325=head4 Buttons
1326
1327=over 4
1328
1329=item Array::BUTTONRECORDARRAY1 / 2
1330
1331An array of BUTTONRECORD1 / 2.
1332
1333=item BUTTONRECORD1 / 2
1334
1335represents a button character and associated button states.
1336
1337 field                 class
1338 field                 class
1339 ButtonStates          $
1340   ButtonStateHitTest  (ButtonStates)
1341   ButtonStateDown     (ButtonStates)
1342   ButtonStateOver     (ButtonStates)
1343   ButtonStateUp       (ButtonStates)
1344 CharacterID           ID
1345 PlaceDepth            $
1346 PlaceMatrix           MATRIX
1347 ColorTransform        CXFORMWITHALPHA - BUTTONRECORD2 only
1348
1349=item Tag::Definebutton
1350
1351defines a button character.
1352
1353 Type: Button, ActionContainer
1354
1355 field       class                      lookahead
1356 ButtonID    ID                             *
1357 Characters  Array::BUTTONRECORDARRAY1
1358 Actions     Array::ACTIONRECORDARRAY
1359
1360=item Tag::DefineButton2
1361
1362defines a button character which has the actions triggered by any state stansition.
1363
1364 Type: Button, ActionContainer
1365
1366 field         class                      lookahead
1367 ButtonID      ID                             *
1368 Flags         $                              *
1369   TrackAsMenu (Flags)
1370 Characters    Array::BUTTONRECORDARRAY2
1371 Actions       Array::BUTTONCONDACTIONARRAY
1372
1373=item Array::BUTTONCONDACTIONARRAY
1374
1375An array of BUTTONCONDACTION.
1376
1377=item BUTTONCONDACTION
1378
1379represents actions and a button states condition which triggers off the actions.
1380
1381 field                    class
1382 Condition                $
1383   CondKeyPress           (Condition)
1384   CondOverDownToIdle     (Condition)
1385   CondIdleToOverDown     (Condition)
1386   CondOutDownToIdle      (Condition)
1387   CondOutDownToOverDown  (Condition)
1388   CondOverDownToOutDown  (Condition)
1389   CondOverDownToOverUp   (Condition)
1390   CondOverUpToOverDown   (Condition)
1391   CondOverUpToIdle       (Condition)
1392   CondIdleToOverUp       (Condition)
1393 Actions                  Array::ACTIONRECORDARRAY
1394
1395=item Tag::DefineButtonCxform
1396
1397defines the color transform for each shape and text character in a button.
1398
1399 Type: Button
1400
1401 field                 class  lookahead
1402 ButtonID              ID         *
1403 ButtonColorTransform  CXFORM
1404
1405=item Tag::DefineButtonSound
1406
1407defines the sound data for a button.
1408
1409 Type: Button
1410
1411 field             class      lookahead
1412 ButtonID          ID             *
1413 ButtonSoundChar0  ID             *
1414 ButtonSoundInfo0  SOUNDINFO
1415 ButtonSoundChar1  ID
1416 ButtonSoundInfo1  SOUNDINFO
1417 ButtonSoundChar2  ID
1418 ButtonSoundInfo2  SOUNDINFO
1419 ButtonSoundChar3  ID
1420 ButtonSoundInfo3  SOUNDINFO
1421
1422=back
1423
1424=head4 Sprites
1425
1426=over 4
1427
1428=item Tag::DefineSprite
1429
1430defines a sprite.
1431
1432 Type: Sprite
1433
1434 field              class           lookahead
1435 SpriteID           ID                  *
1436 FrameCount         $                   *
1437 ControlTags        Array::TAGARRAY
1438 (TagStream)        TAGSTREAM
1439
1440=over 4
1441
1442=item $sprite->shallow_unpack($stream)
1443
1444unpacks SpriteID and FrameCount from the stream,
1445and prepare TagStream to parse later instead of unpacking all ControlTags.
1446
1447=back
1448
1449=item Array::TAGARRAY
1450
1451An array of SWF tags.
1452
1453=item TAGSTREAM
1454
1455A stream of the tags.
1456
1457=over 4
1458
1459=item $tagstream->parse( \&callback )
1460
1461parses the tag stream and calls &callback sub.
1462See L<SWF::Parser> for details of the tag callback sub.
1463
1464=back
1465
1466=back
1467
1468=head4 Video
1469
1470=over 4
1471
1472=item  Tag::DefineVideoStream
1473
1474defines a video character.
1475
1476 Type: Video
1477
1478  field        class  lookahead
1479  CharacterID  ID         *
1480  NumFrames    $          *
1481  Width        $          *
1482  Height       $          *
1483  VideoFlags   $          *
1484  CodecID      $          *
1485
1486=item Tag::VideoFrame
1487
1488provides a single frame of video data for a video character.
1489
1490 Type: Video
1491
1492  field      class   lookahead
1493  StreamID   ID          *
1494  FrameNum   $           *
1495  VideoData  BinData
1496
1497=back
1498
1499=head1 LIMITATIONS
1500
1501Not all tags have been tested yet.
1502
1503No support of the SWF version control for the tags unless the version affects the tag structure.
1504
1505Binary block data, such as bitmaps, sounds, and video, are neither decoded nor encoded.
1506
1507=head1 COPYRIGHT
1508
1509Copyright 2000 Yasuhiro Sasama (ySas), <ysas@nmt.ne.jp>
1510
1511This library is free software; you can redistribute it
1512and/or modify it under the same terms as Perl itself.
1513
1514=head1 SEE ALSO
1515
1516L<SWF::BinStream>, L<SWF::Parser>
1517
1518SWF file format specification from Macromedia.
1519
1520
1521=cut
1522
1523