Effects with the Pixel Bender Toolkit – Part 4: Sampling multiple pixels

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

In this article, you'll learn how to write a Pixel Bender kernel that combines multiple pixels from the same image. If you've been following along with the instructions provided since the beginning of this series, you've been building on the same file with each subsequent section. This time, we're going to start by creating a brand new filter, using the steps provided in the first article in this series.

This is the fourth 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 add parameters to create a slider interface that affects the display of the image in the preview window. You also learned how to add metadata to the parameters to ensure consistency when the effects are displayed. In this section, you'll learn how to sample multiple pixels from the same input image.

Setting up the files

If you'd like to follow along by reviewing the code in the working copy, download the sample files provided. To get started, follow these steps:

1. Choose File > New Kernel to create a new filter.
2. Load the YellowFlowers.png image and modify the kernel metadata as described in the first article in this series.
3. Click the Run button to run the filter.
4. After verifying that there are no syntax errors, choose File > Save Filter.
5. Name the file Exercise4.pbk and save it in the folder named pixel_bender on your desktop.

Adding a float parameter

In this part, you'll update the code using the syntax you learned in Part 3 of this article series. Follow these steps:

1. Find this line of code:

output pixel4 dst;

1. Immediately following that line, add a float parameter called amount:

parameter float amount;

1. Immediately following the line above, set the parameter's metadata as follows:

< minValue: -5.0; maxValue: 5.0; defaultValue: 0.0; >;

Note: Open the sample file named Exercise4FilterB.pbk to see the working example of adding the metadata described above to a float parameter.

1. After editing the code, make sure your code looks like this:

<languageVersion : 1.0;> kernel Part4Filter < namespace : "com.adobe.devnet.pixelbender"; vendor : "Kevin's Filter Factory"; version : 2; description : "Playing around with pixels"; > { input image4 src; output pixel4 dst; parameter float amount < minValue: -5.0; maxValue: 5.0; defaultValue: 0.0; >; void evaluatePixel() { dst = sampleNearest(src,outCoord()); } }

1. If you encounter any errors, compare your code to the example above. Make any necessary changes.

Sampling a second pixel

In this part, you'll learn how to write the code to sample the second pixel and store its value in a new variable that you'll declare. Follow these steps:

1. Locate the line of code that samples the input pixel:

dst = sampleNearest(src,outCoord());

1. Add a new line after the line above, and enter the following code:

pixel4 dst2 = sampleNearest(src, outCoord()+float2(amount, amount));

1. Click the Run button to run the filter. If syntax errors occur, return to the code and compare it to the code shown above. The image will not change; at this point, you haven't made any modifications to the output pixel, stored in the variable named dst.
2. If you do not encounter syntax errors, choose File > Save Filter to save the filter.

   Note: dst2 is a new variable. It is storing the value of a second pixel in the image offset in both x and y axes by the value in the parameter named amount.

3. Add the following line of code to the end of the evaluatePixel function:

dst += dst2;

1. After making these changes, examine your code to make sure it looks like this:

Dst Void evaluatePixel() { dst = sampleNearest(src, outCoord()); pixel4 dst2 = sampleNearest(src, outCoord()+float2(amount, amount)); dst += dst2; }

1. Click the Run button to run the filter.
2. After verifying that there are no syntax errors, choose File > Save Filter.
3. When you leave the slider in its default position, the image looks twice as bright. When you move the slider, it causes the image to appear offset (see Figure 1).

Figure 1. Oversaturated output image in the preview

The dark borders around two edges of the image appear when running this filter because the returned color is a transparent black when sampling pixels off the end of the image.

Scaling back the pixel values

The current implementation of the filter causes the colors to be oversaturated because the code is adding two pixel values together. In this section, you'll learn how to remedy this issue and make the saturation level return to normal.

Follow these steps:

1. Locate this line in the code:

dst += dst2;

1. Immediately following the line above, add this line of code:

dst /= 2.0;

1. Click the Run button to run the filter.
2. If there are no syntax errors, choose File > Save Filter to save the filter.

Notice that if you leave the slider in its default position, the image appears unchanged. This occurs because you updated the code to add each pixel to itself and then divide the resulting value by 2.0 (restoring it to normal saturation).

If you move the slider, the offset effect is now displayed without making the colors seem too bright (see Figure 2).

Figure 2. Offset effect applied to the image

Use the instructions provided in Part 2 of this article series to export the Pixel Bender code so that you can use it in Flash. Follow these steps:

1. Choose Build > Turn on Flash Player Warnings and Errors. This option enables filter validation for Flash Player when running filters, to help you perform troubleshooting.
2. Click the Run button to run the filter.
3. Verify that the filter runs successfully without generating any errors.
4. Choose File > Export Kernel Filter for Flash Player.

In the Export dialog box that appears, enter the name for the filter: Exercise4Filter.pbj. Save the exported file to the desktop, in the folder named pixel_bender.

Where to go from here

After experimenting with sampling multiple pixels from the same image, continue with Part 5 in this series, where you'll learn how to apply a Pixel Bender filter to an image in Flash.

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