2014/11/21

The Labs.Com Video Lab Perl Flash
Last update 2001/10/17

The Labs - Design & Functionality For The Net

Perl-Interface to libswf.a: Perl Flash (Flash.pm)

  1. Introduction
  2. Download
  3. Installation
  4. Test
  5. Perl API
  6. Documentation
  7. TODO
  8. Related Sites
Perl Flash
1. Introduction
We just started to make an interface of libswf.a (which was written by Paul Haeberli) for Perl called Perl Flash (Flash.pm)

The package is supporting aprx. 98% of function-calls of libswf.a for now.

It's a test-bed to check if libswf.a is mighty enough and useable to build a more complex tool on it.

So far you control the flash-content on a very low-level and you should be versed in Flash3 already in order to use it. (See below "Documentation")

By Dec 30, 2000 Simon Wistow finished Beta of his Perl::Flash
Perl::Flash
Another Perl::Flash
Perl::Flash still requires the libswf.a too like our approach but he is working toward libswf.a independance so the package becomes OS and platform independent (libswf.a is only available as library, no source-code so far).

Perl Flash
2. Download

Flash.pm.tar.gz ($MyVersion: 0.008 - Thu Jun 29 12:04:36 CEST 2000 - kiwi$)

$MyHistory$
	29 Jun 2000: 0.008: bug-fix for shapeFillSolid .
	25 Aug 1999: 0.007: constants included .
	25 Aug 1999: 0.006: getFontInfo bug fix .
	25 Aug 1999: 0.005: sound files supported (16 bits, mono) .
	23 Aug 1999: 0.004: actionXXX and button-functions included .
	23 Aug 1999: 0.003: aprx. 90% of all functions available .
	23 Aug 1999: 0.001: start, few calls supported .

Also download the binary of libswf.a (linux, freebsd, irix):
libswf.a
download the libswf.a library (linux,freebsd,irix)

Perl Flash
3. Installation

After you downloaded the correct libswf.a library then

 tar zvfx Flash.pm.tar.gz 
 cp swf.h libswf.a Flash/ 
 cd Flash; 

Make first the libaudiofile (source included):

 cd libaudiofile-* 
 ./configure 
 make; make install 
 cd ../ 

Back in the Flash/

 perl Makefile.PL; make; make install 

Perl Flash
4. Test

test.pl is the perl-source, which creates test.swf

Put the test.pl within the Flash/ directory and execute it there.

Perl Flash
5. Perl API

DISCLAIMER: Entire API is subject of change at ANY time!

Init:

 open(name,xsize,ysize,framerate=20,r=1,g=1,b=1)
This is the first function you should call to open a .swf file. If you want to write the output to a file, the filename should end in ".swf". If you want to write to stdout, give the special file name of "STDOUT". The xsize and ysize are the dimensions of the Flash movie in pixels. framerate specifies the frame rate in frames per second. The last three arguments r, g, and b select a color to be used for the backgound of the Flash movie.

close()

Closes the .swf file.

Frames:

 labelFrame(name)
This adds a string label to the current frame. This is only needed if you want to use actionGoToLabel to get to this frame in future. If you want to put a secret message into your flash files, this is where to do it!

showFrame()

Finish the current frame and start adding commands to the next frame.

setFrame(no)

Selects the specified frame number for adding commands to.

getFrame()

Returns the frame number of the current frame. The first frame is frame 0.

Color:

 addColor(r=0,g=0,b=0,a=0)
Sets the global add color to the rgba value specified. This color is used implicitly by placeObject, modifyObject and addButtonRecord. This color is added to the original color of the object when it is drawn. These values can be positive or negative.

mulColor(r=1,g=1,b=1,a=1)

Sets the global multiply color to the rgba value specified. This color is used implicitly by placeObject, modifyObject and addButtonRecord. The color of the object will be multiplied by the values given when it is drawn. These values can be positive or negative.

Objects:

 placeObject(id,depth)
Places the object identified by objid in the current frame at the given depth. objids must be between in the range [1..65535], while depths must be between in the range [1..65535]. This uses the current mulcolor and addcolor and matrix to position and color the object. Full RGBA colors are supported.

modifyObject(id,how)

