Can some one explain to me why the behavior of this ActionScript code is auto scale?

I'm new to AS3 and I'm doing some custom video player video project for AIR. While I was studying the simple examples (non-StageVideo) on how to play videos, I've encountered a unique situation where I got an awesome auto-scaling (stretch-to-fit) to window behavior from Flash.

Whenever I set the SWF directive's width and height equal to the width and height of the flash.media.Video object I'm creating. It does the auto-scaling, stretch-to-fit, resizable behavior. Like so:

// SWF directive placed before the class declaration of the main class
[SWF( width="1024", height="576", backgroundColor="000000", visible="true" )]

// somewhere in my initialization
myvid = new Video();
with( myvid )
{
    x = 0;
    y = 0;
    width = 1024; // if I set this wxh equal to wxh in the SWF directive it auto-scales!
    height = 576;
}
myvid.attachNetStream( myns );
addChild( myvid ); // must come after instancing of video and netstream, and attach to make the auto-scale work
myvid.play( "somevideo.flv" );

Even if I set the width to 16 and height to 9 on both it scales and fits perfectly on the size of my window. Can some explain me this behavior? None of what I read in the documentation mentioned this.

Don't get me wrong, I like this behavior! :) It made things easier for me. But code-wise I need to understand why is this happening as the code I set had nothing to do with auto-scaling.

Also, what the heck are directives for? Don't they just have pure ActionScript 3 equivalent? They look hackish to me.

I think the behavior you're describing is caused by the scale parameter in the HTML embed of the Flash. Generally this defaults to showAll, scaling the Flash up to fit the container.

There are two different sizes: the size of the container (the block in the HTML page) and the size of the Flash content (what you specify in the SWF tag). The scale mode decides the behavior when these sizes don't match. You can control this behavior either by tweaking that embed parameter, or from AS3 directly using stage.scaleMode:

import flash.display.StageScaleMode;
// scale the content to fit the container, maintaing aspect ratio
stage.scaleMode = StageScaleMode.SHOW_ALL;
// disable scaling
stage.scaleMode = StageScaleMode.NO_SCALE;

If you want to use the scale mode to your advantage, I would set the width of your Video to match the stage dimensions like so:

myvid.width = stage.stageWidth;
myvid.height = stage.stageHeight;

This way you avoid having to repeat the SWF width and height.

The directives mostly specify some metadata or instructions for the compiler. The SWF tag in particular specifies the info in the SWF header, such as desired width, height, framerate. Mostly these are just some suggestions to the player + container about how the file should be displayed. Some of them can be changed in code (stage.frameRate = 50;). Another metatag is Embed, which will bundle some assets into the SWF (particularly handy if you want to embed some binary data).