Effects with the Pixel Bender Toolkit – Part 8: Controlling the displacement filter with mouse positioning

Requirements

User level

Beginning

Required products

• Flash Player 10 and later
• Flash Professional (Download trial)
• Pixel Bender Toolkit (Macintosh)
• Pixel Bender Toolkit (Windows)

Sample files

• pixel_bender_08.zip

In this article, you'll add a type of interactivity that animates a Pixel Bender filter to correspond to changing mouse positions.

This is the eighth installment in this series of articles about using the Pixel Bender Toolkit to create visual effects with bitmap images. In the previous section, you learned how to update the displacement filter to enable it to move in all directions. You also updated the parameters to make the displacement filter effect more dramatic when you moved the slider controls.

In this section, you'll update the ActionScript code in the Flash file to control the displacement filter parameter with changing positions of the mouse.

Setting up the files

Before you begin, if you'd like to continue experimenting with the previous version of the project, you can add a second slider to control the float2 parameter that you just added to the Displacement filter. That process is fairly straightforward and it is always a good idea to practice when learning a new concept.

In this part of the series, we'll discuss adding another type of interactivity to control the filter effect; this time you'll track the placement of the cursor and use it to animate the displacement filter.

Before updating the ActionScript, set the file up in Flash in preparation for the code edits. Follow these steps:

