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:

Locate the following line of code:

output pixel4 dst;

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

parameter float amount;

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

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.

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

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:

Locate the following line of code:

dst.r += 0.5;

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

dst.r += (0.5 * amount);

Click the Run button to run the filter.
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.
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);

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:

Locate the following line in the code:

parameter float amount;

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

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

Click the Run button to run the filter.
Save the filter by choosing File > Export Kernel Filter for Flash Player.
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:

Locate the following three lines of code:

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

Replace the three lines shown above with the following line:

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

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:

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);

Change the line above to this:

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

Click the Run button to run the filter.
When you preview the image, the filter behaves exactly as before.
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:

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.

Tutorials & Samples

Tutorials

Samples

Pixel Bender Forum

05/09/2013	Pixel Bender Installation
02/10/2012	I Cannot get pixel bender to show in PS
05/31/2009	White Hat PBJ Decompiling
01/19/2013	Multiple Image inputs in Blendmode Shader

Pixel Bender Exchange

	Escher's Droste Effect
	4D Quaternion Julia-set Ray Tracer with Ambient Occlusion
	Zoom Blur Focus
	Raytracer

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

by Kevin Goldsmith

Content

Created

Page tools

Requirements

Prerequisite knowledge

User level

Required products

Sample files