Animating a particle system using Pixel Bender

Although the Adobe Pixel Bender kernel language was originally designed to process image and video files, its fast, multi-threaded execution in Adobe Flash Player makes it useful for general math processing. In this tutorial you'll examine a sample project to develop a particle system. You'll learn how to encode general-purpose data for Pixel Bender with a ByteArray, process the data using the ShaderJob class in the Flash runtime, and then return the results of the data.

To get started, create a new project and set up the related files. If you haven't already, be sure to download the sample files folder linked at the beginning of this article. Uncompress the ZIP file and place the folder in a convenient location, such as your desktop. Follow these steps to set up the project:

1. Launch Flash Builder 4.
2. Create a new Flex Project with the new Flex Project Wizard by choosing File > New > Flex Project. Enter the following settings:
• In the project name field, enter ParticleSystemExercise
• For the Application Type, choose Desktop
• For the Flex SDK Version, choose either Flex 4.1 or Flex 4.0
• For Server Technology, choose None/Other
3. After applying these settings, click Finish.

The next task involves creating a folder in your project named kernels:

1. Select the ParticleSystemExercise folder located in the Package Explorer tab.
2. From the File menu, select New > Folder.
3. In the Folder Name field, enter kernels.
4. Click Finish.

To finish the setup process, create the folder that will contain the bytecode file:

1. Select the ParticleSystemExercise folder located in the Package Explorer tab.
2. From the File menu, select New > Folder.
3. In the Folder Name field, enter pbjs.
4. Click Finish.

The Flash Builder project is now ready to go. In the next section, you'll learn how to add the code to create the first version of the project.

This section shows you how to update the existing code to add the project code. Follow these steps:

1. Replace the text in the ParticleSystemExercise.mxml file with the following code:

The code shown above defines three functions, a member variable, and a constant in the <fx:script> block. The constant PARTICLE_COUNT specifies the number of particles that the application will generate. Each particle's position and velocity is stored in the ByteArray named m_bytes. The function initializeByteArray adds four float values for each particle: the x position, the y position, the x velocity, and the y velocity to the m_bytes ByteArray object.

The position is set to a random position within the control. Each velocity value is randomized to a value between –1 and 1. The draw function creates a BitmapData object and then steps through the m_bytes ByteArray object, reading the x and y position values and setting the pixel they represent to a random color.

Finally, the applicationCompleteHandler is an event handler for the applicationComplete event. The applicationCompleteHandler function initializes the m_bytes object and then uses the draw function to display the particle system. Run the ParticleSystemExercise application. You'll see something similar to Figure 1.

In this section, you add the code to set the position of the particles on the Stage. Follow these steps:

1. Launch the Pixel Bender Toolkit.
2. Create a new kernel by selecting File > New Kernel.
3. Rename the kernel to Particle.
4. Set the namespace to com.adobe.max10.
5. Set the vendor to your name (or the name of your company).
6. In the evaluatePixel function, after the sampleNearest line, add the following code:

The Pixel Bender kernel is reading four float values of the ByteArray at a time. The four floating-point values are mapped to the colors in a pixel, so the red and green components of the pixel correspond to the x and y coordinates of the particle and the blue and alpha components of the pixel correspond to the velocity values.

The kernel should now look something like this:

8. Save the kernel as Particle.pbk in the kernels directory that you created in Step 2.
9. Export the bytecode file as Particle.pbj to the pbjs directory by choosing File > Export Filter for Flash Player.

Here you add the code that animates the particles in the application. Follow these steps:

1. Switch back to Flash Builder.
2. Create a new function named enterFrameHandler, which takes a single event parameter and returns void after the applicationCompleteHandler function, like this:

3. In the applicationCompleteHandler function, register the new enterFrameHandler function as an event listener for the ENTER_FRAME event and move the lines that draw in the particleDisplay canvas object into the new enterFrameHandler function:

4. Run the ParticleSystemExercise application. As it plays, the particles display a  shimmering effect as they change color on each frame.
5. Add the code to embed the pbj file into your application after the import line:

6. After the declaration of the m_bytes member variable, add a new declaration for a member variable named m_shader of type Shader and initialize it with the Embedded kernel:

7. In the enterFrameHandler function, add the following lines before the drawing code:

This code sets the input of the shader to be the m_bytes ByteArray object. Since the input is a ByteArray and not a BitmapData object, the width and height of the input must be set on the shader object.

In this example, the width is used as the number of particles and the height is set to 1. The ShaderJob object is then created. This requires a Shader object, a destination buffer (in this case the m_bytes ByteArray is reused as the output buffer), and when using a ByteArray or vector, it also requires width and height values of the destination buffer.

When the start function is called, it launches the ShaderJob by passing in the true value and then waits until the ShaderJob completes rather than registering an event handler to be notified when the ShaderJob has completed.