1. Launch Flash CS4 (or make it active if it is already open).
2. Open the file named Exercise5.fla from the pixel_bender folder on your desktop.

   (If you are just beginning to follow along with this section and didn't complete the files in the previous parts of this series, download the sample files provided. Uncompress the ZIP file and save the contents into a folder named pixel_bender that you create on your desktop. Open the file named exercise8A.fla to begin following along at this point.)

3. When you open the FLA file, you'll see a flower image and a slider control on the Stage.
4. Choose Window > Actions to open the Actions panel (if it is not already open). Alternatively, expand the panel if it was open but collapsed.
5. Select Frame 1 in the Timeline and review the code in the Script window. It should look similar to the ActionScript shown below:

import fl.events.SliderEvent; var urlRequest:URLRequest = new URLRequest("Exercise4Filter.pbj"); var urlLoader:URLLoader = new URLLoader(); urlLoader.dataFormat = URLLoaderDataFormat.BINARY; urlLoader.addEventListener( Event.COMPLETE, applyFilter ); urlLoader.load(urlRequest); var shader:Shader; var shaderFilter:ShaderFilter; function applyFilter( event:Event ):void { urlLoader.removeEventListener( Event.COMPLETE, applyFilter ); shader = new Shader( event.target.data ); shaderFilter = new ShaderFilter( shader ); // set up slider amount_slider.minimum = shader.data.amount.minValue; amount_slider.maximum = shader.data.amount.maxValue; amount_slider.value = shader.data.amount.defaultValue; amount_slider.snapInterval = Math.abs(amount_slider.minimum - amount_slider.maximum) / 100; amount_slider.liveDragging = true; amount_slider.addEventListener( SliderEvent.CHANGE, updateFilter ); flower.filters = [ shaderFilter ]; } function updateFilter( event:SliderEvent ):void { shader.data.amount.value = [amount_slider.value]; flower.filters = [ shaderFilter ]; }

1. If desired, rearrange the panels in the Flash authoring environment so that you can see both the Stage and the Actions panel simultaneously (see Figure 1).

Figure 1. Panels arranged in the Flash workspace so that you can edit both the code and the elements on the Stage

Deleting the Slider component

Follow these steps to remove the slider from the Flash file:

1. Select the instance of the slider control on the Stage.
2. Press the Delete key to delete it.
3. Open the Actions panel and review the code in the Script window. Remove the line of code at the top that imports the SliderEvent:

import fl.events.SliderEvent;

1. Remove the slider setup code located in the applyFilter function. After making these changes, the applyFilter function should look like this:

function applyFilter( event:Event ):void { urlLoader.removeEventListener( Event.COMPLETE, applyFilter ); shader = new Shader( event.target.data ); shaderFilter = new ShaderFilter( shader ); flower.filters = [ shaderFilter ]; }

1. Locate the beginning of the updateFilter function:

function updateFilter( event:SliderEvent ):void

1. Change the event type from a SliderEvent to the generic type Event:

function updateFilter( event:Event ):void

1. Locate the line that sets the amount parameter in the Pixel Bender filter. You need to disable the code, but don't delete this line; you'll re-enable it later:

shader.data.amount.value = [amount_slider.value];

Instead, just type two forward slashes before the line to comment it out:

// shader.data.amount.value = [amount_slider.value];

After making these changes, your ActionScript code should look like this:

var urlRequest:URLRequest = new URLRequest("Exercise4Filter.pbj"); var urlLoader:URLLoader = new URLLoader(); urlLoader.dataFormat = URLLoaderDataFormat.BINARY; urlLoader.addEventListener( Event.COMPLETE, applyFilter ); urlLoader.load(urlRequest); var shader:Shader; var shaderFilter:ShaderFilter; function applyFilter( event:Event ):void { urlLoader.removeEventListener( Event.COMPLETE, applyFilter ); shader = new Shader( event.target.data ); shaderFilter = new ShaderFilter( shader ); flower.filters = [ shaderFilter ]; } function updateFilter( event:Event ):void { // shader.data.amount.value = [amount_slider.value]; flower.filters = [ shaderFilter ]; }

1. Choose Debug > Debug Movie.
2. If you do not encounter any syntax errors, Flash Player launches to display the yellow flowers image. This time the SWF does not show a slider. The image appears normally because the filter is not applied.
3. Choose File > Save. Save the Flash project as Exercise8.fla in the pixel_bender folder on your desktop.

Controlling the filter effect with mouse interactions

Now that you've removed the slider control, the next task involves adding code to control the filter effects by tracking the cursor. This step allows the filter to be reapplied and creates a more interactive experience for the user:

1. Choose Window > Actions to access the Actions panel.
2. In the Script window, edit the linked PBJ file, changing the reference from Exercise4Filter.pbj to Exercise7Filter.pbj.
3. Add the following line to the end of the applyFilter function, before the closing curly brace:

flower.addEventListener( Event.ENTER_FRAME, updateFilter );

1. Locate this commented line of code in the body of the updateFilter function:

// shader.data.amount.value = [amount_slider.value]; flower.filters = [ shaderFilter ];

1. Change the body of the updateFilter function to look like this:

var xOffset:Number = flower.width/2 - flower.mouseX; var yOffset:Number = flower.height/2 - flower.mouseY; shader.data.amount.value = [ xOffset, yOffset ]; flower.filters = [ shaderFilter ];

The code above retrieves the current mouse position, determines its offset (based on the center of the image), and uses the value to set the offset as the parameter value to the Pixel Bender filter.

1. Choose Debug > Debug Movie. If you do not encounter any syntax errors, Flash Player launches to display the yellow flowers image.
2. Interact with the SWF by moving your cursor over it. Although the filter is running, when you test the SWF you'll notice that the parameter values are ignoring the minimum and maximum values.

   Note: Because Flash player does not enforce the minValue or maxValues on the filter, it is a best practice to take these values into account in your ActionScript code.

3. Choose File > Save. Name the Flash project as Exercise8.fla and save it in the folder called pixel_bender on your desktop.

Incorporating the minimum and maximum metadata

In this section, you'll update the code to enable the filter to be constrained by the minimum and maximum values that are set in the Pixel Bender metadata. Follow these steps:

1. Change the code in the updateFilter function, to match the example below:

function updateFilter( event:Event ):void { var xOffset:Number = flower.width/2 - flower.mouseX; var yOffset:Number = flower.height/2 - flower.mouseY; xOffset = Math.min( xOffset, shader.data.amount.maxValue[0] ); xOffset = Math.max( xOffset, shader.data.amount.minValue[0] ); yOffset = Math.min( yOffset, shader.data.amount.maxValue[1] ); yOffset = Math.max( yOffset, shader.data.amount.minValue[1] ); shader.data.amount.value = [ xOffset, yOffset ]; flower.filters = [ shaderFilter ]; }

This code forces the parameter values set by the ActionScript code to stay within the ranges specified by the Pixel Bender code.

1. Choose Debug > Debug Movie.
2. If you do not encounter any syntax errors, Flash Player launches to display the yellow flower image.
3. Interact with the SWF by moving your mouse to see the filter running. Notice how the effect is constrained to the minimum and maximum values set in the Pixel Bender metadata.
4. Save the Flash project in the pixel_bender folder on your desktop.

Where to go from here

After testing and reviewing the code from the SWF, continue with Part 9 in this series, where you'll learn how to create a Pixel Bender kernel that integrates values from multiple image sources.

Check out the following resources to learn more about working with the Pixel Bender Toolkit:

• Pixel Bender forum
• Pixel Bender basics for Flash
• Pixel Bender basics for Flex and AIR