Recipe 4.12 Scripting Masks

4.12.1 Problem

You want to create a mask at runtime.

4.12.2 Solution

Use the Drawing API to create a shape and then use MovicClip.setMask( ) to apply the mask.

4.12.3 Discussion

Masks can be used to create unique shapes or visual effects. For example, you can use masks to create wipes and transitions or interesting animations in which only the masked portion of the artwork is visible at a given time. You can even create masks that change shape over time, and use them to mask bitmapped graphics (in movie clips).

You can use any movie clip as a mask of another movie clip using the setMask( ) method. The setMask( ) method is called from the movie clip to be masked, and you should pass it a reference to the movie clip that acts as the mask:

maskedMovieClip.setMask(maskMovieClip);

In most cases, masks are simple shapes, such as rectangles or circles. You do not need to use the Drawing API to draw the mask movie clip, but it is recommended that you do so unless the mask is of an unusual shape.

First, here is an example in which a mask follows the mouse. The mask is assigned to a movie clip containing a loaded image, so the effect is that the user can see only the portion of the image over which he has positioned the mouse.

// Include the drawing methods, which are needed for the drawCircle(  ) method.
#include "DrawingMethods.as"

// Create a movie clip and a nested movie clip for loading an image. See Recipe 15.3
// for more information on the need for creating nested movie clips when loading
// external JPEGs.
_root.createEmptyMovieClip("image_mc", 1);
_root.image_mc.createEmptyMovieClip("imageHolder_mc", 1);

// Load the image into the movie clip. You can use this URL if you want, but it will
// work only while you are using the test or standalone players. See Recipe 15.3 for
// more information on loading JPEGs.
image_mc.imageHolder_mc.loadMovie("http://www.person13.com/ascb/data/images/image1.jpg");

// Draw the masking movie clip.
_root.createEmptyMovieClip("mask_mc", 2);
mask_mc.lineStyle(3, 0x000000, 0);
mask_mc.beginFill(0, 100);
mask_mc.drawCircle(60);
mask_mc.endFill(  );

// Call the setMask(  ) method on the masked movie clip and pass it the masking movie
// clip as a parameter.
image_mc.setMask(mask_mc);

// Call the startDrag(  ) method of the masking movie clip so that the mask can be
// moved with the cursor.
mask_mc.startDrag(true);

Next, here is an example in which a mask is used to create a wipe transition between two loaded images.

#include "DrawingMethods.as"

// Create a movie clip and a nested movie clip and load the first image into it.
_root.createEmptyMovieClip("image0_mc", 1);
_root.image0_mc.createEmptyMovieClip("imageHolder_mc", 1);
image0_mc.imageHolder_mc.loadMovie("http://www.person13.com/ascb/data/images/image1.jpg");

// Create another movie clip and nested movie clip and load the second image into it.
// Both image0_mc and image1_mc are created at (0,0). This means that they will
// overlap. This is what we want.
_root.createEmptyMovieClip("image1_mc", 2);
_root.image1_mc.createEmptyMovieClip("imageHolder_mc", 1);
image1_mc.imageHolder_mc.loadMovie("http://www.person13.com/ascb/data/images/image2.jpg");


// Draw the masking movie clip. The dimensions of the images are 640   x   480 (if you
// load the images using the URLs provided) and so the mask should be a rectangle
// with the same dimensions.
_root.createEmptyMovieClip("mask_mc", 3);
mask_mc.lineStyle(3, 0x000000, 0);
mask_mc.beginFill(0, 100);
mask_mc.drawRectangle(640, 480);
mask_mc.endFill(  );

// Position the mask so that it is off to the left side of the Stage.
mask_mc._x = -320;
mask_mc._y = 240;

// Call the setMask(  ) method to set mask_mc as the mask for image1_mc. This causes
// image0_mc to display initially, even though it is below image1_mc.
image1_mc.setMask(mask_mc);

// Define an event handler method for image0_mc so that the mask movie clip moves
// when the user clicks on image0_mc.
image0_mc.onRelease = function (  ) {

  // Use an onEnterFrame(  ) event handler method to move the mask. This assumes you
  // have the default frames per second setting of 12.
  _root.mask_mc.onEnterFrame = function (  ) {

    // Move the mask to the right by 12 pixels.
    this._x += 12;

    // If the mask is fully masking the image, then delete the onEnterFrame(  ) method.
    if (this._x >= 320) {
      this._x = 320;
      delete this.onEnterFrame;
    }
  }
}

If you use the URLs provided in this example, then the images that are loaded have dimensions of 640 x 480. Therefore, you might need to increase the dimensions of your movie to see the full images. If you use your own images, they must be of the same resolution for the effect to work as described.