Ming the Tutorial

---

Fill Styles

This may very well be the most confusing thing about Ming, so I'll do some explaining (read: cheap excuses) first. The swf file format is designed to be compact and easy to render, which means that optimizations in the file representations of shapes are done up front, not in the player. And what /that/ means is that shapes are described in a way that doesn't make immediate sense to our inferior human brains.

Specifically, when defining a shape you must tell the player what's being filled in on either side of the lines you're drawing. The reason for this (and feel free to skip this paragraph, it won't be on the test) is that the flash player draws your shape in scan lines, and as it crosses each edge in your shape definition it looks at the left-side and right-side fill records to see what fill style it's going to render on the line. If the edge heads more north than south, the scan line is moving to the right side of the edge as it crosses from right to left on the line, so it starts filling with the edge's right-side fill style. If the edge were pointed more south than north, it would use the left-side fill style.

You set the shape's left-side and right-side fills with the setRightFill and setLeftFill methods. These work just like setLine did- they apply to all subsequent edges until you change the fill style again. setRightFill and setLeftFill take one argument, an SWFFill object.

SWFFill

SWFFill encompasses solid fills, gradients, and bitmaps. Instead of instantiating an SWFFill directly, though, you ask an SWFShape to create one for you by using the SWFShape's addFill method. The logic behind this is that a fill only has meaning within the context of the shape, and we'll see why shortly. addFill comes in a variety of flavors, one for each of the types of fills you can create: solid colors, bitmaps, and gradients.

$f = $s->addFill(r, g, b [,a]);

creates a solid color fill with specified red, green, and blue (and optionally alpha) components. Let's draw a plain, red square:

$s = new SWFShape();
$f = $s->addFill(r, g, b [,a]);
$s->setRightFill($f);
$s->movePenTo(-200, -200);
$s->drawLine(400, 0);
$s->drawLine(0, 400);
$s->drawLine(-400, 0);
$s->drawLine(0, -400);

We used setRightFill here because we drew the outline of the square in a clockwise fashion, hence the interior of the square is on the right side of the edges. If we had drawn the square in a counter-clockwise fashion, we would have used the setLeftFill method.

SWFBitmap

To add a bitmap fill to a shape, we use:

$f = $s->addFill(bitmap [, flags]);

where bitmap is an SWFBitmap object, created with:

$b = new SWFBitmap(filename [, maskname]);

where filename is the name of a jpeg or dbl file. A "dbl" file is a png file that's been munged with the "png2dbl" utility so that Ming can digest it more easily. (This munging is a "feature" of ming that you'll run into occasionally. The only reason we ask you to go through these extra steps is so that we won't require you to have various support libraries like libpng in order to use ming. Some day we'll have autoconf sort this mess out and you'll be able to read pngs and gifs and ttfs with a simple function call.) The png2dbl program is included in the Ming source package. Also be aware that Ming can only process baseline compressed jpeg files at this point. Baseline optimized and progressive scan jpegs won't work.

The optional maskname argument specifies a "msk" file which adds an alpha channel to a jpeg bitmap. The msk file is created with "gif2mask", also included in the Ming source package. The input gif file must be the same size as the jpeg. The resulting bitmap is opaque where the mask image is white, semi-transparent where grey, and totally transparent where black. That is, the value of the mask file pixels is used as the alpha level for the jpeg image pixels.

The flags argument can be either SWFFILL_CLIPPED_BITMAP or SWFFILL_TILED_BITMAP, and indicates whether the bitmap should be clipped (which is the default, in lieu of the flags argument) or tiled, respectively.

SWFBitmap also provides methods for retrieving the dimensions of your image:

$b->getWidth();
$b->getHeight();

which allows you to draw a rectangle the same size as your bitmap, which is quite useful, indeed.

SWFGradient

Gradients, as you already well know, are smooth transitions between colors. In Flash, gradients can be linear or radial, can contain up to eight colors, and can have transparency. To build a gradient fill, first create an SWFGradient object:

$g = new SWFGradient();

then populate it with entries:

$g->addEntry(ratio, r, g, b [,a]);

where ratio is a number on a scale from 0 to 1, and r, g, and b (and optionally a) specify the red, green, and blue (and alpha) components of the specified location in the gradient. You should (must) add them in order of increasing ratio.

For example, here's how you build a simple black-to-white gradient:

$g = new SWFGradient();
$g->addEntry(0, 0, 0, 0);
$g->addEntry(1.0, 0xff, 0xff, 0xff);

Finally, you add the gradient to your shape with:

$f = $s->addFill(gradient [, flags]);

where gradient is your freshly baked SWFGradient and flags is either SWFFILL_RADIAL_GRADIENT for a (surprise!) radial gradient, or SWFFILL_LINEAR_GRADIENT for a boring old linear gradient. If the flags argument is not given, your gradient defaults to linear and boring.

Transforming your fill

Since your swank new gradient and bitmap fills aren't much fun in their default positions, we've kindly provided the following methods for you:

$f->moveTo(x,y);

moves the fill to coordinates (x,y),

$f->rotateTo(deg);

rotates the fill to deg degrees, and

$f->scaleTo(xscale [, yscale]);

sets the fill's scaling to xscale in the x direction and yscale in the y direction. If only one argument is given, both dimensions are scaled by xscale. Lastly,

$f->skewXTo(s);
$f->skewYTo(s);

skews the fill by s on the x or y axis. An s of 0 is not skewed, an s of 1.0 is skewed at a 45 degree angle.

next: animation, at last

Macromedia(r) and Flash(tm) are trademarks or registered trademarks of Macromedia, Inc. in the United States and/or other countries.
Macromedia(r) does not sponsor, affiliate, or endorse this product and/or services.