Updates the position and or color of the object at the specified depth. how determines what things are modified using the values FlashModColor, FlashModMatrix or FlashModColor|FlashModMatrix This uses the current mulColor and addColor and matrix to position and color the object. Full RGBA colors are supported.

removeObject(depth)

Removes the object at the specified depth.

nextid()

Returns a free objid. this makes it easier to manage the object ids used.

Primitives:

 line(id,x1,y1,x2,y2,width=1)
Defines a line segment from x1,y1 to x2,y2 with the given line width.

rect(id,x1,y1,x2,y2,width=1)

Defines an outlined rectangle from x1,y1 to x2,y2 with the given line width. If width is 0.0, the rectangle is filled instead of stroked.

Symbols:

 startSymbol(id)
Symbols are tiny Flash movies that can be played simultaneously. To define a symbol, call this function with the objid that you want to use to identify the symbol.

endSymbol()

Completes the symbol.

Action Control:

 An action list is described by a sequence of calls as shown here:

 startDoAction(); 
    actionGotoFrame(143); 
    actionPlay(); 
 endDoAction(); 

You can put lots and lots of actions between startDoAction and endDoAction to create an actionlist. All the actions are performed in sequence after the current frame is drawn.

startDoAction()

This starts the description of an action list for the current frame. There should be only one action list associated with a single frame in the Flash movie.

endDoAction()

Ends the list of actions to perform for the current frame.

actionPlay()

Starts playing the Flash movie from the current frame.

actionStop()

Stops playing the Flash movie at the current frame.

actionGotoFrame(n)

Causes the Flash movie to display the specified frame and stop.

actionGetURL(url,tar)

Gets the specified URL. target indicates what to do with the content from the URL. If target is "_level0", data from the URL will replace the current Flash movie. If target is "_level1", The new URL will displayed on top of the current Flash movie.

actionNextFrame()

Goes forward one frame.

actionPrevFrame()

Goes backward one frame.

actionToggleQuality()

Toggles between high and low quality.

actionStopSounds()

Stops playing sound.

actionWaitForFrame(frame,skipcount)

If the specified frame has not been loaded, skip the specified number of actions in the action list. This can be used to show an animation while frames are being loaded.

actionSetTarget(tar)

Set the context for actions. This can be used to control other Flash movies that are playing.

actionGoToLabel(label)

Causes the Flash movie to display the frame with the given label, and stop.

Buttons:

 Buttons provide the interaction in Flash movies. The functions below are used to define the appearance and behavior of a button. In typical application, a complete button will look something like this:

 startButton(objid,FlashTypeMenuButton); 
     addButtonRecord(FlashBSHitTest|FlashBSDown| 
           FlashBSOver|FlashBSUp, 
         RECTFILLID,3000); 
     onCondition(FlashMenuEnter); 
         actionGetURL("overlay.swf","_level1"); 
     onCondition(FlashMenuExit); 
         actionGetURL("","_level1"); 
 endButton(); 

A button definition always starts with startButton and ends with endButton. There should be one or more addButtonRecord calls, and zero or more calls to onCondition followed by action elements. To make a button appear on the screen, you will have to use placeObject to position it in a frame.

startButton(id,menu)

Starts the definition of a button with the specified object id. type can have the value FlashTypeMenuButton or FlashTypePushButton. this will select whether focus can move from the button while the mouse is down. If type is FlashTypeMenuButton, focus travels, while if type is FlashTypePushButton, focus stays with the button.

addButtonRecord(state,id,depth)

Controls the location, appearance and active area of the current button. There must be one or more calls to this function to indicate what object to associate with FlashBSHitTest (the button hit test area) and FlashBSUp, FlashBSOver and FlashBSDown (the three button state bits). This uses the current mulcolor, addcolor and matrix to position and color the specified object. There can be any number of button records in a single button.

onCondition(trans)

Describes a transition used to trigger an action list. These transitions apply to buttons of type FlashTypeMenuButton:

    FlashIdletoOverUp 
    FlashOverUptoIdle 
    FlashOverUptoOverDown 
    FlashOverDowntoOverUp 
  
    FlashIdletoOverDown 
    FlashOutDowntoIdle 
  
    FlashMenuEnter =  
       (FlashIdletoOverUp|FlashIdletoOverDown) 
    FlashMenuExit =  
       (FlashOverUptoIdle|FlashOverDowntoIdle) 

