ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Shader

Package | flash.display
Class | public class Shader
Inheritance | Shader Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

A Shader instance represents a pixel shader in ActionScript. To use a shader in your application you create a Shader instance for the shader. You then use that Shader instance in the appropriate way according to the effect you want to use it to create. For example, to use the shader as a filter, you assign the Shader instance to the `shader` property of a ShaderFilter object.

A shader defines a function that executes on all the pixels in an image, one pixel at a time. The result of each call to the function is the output color at that pixel coordinate in the image. A shader can specify one or more input images, which are images whose content can be used in determining the output of the function. A shader can also specify one or more parameters, which are input values that can be used in calculating the function output. In a single shader execution, the input and parameter values are constant. The only thing that varies is the coordinate of the pixel whose color is the function result. Shader function calls for multiple output pixel coordinates execute in parallel to improve shader execution performance.

The shader bytecode can be loaded at runtime using a URLLoader instance. The following example demonstrates loading a shader bytecode file at runtime and linking it to a Shader instance.

      var loader:URLLoader = new URLLoader();
      loader.dataFormat = URLLoaderDataFormat.BINARY;
      loader.addEventListener(Event.COMPLETE, onLoadComplete);
      loader.load(new URLRequest("myShader.hbc"));

      var shader:Shader;

      function onLoadComplete(event:Event):void {
          // Create a new shader and set the loaded data as its bytecode
          shader = new Shader();
          shader.byteCode = loader.data;

          // You can also pass the bytecode to the Shader() constructor like this:
          // shader = new Shader(loader.data);

          // do something with the shader
      }

You can also embed the shader into the SWF at compile time using the `[Embed]` metadata tag. The `[Embed]` metadata tag is only available if you use the Flex SDK to compile the SWF. The `[Embed]` tag's `source` parameter points to the shader file, and its `mimeType` parameter is `"application/octet-stream"`, as in this example:

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

      // ...

      // create a new shader and set the embedded shader as its bytecode
      var shaderShader = new Shader();
      shader.byteCode = new MyShaderClass();

      // You can also pass the bytecode to the Shader() constructor like this:
      // var shader:Shader = new Shader(new MyShaderClass());

      // do something with the shader

In either case, you link the raw shader (the `URLLoader.data` property or an instance of the `[Embed]` data class) to the Shader instance. As the previous examples demonstrate, you can do this in two ways. You can pass the shader bytecode as an argument to the `Shader()` constructor. Alternatively, you can set it as the Shader instance's `byteCode` property.

Once a Shader instance is created, it can be used in one of several ways:

- A shader fill: The output of the shader is used as a fill for content drawn with the drawing API. Pass the Shader instance as an argument to the `Graphics.beginShaderFill()` method.
- A shader filter: The output of the shader is used as a graphic filter applied to a display object. Assign the Shader instance to the `shader` property of a ShaderFilter instance.
- A blend mode: The output of the shader is rendered as the blending between two overlapping display objects. Assign the Shader instance to the `blendShader` property of the upper of the two display objects.
- Background shader processing: The shader executes in the background, avoiding the possibility of freezing the display, and dispatches an event when processing is complete. Assign the Shader instance to the `shader` property of a ShaderJob instance.

View the examples

See also

flash.display.DisplayObject.blendShader
flash.display.Graphics.beginShaderFill()
flash.display.ShaderJob
flash.filters.ShaderFilter
flash.net.URLLoader

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | byteCode : ByteArray [write-only] The raw shader bytecode for this Shader instance. | Shader
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | data : ShaderData Provides access to parameters, input images, and metadata for the Shader instance. | Shader
|  | precisionHint : String The precision of math operations performed by the shader. | Shader
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Shader(code:ByteArray = null) Creates a new Shader instance. | Shader
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

byteCode | property

`byteCode:ByteArray` [write-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The raw shader bytecode for this Shader instance.

Implementation
`public function set byteCode(value:ByteArray):void`

data | property |

`data:ShaderData` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Provides access to parameters, input images, and metadata for the Shader instance. ShaderParameter objects representing parameters for the shader, ShaderInput objects representing the input images for the shader, and other values representing the shader's metadata are dynamically added as properties of the `data` property object when the Shader instance is created. Those properties can be used to introspect the shader and to set parameter and input values.

For information about accessing and manipulating the dynamic properties of the `data` object, see the ShaderData class description.

Implementation
`public function get data():ShaderData`
`public function set data(value:ShaderData):void`

See also

flash.display.ShaderData
flash.display.ShaderInput
flash.display.ShaderParameter

precisionHint | property |

`precisionHint:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The precision of math operations performed by the shader.

The set of possible values for the `precisionHint` property is defined by the constants in the ShaderPrecision class.

The default value is `ShaderPrecision.FULL`. Setting the precision to `ShaderPrecision.FAST` can speed up math operations at the expense of precision.

Full precision mode (`ShaderPrecision.FULL`) computes all math operations to the full width of the IEEE 32-bit floating standard and provides consistent behavior on all platforms. In this mode, some math operations such as trigonometric and exponential functions can be slow.

Fast precision mode (`ShaderPrecision.FAST`) is designed for maximum performance but does not work consistently on different platforms and individual CPU configurations. In many cases, this level of precision is sufficient to create graphic effects without visible artifacts.

The following shader operations are affected and faster on an Intel processor with the SSE instruction set:

- `sin(x)`
- `cos(x)`
- `tan(x)`
- `asin(x)`
- `acos(x)`
- `atan(x)`
- `atan(x, y)`
- `exp(x)`
- `exp2(x)`
- `log(x)`
- `log2(x)`
- `pow(x, y)`
- `reciprocal(x)`
- `sqrt(x)`

It is usually faster to use fast precision mode than to use lookup tables.

Implementation
`public function get precisionHint():String`
`public function set precisionHint(value:String):void`

See also

flash.display.ShaderPrecision
Constructor Detail

Shader | () | Constructor

`public function Shader(code:ByteArray = null)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates a new Shader instance.

Parameters

| `code:ByteArray` (default = `null`)`` — The raw shader bytecode to link to the Shader.

Examples How to use examples
ShaderExample.1.as
The following example loads a shader bytecode file at runtime and creates a Shader instance linked to it.

Note that this example assumes there's a shader bytecode file named "donothing.hbc" in the same directory as the output directory for the application.

    package {
        import flash.display.Shader;
        import flash.display.Sprite;
        import flash.events.Event;
        import flash.net.URLLoader;
        import flash.net.URLLoaderDataFormat;
        import flash.net.URLRequest;

        public class LoadedShaderExample extends Sprite {

            private var loader:URLLoader;

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

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

                // do something with the Shader instance
            }
        }
    }

ShaderExample.2.as
The following example embeds a shader bytecode file by compiling it into the SWF, and creates a Shader instance linked to it.

Note that this example assumes there's a shader bytecode file named "donothing.hbc" in the same directory as the source code for the application, and that the Flex SDK is used to compile the SWF.

    package {
        import flash.display.Shader;
        import flash.display.Sprite;

        public class EmbeddedShaderExample extends Sprite {

            [Embed(source="donothing.hbc", mimeType="application/octet-stream")]
            private static var DoNothingShader:Class;

            public function EmbeddedShaderExample() {
                var shader:Shader = new Shader();
                shader.byteCode = new DoNothingShader();

                // do something with the Shader instance
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00