Effects with the Pixel Bender Toolkit – Part 3: Adding parameters to filters

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_03.zip

In this article, you will learn how to add a parameter to a kernel so you can animate a Pixel Bender filter or adjust the effects while the filter is running. You will also learn how to use Pixel Bender's vector types to make the math easier to maintain.

This is the third 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 manipulate the red, green, and blue color channels to affect the image in the preview window. This section shows you how to leverage a powerful way to control effects: parameters. By adding parameters and metadata to filters you create with the Pixel Bender Toolkit, you can control the amount of the filter effect with a slider interface.

Setting up the files

If you have been following along since the beginning of this series, you can continue working with the same file. Otherwise, download the sample files provided. Open the Exercise3FilterA.pbk file in the Pixel Bender IDE.

The vintage tone filter that you developed in the last part looks something like this:

<languageVersion : 1.0;> kernel Part3Filter < namespace : "com.adobe.devnet.pixelbender"; vendor : "Kevin's Filter Factory"; version : 1; description : "Playing around with pixels"; > { input image4 src; output pixel4 dst; void evaluatePixel() { dst = sampleNearest(src,outCoord()); dst.r += 0.5; dst.b -= 0.4; dst.g -= 0.1; } }

Adding a float parameter

Now that you have loaded the code (either by opening the file you created in Part 2 or by opening the sample file), you are ready to edit the code to add a parameter.

Follow these steps to add a float parameter to the filter:

1. Locate the following line of code:

output pixel4 dst;

1. Add a new line immediately following the line above. Add this code:

parameter float amount;

1. Click the Run button to run the filter. A slider appears in the right side panel (see Figure 1).
2. Test the slider by moving it.

Figure 1. Slider appearing on the right side after editing the code

Notice that the image doesn't change. Although it is present, the slider value is not used in the Pixel Bender kernel yet. You'll hook this up in the next section.

Incorporating the parameter into your filter

Now that you've added the slider, the next part involves editing the code to add the parameter to your filter to make the slider adjust the settings of the effect. Follow these steps:

1. Locate the following line of code:

dst.r += 0.5;

1. Change the line shown above to match the code example shown below:

dst.r += (0.5 * amount);

1. Click the Run button to run the filter.
2. This time, the image in the preview window will change. Experiment by moving the slider and notice how the slider affects the display of the image.
3. Try modulating the other channels by changing the amount parameter. Make the following changes to make the evaluatePixel function look like this:

dst = sampleNearest(src,outCoord()); dst.r += (0.5*amount); dst.b -= (0.4*amount); dst.g -= (0.1*amount);

1. Click the Run button to run the filter.

As you move the slider in the right-hand panel, the image changes more significantly as the slider moves. This occurs because all three channels are now modified by the parameter. When the slider is moved to the left, there is no effect applied to the image. When the slider is moved to the right, the effect is fully applied.

Setting the parameter metadata

In this section, you'll add metadata to the new parameter you just created. The completed version of this code is called Exercise3FilterE.pbk in the sample files. Follow these steps:

1. Locate the following line in the code:

parameter float amount;

1. Change the float parameter declaration by adding the new code shown below:

parameter float amount < minValue: -1.0; maxValue: 1.0; defaultValue: 0.0; >;

1. Click the Run button to run the filter.

   The default position of the slider in the right hand panel is now in the middle. If you move the slider to the left, you will see the filter being applied in inverse. If you move the slider to the right, the effect is applied as it was before.

   Note: Adding parameter metadata is not required; the parameter will work without it. However, if you do not set the metadata, each application will use its own default minimum, maximum, and default values. It is a best practice to always set this metadata to control parameters and get consistent results.

2. Save the filter by choosing File > Export Kernel Filter for Flash Player.
3. In the dialog box that appears, name the file Exercise3Filter.pbj and save it inside the pixel_bender folder on your desktop.

Using vectors to simplify the math

In this section, you'll learn how to incorporate vectors into the filter. Adding vectors is easy in the Pixel Bender Toolkit:

1. Locate the following three lines of code:

dst.r += (0.5*amount); dst.b -= (0.4*amount); dst.g -= (0.1*amount);

1. Replace the three lines shown above with the following line:

dst += float4(0.5*amount, -0.4*amount, -0.1*amount, 0.0);

1. Click the Run button to run the filter. The filter behaves exactly as before.

Instead of modifying the first three values of the dst vector individually, you are now creating a new vector and adding it to dst. The extra 0.0 float value at the end is because vectors have to be the same size for the arithmetic operation to be legal. Also notice that you must type the value as 0.0 and not 0 in the code. Pixel Bender will not automatically convert types for you; you always have to use the correct types or an error will occur.

Simplifying the math

In this section, you'll learn a strategy to make the math in the equation a bit more manageable. Follow these steps:

1. Locate the following line in the code window; this is the line that adds the vector:

dst += float4(0.5*amount, -0.4*amount, -0.1*amount, 0.0);

1. Change the line above to this:

dst += float4(0.5, -0.1, -0.4, 0.0) * amount;

1. Click the Run button to run the filter.
2. When you preview the image, the filter behaves exactly as before.
3. Save the filter.

Note: Multiplying a vector by a number is the same thing as multiplying every element of the vector by that number.

Where to go from here

After familiarizing yourself with the Pixel Bender interface, continue with Part 4 in this series, where you'll learn how to write the code to sample multiple pixels from the same image.

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