      *                  applied to this rectangle, will produce a rectangle
      *                  equal to the target rectangle.
      * @param target    The target rectangle.
-     * @param outMatrix An existing <code>Matrix</code> to store the result
-     *                  in. If none provided, will create a new
-     *                  <code>Matrix</code> object.
-     * @return The result stored in <code>outMatrix</code> if it exists, or
-     *         a new <code>Matrix</code> object otherwise.
+     * @param output    A reference to a Matrix in which to store the
+     *                  result. If this is null, a new Matrix will be
+     *                  constructed and returned.
+     * @return          The Matrix passed into <code>output</code>, or a
+     *                  new Matrix, with the calculated result. If source
+     *                  has a width or height of zero, returns
+     *                  <code>null</code>.
      */
     public static function getRectTransform(source:Rectangle, target:Rectangle, outMatrix:Matrix = null):Matrix
     {

     * @param rounding Rounds the calculated values of <code>x</code>,
     *                 <code>y</code>, <code>width</code> and
     *                 <code>height</code> to the nearest whole number.
     * @return         Nothing. The <code>Rectangle</code> passed into the
     *                 source argument is modified.
     */
    public static function fitRect(source:Rectangle, target:Rectangle,
                                   mode:String = "fit",
                                   xAlign:Number = 0.5,
                                   yAlign:Number = 0.5,
                                   rounding:Boolean = false):void
    {
        var scale:Number;

        if (mode == MODE_FILL)
        {
            scale = Math.max(target.width / source.width,
                             target.height / source.height);
        }
        else
        {
            scale = Math.min(target.width / source.width,
                             target.height / source.height);
        }

        if (rounding)
        {
            source.width =  int(.5 + source.width * scale);
            source.height = int(.5 + source.height * scale);
        }
        else
        {
            source.height *= scale;
            source.width *= scale;
        }
        alignRects(source, target, xAlign, yAlign);
        if (rounding)
        {
            source.x = int(.5 + source.x);
            source.y = int(.5 + source.y);
        }
    }

    /**
     * Aligns one rectangle's edges relative to another rectangle's.
     *
     * @param source   The source rectangle. Its <code>x</code> and
     *                 <code>y</code> properties are modified.
     *                 To keep a copy of the source rectangle,
     *                 the caller should clone it themselves.
     * @param target   The rectangle to align <code>source</code> to.
     * @param xAlign   X alignment. A number from 0 to 1. 0 aligns left
     *                 edges, 1 aligns right edges, and 0.5 centres



/**
 * Utility functions for scaling a source rectangular area to fit inside a
 * target area, while maintaining the aspect ratio of the source.
 * <code>MODE_FIT</code> calculates a rectangle that is equal to or smaller
 * than the target.  <code>MODE_FILL</code> is always equal or larger.
 */
public class FitUtil
{
    /**
     * Constant value that directs the <code>fitRect</code> function to
     * calculate a result that is always smaller or equal to the target
     * area. One of the axes of the result may not fully span the target.
     */
    public static const MODE_FIT:String = "fit";

    /**
     * Constant value that directs the <code>fitRect</code> function to
     * calculate a result that is always larget or equal to the target
     * area. One of the axes of the result may exceed the target area.
     */
    public static const MODE_FILL:String = "fill";

    /**
     * Scales one rectangle to fit or fill another rectangle.
     *
     * @param source   The source rectangle.
     * @param target   The rectangle to fit <code>source</code> into.
     * @param mode     Calculation mode: <code>MODE_FIT</code> or
     *                 <code>MODE_FILL</code>
