The Back Button

Here is the full ActionScript API documentation for the latest Flash Player 10 release.

Some pages of the documentation still need to be updated, such as Sprite not inheriting the “z” axis for example (which it should). The DisplayObject page is the best class to look at for all the new 3D APIs.

Apart from a few pages needing updates, you should be able to find all the new APIs. Enjoy!

http://thebackbutton.com/misc/f10api/

Disclaimer: Beta API, APIs may change. Article based on investigatory work via code introspection.

Update: “Hydra” is now known as “Pixel Bender”

Loading Hydra Filters

The Flash API encapsulates Hydra Filters as a flash.display::Shader instances. To create a Shader instance we need to inject the byte code from a compiled Hydra filter file into it. We can do this in two familiar ways.

1) Using ActionScript 3 meta tags to inject the byte code directly into our compiled SWF.

[Embed(source="HydraFilter.hbc", mimeType="application/octet-stream")]
var Filter:Class;

var shader:Shader = new Shader(new Filter());

2) With the use of the URLLoader class which brings all the benefits of runtime loading.

function loadFilter() {
        loader = new URLLoader();
        loader.dataFormat = URLLoaderDataFormat.BINARY;
        loader.addEventListener(Event.COMPLETE, loadCompleteHandler);
        loader.load(new URLRequest("HydraFilter.hbc"));
}

function loadCompleteHandler(event:Event):void {
        var shader:Shader = new Shader(loader.data);
}

Accessing Filter Properties and Defining Input

Hydra filters usually take different parameters in order to control their output. For example, the existing BlurFilter in Flash has blurX and blurY to control the strength of its “blurring”. Flash 10 encapsulates a single filter parameter into a dynamic flash.display::ShaderParameter class instance. This class is dynamic in order for it to be able to inspect custom parameter meta-data . For example you might have minValue / maxValue set on the filter parameter (see below).

parameter float strength
 <
     description: "The strength of the blur";
     minValue: 0.0;
     maxValue: 50.0;
 >;

To set the value of a ShaderParameter, you can access the ‘value’ property of ShaderParameter and get/set Arrays on it. The size and type of data in the array all depends on the type of data the filter parameter is expecting. You can ask the ShaderParameter which flavor of Array it’s expecting by calling the ‘type’ property of ShaderParameter. In our Hydra code above you can see that the parameter is a float. A float requires a single Array element with the data type of that element being a Number. So for example, we could set … value = [10] .. and now the value of the strength is 10.

All of these ShaderParameter’s are wrapped up in another shader centric class called flash.display::ShaderData. This class is completely dynamic and gives access to ShaderParameter’s by their name. You should also be able to enumerate over them using a “for each” or “for in” loop. ShaderData also gives you assess to meta-data from the header of the Hydra filter such as its name, version, etc. So extending on the previous example, we can now say .. shaderData.strength.value = [10]

ShaderData also exposes the image input properties of a Hydra filter. For example our Hydra filter may be expecting a bitmap with an alpha channel …

input image4 src;

We represent this bitmap data input with yet another shader centric dynamic class called flash.display::ShaderInput. This class exposes some key meta-data type information about the input image property such as how many channels the bitmap should process (shaderInput.channels:int) and the index order of the property within the filter (shaderInput.index:int). The main property of this class is the ‘input’ property. Here we can set either a BitmapData, ByteArray or a Vector.<Number> instance that contains our input image. If the input is not a BitmapData type, then ‘width’ and ‘height’ properties must also be assigned to the ShaderInput instance.

Below is an example of assigning BitmapData to a ShaderInput (input image4 src) through our ShaderData:

shaderData.src.input = new BitmapData(123, 321, true, 0xFFCC00CC);

ActionScript developers should not typically need to create ShaderParameter and ShaderInput instances. All instances are created automatically to map to the requirements of the custom Hydra filter. All of these data instances should be accessible via the flash.display::Shader instance that we created before from our Hydra filter byte code. The property of Shader that gives us access to all of these parameters, inputs and meta-data is the ‘data’ property.

Example:

var shader:Shader = new Shader(hydraShaderByteCode);

trace(shader.data.name) // "DemoFilter"
trace(shader.data.version) // "1"
trace(shader.data.strength.maxValue) // 50.0
trace(shader.data.strength.description) // "The strength of the blur"
trace(shader.data.src.channels) // 4

shader.data.strength.value = [10]
shader.data.src.input =  new BitmapData(123, 321, true, 0xFFCC00CC);

Filter Rendering - BitmapFilter

Once you have encapsulated your hydra filter as a Shader, everything else starts to become very familiar. We just have one more element to add. The missing element is the flash.filters::ShaderFilter class. This class extends flash.filters::BitmapFilter, which is the base class for all existing DisplayObject filters. And so, we can now utilize our Shaders in exact same way that we would traditionally work with existing built in filters such as BlurFilter.