These transitions apply to buttons of type FlashTypePushButton:

    FlashIdletoOverUp 
    FlashOverUptoIdle 
    FlashOverUptoOverDown 
    FlashOverDowntoOverUp 
  
    FlashOverDowntoOutDown 
    FlashOutDowntoOverDown 
    FlashOutDowntoIdle 
  
    FlashButtonEnter =  
       (FlashIdletoOverUp|FlashOutDowntoOverDown) 
    FlashButtonExit =  
       (FlashOverUptoIdle|FlashOverDowntoOutDown) 

The call to onCondition should be followed by one or more action elements as described above.

endButton()

Completes the definition of a button.

Matrix:

 pushMatrix()
Push the current transformation matrix onto the stack.

popMatrix()

Restore a previous transformation matrix.

Geometry:

 ortho(xmin=-100,xmax=100,ymin=-100,ymax=100,zmin=-100,zmax=100)

ortho2(xmin=-100,xmax=100,ymin=-100,ymax=100)

Defines a 2D orthographic mapping of user coordinates onto the current viewport. This defaults to be a one to one mapping with the area of the Flash movie. If a perspective transformation is desired, perspective may be used.

viewport(xmin,xmax,ymin,ymax)

Selects an area on the drawing surface for future drawing. This defaults to the screen area of the Flash movie.

scale(x,y,z)

Scale the current transformation.

translate(x,y,z)

Translate the current transformation.

rotate(a,axis)

Rotate the current transformation by the given angle about x, y, or z axis. The axis may be 'x', 'y', or 'z'.

polarview(dist,az,in,tw)

efines the viewer's position in polar coordinates. dist selects the distance from the viewpoint to the world space origin. Azimuth defines the azimuthal angle in the x-y plane, measured from the y axis. Incidence specifies the angle of incidence in the y-z plane, measured from the z axis. The incidence angle is the angle of the viewport relative to the z axis. Twist defines the amount that the viewpoint is to be rotated around the line of sight using the right-hand rule.

lookat(vx,vy,vz,px,py,pz,tw)

Defines a viewing transformation by giving the view position vx, vy, vz, and the coordinates of a reference point in the scene at px, py, pz. Twist controls a rotation along the viewer's z axis.

perspective(fovy,as,nr,fr)

Define a perspective projection transformation. Fovy selects the field-of-view angle in the y direction. Aspect should be set to the aspect ratio of the viewport we're drawing into. The near and far clipping planes are specified by near and far. Various distortion artifacts may appear when using a perspective projection, since Flash players only have a 2D matrix. Some of these can be quite disturbing.

posRound(doit)

This enables or disables rounding of the translation when objects are places or moved. There are times when text can be made more readable if position rounding is turned on.

Fonts:

 fontSize(h=10)
Sets the current font size to the height indicated.

fontSlant(s)

Sets the current font slant to the slant angle indicated. Positive values slant forward, negative values slant backwards.

fontTracking(t)

Sets the current font tracking to the specified value. The is used to adjust the spacing between letters in text. Positive values increase the amount of space, while negative numbers decrease the amount of space. A tracking value of 1.0 will add the currenet font height's worth of space between letters.

fontLineWidth(t)

defineFont(id,name)

Defines a font. name specifies the PostScript (be aware pstoff must be available from the libswf.a distribution) name of the font to use. This font also becomes the current font.

setFont(id)

Sets the current font to the font indicated by fontid.

textWidth(s)

Returns the width of the string using the current font and current fontsize and current font slant.

getFontInfo()

Returns the height of the capital A and lower case x using the current font and fontsize.

defineText(id,s,doc=0)

Defines a text string using the current font, current fontsize and current font slant. If docenter is 1, the word is centered in x.

Bitmaps:

 defineBitmap(id,name)
Defines a bitmap given the name of a .gif .rgb .jpeg or .fi image. The image will be converted into Flash jpeg or Flash color map format. (Be aware imgtoff must be available, part of libswf.a distribution)

getBitmapInfo(id)

Returns the size of a previously defined bitmap. xsize and ysize are the width and height in pixels.

Shapes:

 startShape(id)
Starts the definition of a complex shape. An object with the specified objid will be created.

shapeLineSolid(r,g,b,a,w)

Sets the current line style. The color is given by r, g, b, and a. width specifies the thickness of the line. If a width of 0.0 is given, no lines are drawn.