Note: In this case, the name of the input is known, so you can refer to it by name without first checking that it exists. If your project includes code that will load arbitrary Pixel Bender filters, you'll need to enumerate the inputs, rather than attempting to address them directly by their name. Flash includes a limit of 8,000 for both the width and height of inputs.

Run the ParticleSystemExercise application again. The particles animate around the window and, over time, they eventually leave the window. In the next section, you'll resolve that issue.

This section shows you how to add conditional blocks to ensure that the animated particles stay within a specific area. Follow these steps:

1. Switch back to the Pixel Bender Toolkit and open the Particle.pbk file (if it isn't already open).
2. Add a float2 parameter named size before the evaluatePixel declaration, like this:

Note: In this example, it is not necessary to set the parameter metadata for min, max, and default values.

3. Add the following lines before the end of the evaluatePixel function:

The conditional blocks displayed above verify that a particle is not outside the window area. If the particle animates beyond one of the edges, it is moved back to the edge and its velocity is inverted, which makes the particle appear to bounce. (Remember that the colors in the pixel are used to refer to the particle's position and velocity as described above.)

Note: You can also refer to the channels of a pixel or float4 value using .xyzw or array indices, which may be helpful if the strategy of using the color letters is confusing.

4. Save the Pixel Bender kernel and export it to the pbjs directory by selecting File > Export Filter for Flash Player. The current text of the Particle.pbk file should look something like this:

5. Switch back to the ParticleSystemExercise.mxml file in Flash Builder.
6. Add the following line before the declaration of the ShaderJob object in the enterFrameHandler function:

This line of code sets the value of the size parameter.

7. Run the ParticleSystemExercise application again. This time when the application runs, the particles bounce off the edges of the window. If you'd like to experiment, you can change the size of the window and notice how the particles react (see Figure 2).

Now it's time to review two strategies for improving performance. The first involves revising the ShaderJob to use multiple threads.

Updating the ShaderJob to use multiple threads

Follow these steps to add the code:

1. After the declaration of the PARTICLE_COUNT constant, add a new declaration of a constant named ROWS of type uint initialized to the value 10:

2. In the enterFrameHandler function, where the width is specified to be PARTICLE_COUNT for both the Shader inputs and ShaderJob output, change that value to PARTICLE_COUNT/ROWS.
3. Also in the enterFrameHandler function, change the code where the input height of the shader is 1 and the output height in the ShaderJob is set to 1, to set them to ROWS instead, like this:

Note: When shaders are executed in Flash Player, the height of the output buffer is used to divide the computation into multiple threads. If the height is set to 1, only one thread is spawned. Most current computers have the capability to run between two and eight threads at the same time. It is a best practice to always use multiple rows when passing ByteArray or vector objects to be processed with Pixel Bender.

4. Run the ParticleSystemExercise application again.

   The application's performance may not be noticeably different on your computer with only 8,000 particles. Because the data is now being divided into multiple rows, however, it is now possible to modify the PARTICLE_COUNT and ROWS constants so that you can run many more particles without exceeding the width or height of 8,000. If you'd like to experiment, test to see how many you can run and still maintain acceptable performance on your machine.

Improving performance of the Pixel Bender shaders by changing conditional blocks into conditional assignments

Now look at the second strategy to improve performance. Follow these steps:

1. Switch back to the Pixel Bender Toolkit. Open the particle.pbk file, if it is not already open.
2. Replace the existing lines of the if blocks with the following code:

While the logic may seem much more complicated, it is not as complex as it appears. For example, this part of the code:

can also be written as:

Note: Because of the way the Pixel Bender runtime in Flash optimizes code, conditional statements can be significant performance bottlenecks. When you build projects, it is a good idea to test the application to see if the code performed in an if/else block can be computed separately and then use the select statement to assign the final value to variable. This strategy can potentially improve performance, but it is worth evaluating the application using both methods to verify the one that works best.

3. Save the Pixel Bender kernel and export it to the pbjs directory by choosing File > Export Filter for Flash Player.
4. Switch back to Flash Builder.
5. Run the ParticleSystemApplication exercise. You may notice a performance improvement, depending on the capabilities of your computer.

In the last section of this article, you'll review the completed code that was used to build the final version of the particle system application. If you are following along with these instructions, you can compare your project to the final project files. You can also extend these files to modify the project in various ways.

Compare the completed code for the application with the code that you've updated throughout the course of this tutorial. Open the files you created locally and compare them with the final code shown next.

Final version of the code in ParticleSystemExercise.mxml:

Final version of the code in Particle.pbk:

Adapt the Pixel Bender concepts described in this article and apply them to your own ActionScript projects. Experiment with extending this sample project by adding a second source input to the Pixel Bender kernel that uses an actual bitmap image to constrain the particles.

Check out these other resources to learn more about working with Pixel Bender:

• Pixel Bender basics for Flex and AIR
• Pixel Bender basics for Flash
• Pixel Bender Technology Center
• Effects with the Pixel Bender Toolkit
• Pixel Bender Developer's Guide (PDF, 1 MB)