NOTE: BitmapFilter will automatically set the first ShaderInput for you. The DisplayObject that the BitmapFilter is assigned to becomes the first image input. Additional image inputs shall need to be defined in the usual way.

In this example below, we can how we wrap the Shader up into a ShaderFilter and apply it to a Sprite.

[Embed(source="HydraFilter.hbc", mimeType="application/octet-stream")]
var MyFilter:Class;

var shader:Shader = new Shader(hydraShaderByteCode);
var filter:ShaderFilter = new new ShaderFilter(shader);
filter.data.strength.value = [10];

var sprite:Sprite = new Sprite();
sprite.graphics.beginFill(0xcc00cc);
sprite.graphics.drawRect(0,0,123,321);
sprite.filters = [filter];

addChild(sprite);

Filter Rendering - Threaded Background Jobs

Sometimes a Hydra filter might take longer than desired to render. And because Flash currently runs on a single threaded rendering loop, a taxing filter could leave an applications UI unresponsive for an undesired amount of time. To avoid this scenario, Adobe have added the ability to perform background GPU filter rendering outside of the main thread, in the form of “jobs”.

The Flash API defines the flash.display::ShaderJob class for developers to manage this background rendering process. Here is an example using a BitmapData object as our output “bucket”.

function startJob(shader:Shader, target:BitmapData) {
        var job:ShaderJob = ShaderJob(shader, target);
        job.addEventListener(ShaderEvent.COMPLETE, shaderJobCompleteHandler)
        job.start()
}

function shaderJobCompleteHandler(e:ShaderEvent):void {
        var  result:BitmapData = e.bitmapData;
}

Flash Player 10 introduces a new core data type to store lists of data called “Vector”. It’s almost identical to the vanilla ActionScript array we use today but with the added benefit of being strictly/strongly typed. Strict typing is very beneficial, it helps create error free code while coding and compiling, allows for understandable APIs and best of all, increases code execution performance.

Vector is a top-level class just as Array is so you will not need to import it.

Below is an example of creating a Vector for the int type.

 var vec:Vector.<int> = new Vector.<int>();

Notice that we define the type of Vector with the use of the less-than/lower-than brackets.

Here is an extended example using a Vector for holding Sprites.

class Foo  {

	private var _displayChildren:Vector.<Sprite>;

	function Foo() {
		_displayChildren = new Vector.<Sprite>;
	}

	public function addChild(child:Sprite):void {
		_displayChildren.push(child);
	}

	public function removeChild(child:Sprite):void {
		var idx:int = _displayChildren.indexOf(child);
		_displayChildren.splice(idx,1);
	}

	public function get numChildren():uint {
		return _displayChildren.length;
	}

}

If you attempt to add data of the wrong type to a vector, you shall receive a “Type Coercion failed: cannot convert” error. There is however some exceptions, for example if you have a int typed Vector and you try to add a String to it using a push or unshift method, it shall perform an int(string) conversion.

intVec.push("00123")
intVec.push("hello")
trace(intVec) // 123, 0

If you try this however .. intVec[0] = “00123″ .. it shall result in a “Implicit coercion of a value of type String to an unrelated type int” error.

The only method Vector didn’t pick up from its Array cousin is sortOn. Apart from that, every method from Array is available to use to manipulate Vector.

Vector does introduce something new though, the ability to force a fixed collection length. Below is an example on how to enable fixed length.

// int Vector with fixed length of 5
var vec:Vector.<int> = new Vector.<int>(5, true);
trace(vec.fixed) // true
trace(vec) // 0, 0, 0, 0, 0

While in fixed mode, the methods push/pop/shift/unshift/splice/..etc shall not work and shall result in a “Cannot change the length of a fixed Vector.” error.

If you go out of the fixed range using the square bracket notation .. vec[15] = 1 .. you shall find this error “The index 15 is out of range 5.”.

By default, hardware accelerated composing is turned off in the current Flash Player 10 beta, and rightly so. You should only need to use GPU composing if your application really benefits from it.

If you want to enable this new feature in the new beta player, the only way to currently do this is via an attribute in your HTML/JS embed code. The attribute in question is not an addition, it is the familiar “wmode” parameter. The parameter traditionally defines how Flash content is “windowed” on a page with the current choices being “window“, “opaque” and “transparent“. With Flash Player 10, the number of choices gets bumped up to five with the addition of “direct” and “gpu“.

wmode=”direct”

“Direct” instructs the player to totally bypass the parent web browser for rendering. You might compare it to standalone players performance with the little more kick.

wmode=”gpu”

“GPU” is full hardware accelerated composing. But note, GPU mode is not a magic bullet for speeding up everything, in some scenarios it may in-fact course performance drains.

As announced in the early hours of this morning, Flash Player 10 Beta is now available to the general public via the labs.adobe.com website. This is fantastic news, but almost useless at the same time if your unable to create content for it.

Well never fear, the Adobe opensource team has release documentation on the steps you need to take in order to create your first Flash 10 content!

Check it out: opensource.adobe.com