shapeFillOff()

Turns off filling.

shapeFillSolid(r,g,b,a)

Sets the current fill style to a solid fill with the the specified color.

shapeFillBitmapClip(id)

Sets the current fill mode clipped bitmap fill. Pixels from the previously defined bitmapid will be used to fill areas.

shapeFillBitmapTile(id)

Sets the current fill mode tiled bitmap fill. Pixels from the previously defined bitmapid will be used to fill areas. The image will repeat across the area.

shapeMoveTo(x,y)

This moves the current position to the given x,y.

shapeLineTo(x,y)

Draws a line from the current position to x,y. Then the current position is set to x,y.

shapeCurveTo(x1,y1,x2,y2)

Draws a quadradic bezier curve starting at the current position using x1,y1 as an off curve control point and using x2,y2 as the end point. Then the current position is set to x2,y2.

shapeCurveTo3(x1,y1,x2,y2,x3,y3)

Draws a cubic bezier curve starting at the current position using x1,y1 and x2,y2 as off curve control points and using x3,y3 as the end point. Then the current position is set to x3,y3. The cubic bezier curve is converted to the quadradic beziers used internally by Flash.

shapeArc(x,y,r,a1,a2)

Draws a circular arc from ang1 to ang2. The center of the circle is given by x, and y. r specifies the radius of the arc.

endShape()

Completes the definition of the current shape.

Sounds:

 soundRate(rate=22000)
Sets the sample rate for future sound definitions to the specified value. The only rates supported are 5500, 11000, 22000 and 44000 sampels pre second.

soundComp(nbits=2)

Selects the number of bits that sound samples should be compressed to when sounds are defined. The only values supported are 0, 2, 3, 4 and 5. The value of 0 is used to create sounds with no compression. NB: It looks like the Flash plugin on some PC's have trouble playing uncompressed sound.

defineSound(id,soundf)

Defines sound-file via sound-file. We use LibAudioFile which supports WAV, SND, AIFF, SND and multiple other formats, only restriction is 16bits per sample & mono, and sampling rate 5500, 11000, 22000 and 44000. You still need to call soundRate explicit.

defineButtonSound(id,outid,overid,downid)

Associates sounds with an already defined button. outid, overid and downid can be previously defined sounds, or 0 if no sound should be playd for the particular transition.

soundStream(soundf)

Adds sound-file to the movie starting at the current frame. (See defineSound)

startSound(id)

Starts playing the sound defined by soundid.

Aprx. 99% of all functions of libswf.a have been interfaced.

TODO: polygon-shape.

Perl Flash
6. Documentation

LIBSWF Documentation
it provides some background info how to write flash3 files using libswf.a
SWF Specifications (local)
The details
Flash Standards
Macromedia's official specs (still a lot of reverse engineering was required by various people)

Perl Flash
7. TODO

  • Sending Paul Haeberli a lot of goodies so he releases the source-code so the libswf.a can become widely available and ported to many platforms as possible. ;-)

  • Perl Flash making truly object-oriented, and higher-level interface with new API (to be defined).

  • Support of GIF, JPEG, and Sound, and PS-Fonts (without additional external progs as libswf.a does it now).

  • Very high-level scripting language, either programmed in C & YACC, or within Perl itself.

  • Flash4 and even Flash4-scripting will maybe supported as soon specs are available.

Perl Flash
8. Related Sites

Perl::Flash
Another Perl::Flash
LIBSWF
Another libswf in C++
SWF to SVG Conversion
From one animation format to another
MING
SWF library with interface to PHP, Python etc (not Perl yet)
SWFsource
Another library C++
SWFTools
Another library

                                                                                                                                   

Macromedia Flash Video LabDVD Lab

Hipocrisy of the finest:

"I agree that no single company can create all the hardware and software. Openness is central because it's the foundation of choice."
-- Steve Balmer (Microsoft) blaming Apple regarding iPhone, February 18, 2009

"Things work better when hardware and software are considered together, [..]. We control it all, we design it all, and we manufacture it all ourselves."
-- Steve Balmer announcing Windows 8 Tablet, June 19, 2012

Last update 2001/10/17

All Rights Reserved - (C) 1997 - 2012 by The Labs.Com

Top of Page

The Labs.Com