| Package | flash.display |
| Class | public class ShaderJob |
| Inheritance | ShaderJob  EventDispatcher Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
There are two primary reasons for using a shader in stand-alone mode:
- Processing non-image data: Using a ShaderJob instance you have control over input values and over how the shader result is used. The shader can return the result as binary data or number data instead of image data.
- Background processing: Some shaders are complex and require a notable amount of time to execute. Executing a complex shader in the main execution of an application could slow down other parts of the application such as user interaction or updating the screen. Using a ShaderJob instance, you can execute the shader in the background. When the shader is executed in this way, the shader operation runs separate from the main execution of the application.
The shader property (or constructor parameter) specifies the
Shader instance representing the shader that is used for the operation. You
provide any parameter or input that the shader expects using the
associated ShaderParameter or ShaderInput instance.
Before execution a ShaderJob operation, you provide an object into which the
result is written, by setting it as the value of the target property.
When the shader operation completes the result is written into the target object.
To begin a background shader operation,
call the start() method. When the operation finishes the result is
written into the target object. At that point the ShaderJob
instance dispatches a complete
event, notifying listeners that the result is available.
To execute a shader synchronously (that is, not running in the background), call
the start() method and pass true as an argument. The shader
runs in the main execution thread and your code pauses until the operation completes. When
it finishes the result is written into the target object. At that point
the application continues running at the next line of code.
More examples
Related API Elements
Hide Inherited Public Properties
Show Inherited Public Properties| Property | Defined By | ||
|---|---|---|---|
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| height : int
The height of the result data in the target if it is
a ByteArray or Vector.<Number> instance. | ShaderJob | ||
| progress : Number [read-only]
The progress of a running shader. | ShaderJob | ||
| shader : Shader
The shader that's used for the operation. | ShaderJob | ||
| target : Object
The object into which the result of the shader operation is written. | ShaderJob | ||
| width : int
The width of the result data in the target if it is
a ByteArray or Vector.<Number> instance. | ShaderJob | ||
| Method | Defined By | ||
|---|---|---|---|
| ShaderJob | |||
| addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener
receives notification of an event. | EventDispatcher | |
Cancels the currently running shader operation. | ShaderJob | ||
|
Dispatches an event into the event flow. | EventDispatcher | |
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
Indicates whether an object has a specified property defined. | Object | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
Starts a shader operation in synchronous or asynchronous mode, according to the
value of the waitForCompletion parameter. | ShaderJob | ||
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | ||
| Dispatched when a ShaderJob that executes asynchronously finishes processing the data using the shader. | ShaderJob | |||
| [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | ||
height | property |
height:int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
The height of the result data in the target if it is
a ByteArray or Vector.<Number> instance. The size of the
ByteArray or Vector.<Number> instance is enlarged
if necessary and existing data is overwritten.
Implementation
public function get height():int public function set height(value:int):voidprogress | property |
progress:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
The progress of a running shader. This property is a value from 0 through 1. Zero is the initial value (0% complete). One indicates that the shader has completed its operation.
If the cancel() method is called this property becomes
undefined, and its value cannot be used reliably until the
shader operation starts again.
Implementation
public function get progress():Numbershader | property |
shader:Shader| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
The shader that's used for the operation. Any input or parameter that the
shader expects must be provided using the ShaderInput or ShaderParameter
property of the Shader instance's data property. An input must
be provided using its corresponding ShaderInput even if it is the same as
the target object.
To process a ByteArray containing a linear array of data (as opposed to
image data) set the corresponding ShaderInput instance's height
to 1 and width to the number of 32-bit floating-point values in
the ByteArray. In that case, the input in the shader must be defined with
the image1 data type.
Implementation
public function get shader():Shader public function set shader(value:Shader):voidRelated API Elements
target | property |
target:Object| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
The object into which the result of the shader operation is written. This object must be a BitmapData, ByteArray, or Vector.<Number> instance.
Implementation
public function get target():Object public function set target(value:Object):voidwidth | property |
width:int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
The width of the result data in the target if it is
a ByteArray or Vector.<Number> instance. The size of the
ByteArray or Vector.<Number> instance is enlarged
if necessary and existing data is overwritten.
Implementation
public function get width():int public function set width(value:int):voidShaderJob | () | Constructor |
public function ShaderJob(shader:Shader = null, target:Object = null, width:int = 0, height:int = 0)| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
Parameters
shader:Shader (default = null) | |
target:Object (default = null) | |
width:int (default = 0)target if it is
a ByteArray or Vector.<Number> instance. The size of the
ByteArray or Vector.<Number> instance is enlarged
if necessary and existing data is overwritten.
| |
height:int (default = 0)target if it is
a ByteArray or Vector.<Number> instance. The size of the
ByteArray or Vector.<Number> instance is enlarged
if necessary and existing data is overwritten.
|
cancel | () | method |
public function cancel():void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
Cancels the currently running shader operation. Any result data that is already
computed is discarded. The complete event is not dispatched.
Calling cancel() multiple times has no additional effect.
start | () | method |
public function start(waitForCompletion:Boolean = false):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
Starts a shader operation in synchronous or asynchronous mode, according to the
value of the waitForCompletion parameter.
In asynchronous mode (when waitForCompletion
is false), which is the default, the
ShaderJob execution runs in the background. The shader operation does not affect the
responsiveness of the display or other operations. In asynchronous mode the start()
call returns immediately and the program continues with the next line of code. When the asynchronous
shader operation finishes, the result is available and the complete
event is dispatched.
Only one background ShaderJob operation
executes at a time. Shader operations are held in a queue until they execute.
If you call the start() method while a shader
operation is executing, the additional operation is added to the end of the queue.
Later, when its turn comes, it executes.
To execute a shader operation in synchronous mode, call start() with a
true value for the waitForCompletion parameter (the only parameter).
Your code pauses at the point where start() is called until the shader operation
completes. At that point the result is available and execution continues with the next line
of code.
When you call the start() method the Shader instance in the shader
property is copied internally. The
shader operation uses that internal copy, not a reference to the original shader. Any changes
made to the shader, such as changing a parameter value, input, or bytecode, are not applied
to the copied shader that's used for the shader processing. To incorporate shader changes
into the shader processing, call the cancel() method
(if necessary) and call the start() method again to restart the shader processing.
While a shader operation is executing, the target object's value
is not changed. When the operation finishes (and the complete
event is dispatched in asynchronous mode) the entire result is written to the
target object at one time. If the target object is a
BitmapData instance and its dispose() method is called
before the operation finishes, the complete event is still
dispatched in asynchronous mode. However, the result data is not
written to the BitmapData object because it is in a disposed state.
Parameters
waitForCompletion:Boolean (default = false)false, the default) or in the main program
execution (true).
|
Events
complete: — Dispatched when the operation finishes, if the
start() method is called with a
waitForCompletion argument of true.
|
Throws
ArgumentError — When the target property is null or is not
a BitmapData, ByteArray, or Vector.<Number> instance.
| |
ArgumentError — When the shader specifies an image input that isn't provided.
| |
ArgumentError — When a ByteArray or Vector.<Number> instance is used as
an input and the width
and height properties aren't specified for the
ShaderInput, or the specified values don't match the amount of
data in the input object. See the ShaderInput.input
property for more information.
|
complete | Event |
flash.events.ShaderEventproperty ShaderEvent.type =
flash.events.ShaderEvent.COMPLETE| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5 |
Dispatched when a ShaderJob that executes asynchronously finishes processing
the data using the shader. A ShaderJob instance executes asynchronously when the
start() method is called with a false value for the
waitForCompletion parameter.
type property of a complete event object.
This event has the following properties:
| Property | Value |
|---|---|
bubbles | false |
bitmapData | The BitmapData object
containing the result of the operation that finished (or
null if the target wasn't a BitmapData object). |
byteArray | The ByteArray object containing
the result of the operation that finished (or null if
the target wasn't a ByteArray object). |
cancelable | false; there is
no default behavior to cancel. |
currentTarget | The object that is actively processing the event object with an event listener. |
target | The ShaderJob object reporting completion. |
vector | The Vector.<Number> instance
containing the result of the operation that finished (or null if
the target wasn't a Vector.<Number> instance). |
Mon Apr 10 2017, 12:28 PM -07:00