To squeeze all the juice out of Flash I employed a couple tricks. The first was the particles themselves–they’re blitted to a single bitmap which is used as the source image for grabbing collision data from. The particles are also drawn with the raster engine in Flash (multiple setPixel32() ops to give the illusion of a line… a choppy one anyway) instead of the vector renderer (lineTo()). The second trick was to only grab a Vector of pixels from the regions we cared about (within sprite boundaries) every so often, then to loop through the Vector and test it against our desired conditions. Also, since the particle bitmap is more sparse than our sprites as far as opaque pixels go, we test the particle bitmap first, resulting in a lot fewer passes on the first round of conditional statements.

So my poor man’s method of making lines is done by interpolating the position of a particle from the previous to the current frame, for a total of 3 setPixel32() operations per iteration. (We can use setPixel() for a solid performance gain, but at a different kind of cost that I’ll explain later.) To give the particles a long tail we simply decrease the alpha of the particle bitmap a little bit every frame, making older particles fade more as time goes by. This means we can skip fillRect() to clear the bitmap every frame, but I’m wondering if that’s faster or slower than ColorTransform. Haven’t tested, for shame.

I’ll admit that I haven’t tried this method with bitmap-based particles but those would work just as well, in theory (using blitted rendering). One of my current projects demands those trailing things so I didn’t look into it. If you try it, please comment on this post below with your findings
Click on the right-side arrow to unroll this block of code.

particleMap.lock();
for (i = 0; i < _numParticles; ++i) {
	p = particles[i];
	// get our velocity from the perlin noise map
	vel = noiseMap.getPixel(p.x>>3, p.y>>3); // because noiseMap is 1/9 the size of particleMap
	var brightness:Number = vel / 0xFFFFFF;
	var speed:Number = 0.1 + brightness * p.speed;
	var angle:Number = 360 * (brightness * p.wander) * 0.0175; // roughly PI / 180 to convert to radians
	p.vx = Math.cos(angle) * speed;
	p.vy = Math.sin(angle) * speed;
	// absolute value for velocity calculations
	var pvx:Number = p.vx < 0 ? -p.vx : p.vx; // use bitwise sign flippage
	var pvy:Number = p.vy < 0 ? -p.vy : p.vy;
	// poor man's lineTo ENGAGED
	var nx:Number = p.x + (p.vx >> 1); // where we are now + half the distance to where we will be
	var ny:Number = p.y + (p.vy >> 1);
	var mx:Number = nx - p.x; // then half THAT distance for a third position...
	var my:Number = ny - p.y;
	// actually apply velocity to pixel
	p.x += p.vx;
	p.y += p.vy;
	// bounds-check
	if (p.y < 0) p.y = h - 1;
	else if (p.y > h) p.y = 1;
	if (p.x < 0) p.x = w - 1;
	else if (p.x > w) p.x = 1;
	// pick our color based on speed
	speed *= 60;
	if (speed > 255) speed = 255;
	color = 255 << 24 | speed << 16 | speed << 8 | speed;
	// render the particle three times, each in different places to get a line-ish thing going
	particleMap.setPixel32(p.x, p.y, color);
	particleMap.setPixel32(mx, my, color);
	particleMap.setPixel32(nx, ny, color);
}
// and we're done. release the pixels!
particleMap.unlock(_r);

So that gives us some spotty-but-close-enough trails to help with our collision detection. It works like this: We create a single bitmap to use as a canvas for our particles. We render those particles using setPixel32() as mentioned above. Sprites will use this bitmap as a source for collision data. Every other frame or so (more on this later) the sprites will grab a section of pixels from the particle bitmap using something like getVector() (>= Flash 10) or getPixels() (< Flash 10), using their own position and dimensions for the sourceRect parameter.

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

shipVec = buffer.getVector(_rc); // get an array of pixels from the whole sprite
_rc.x = int(this.x); // change rect to particleBMD's coordinate space
_rc.y = int(this.y);
pixVec = _particlebmd.getVector(_rc); // grab an array of the same area of pixels that our sprite is occupying
var a:uint;
var i:int = 0;
buffer.lock();
for (i; i < _l; ++i) {
	_pval = pixVec[int(i)]; // first look at the particle's image for opaque pixels
	a = _pval >> 24;
	if (a < 100) continue;
	// it found an opaque-ish pixel, so let's see if there's an opaque pixel in the ship there too
	_sval = shipVec[int(i)];
	a = _sval >> 24;
	if (a < 100) continue;
	/* if we get this far then we have a collision because one
	 * of the ship's pixels is overlapping a particle's pixel.
	 * we're only going to collide with red-colored particles though */
	_pval = _pval >> 16 & 0xFF; // red channel extraction
	if (_pval > 100) {
		var px:int = int(i % w); // translate 1d array coordinate to 2d grid coordinates
		var py:int = int(i / h);
		buffer.setPixel32(px,py,0xFF4e88c9); // colliding pixels are painted on the top of our sprite in a cold blue-ish color
	}
}
buffer.unlock();

As you can see on line 133 and 136, each sprite has a block of pixels ready to examine on each tick. The sprite loops through that block and compares every pixel of its own with the pixels in the Vector it got. If there's a match (eg both pixels are opaque) then look at the particle's pixel in detail to see if it's the droid one we're looking for and record its findings.

So you can alter line 151 so that the sprites check for specific colors in the particle bitmap, like anything brighter than dark grey (which I did here, or anything with an alpha greater than 0.1 or... use your imagination I guess?).

Because grabbing a new Vector from the particle bitmap can be so expensive (depending on the size of the sprite), you can time limit the collection so it only samples the particle bitmap once in a short while. In the demo SWF above I sample it once every 100 milliseconds or so, which comes out to about 24 samples a second (given 25 milliseconds per frame at 60 FPS)... as opposed to 2400 samples a second. The casual human eye can't tell the difference but it yields a significant increase in performance. Most performance tricks I've learned are based are smoke and mirror stuff like this.

You can use setPixel() (no alpha) but you'll have to test for color--obviously for a color that isn't what the background of the particle bitmap is, so it's a little more tricky. It's also totally possible to use other sprites as particles as long as you blit them (using copyPixels() or setVector()) to a single bitmap that can be checked by other sprites that collide with them. If you don't know what blitting is, 8bitRocket has a good rundown (it's where I first learned about it actually).

And that's pretty much it. You can download the example files/source below.

Judging by the number of results Google returns, this is a pretty fringe case (that or I’m exceptionally stupid… hush). Regardless, it’s a problem that has been plaguing me for the past few months. If it weren’t for my genius programmery brother I would have never found it either. But thanks to him I’m now savvy to what’s termed as “rounding errors”. They even sound evil.

Here’s an example with code…

Below we define our dimensions grabbed from pixels (raw bitmapData from some loaded file elsewhere). We just want to analyze a quarter of the image, hence we’re dividing both dimensions by 2. We also instantiate the array (a fixed-length Vector) we’ll be iterating through:

1
2
3
4
5

var w:int = pixels.width / 2;
var h:int = pixels.height / 2;
var _l:int = w * h;
var _rc:Rectangle = new Rectangle(0, 0, w, h);
array = new Vector.<uint>(_l, true);

Awesome. Now somewhere else in the code (say, an update method) we want to assign a chunk of pixel data to the array so we can pick through them one by one:

6
7
8
9
10
11
12

_rc.x = pixels.x;
_rc.y = pixels.y;
array = pixels.getVector(_rc);
for (i; i < _l; ++i) {
	_pixel = array[i];
	var alpha:uint = _pixel >> 24;
}

Alright, looks mighty fine. We’re just checkin’ out the alpha value in those pixels, you know whatever. BUT WAIT. While we’re running this code, the values for pixels.x and pixels.y are changing because our source image is moving around the stage. And guess what? Without pixel snapping on, we’re getting floating point values for those coordinates even though they’re typed as ints. This wouldn’t normally be a problem but since we’re extracting other pixel data using those values, they need to be floored or else we’ll get the rounding error I discussed above.

So to fix this bitch we simply change lines 6 and 7 to:

6
7

_rc.x = int(pixels.x);
_rc.y = int(pixels.y);

…and viola, no more error. (I used int() instead of Math.floor() because it’s hella faster). So I hope that helped someone out there because I sure as hell needed it Good luck and have fun.

1. Best resources for beginners
2. Syntax overview
3. More performance tips
4. Realtime use of Pixel Bender
   1. Asynchronous mode
   2. Synchronous mode
5. Conclusion

When I set out to write a very simple Pixel Bender (PB) kernel/script thingy, I expected it to be relatively straight-forward, mostly because Adobe has been so good writing quality documentation for its products and/or there is a wealth of info on their products produced by their users. Unfortunately I didn’t find the dev guide in the Help menu and I missed some key AS3 bits from the links I’ll post below, but even so I still had a lot of trouble finding some info that really should already have been out on the interwebs. So this post is to fill in the gaps when going from AS3 to Pixel Bender.
Hope it helps

Best resources for beginners

Here’s the best tutorials and explanations I’ve found so far:

• The official guide and reference. Slap that F1 key! Also, don’t forget the Help menu in the toolkit like I did (there’s the PB-specific language spec and dev guide there).
• Using PB as a calculator. Completes the official tutorial.
• Great in-depth article with general+performance tips.
• Very straight-forward examples + comedy. Can’t go wrong there.
• Nice user article on optimizations and some speed tests (turns out, for input bitmapData beats ByteArray beats Vector.)

Syntax overview

As a casual programmer of high-level languages and no mid- to low-level ones, I was thrown off by PB’s awkward syntax. It’s strongly typed, which is fine, except I’m not familiar with low-level languages like C or any previous shader language (PB is based on GLSL from what I hear). Here’s a basic difference:

AS3: var i:Number = 12;
…in PB is: float i = 12.0;
The decimal in 12.0 tells PB it’s a floating point number. If it was just 12 PB would think it’s an int.

When dealing with “vectors” (which are arrays, as in Flash 10’s odd use of the word “vector”) it’s float2 i = float2(12.0, 2.0). Notice there’s no brackets or anything suggesting any type of array present. It’s simply the type + how big the array is, eg float3. It goes up to 4, for the 4 channels in images: Red, Green, Blue, Alpha). Then, as you can see, intializing the array is a simple matter of putting in the numbers you said would be there. So float4(1.0, 24.2, 0.1, 3.4) is valid whereas float2(1.0, 24.2, 2) is not, because there’s an extra number in there and it’s an int (adding insult to injury).

An important thing to keep in mind is that Pixel Bender sees channels in the order described above (RGBA). This little detail cost me a bit of time because I’m used to AS3’s order of ARGB–the alpha channel is first in AS3 while it’s last in PB.

To use any of the built-in functions you simply call them as they appear in the reference doc: all(x); atan(x,y); etc., no Math calls like we have to do in Flash (this through me for a loop, lemme tell ya).

For those of you who use the shortcut operations like var i:int = foo < bar ? foo : bar;, then you'll be pleased to hear they're supported in PB too. Just about the only thing "Hydra" (formally the codename for Pixel Bender, now--I guess--the name of the PB Flash implementation) does not support is loops of any kind and their related break/continue statements. That last bit is bad because there are times when I want to stop the filter if a certain condition is met. You just have to design your logic to take this into account from the start.

That's the basics but take special note that shader.data is actually an array, so you can do some naughty stuff like iterate through some kinky data and set the input as shader.data['whatever'+i].input = kinky[i]. Also note that in order to set the input for a shader in AS3 you must set it to shader.data.vdipb.INPUT = inputImage where vdipb is the variable name you declared in the PB shader itself.

More performance tips

Turns out that after I converted my kernel from using boolean methods (like boolean4() etc.) to if statements, it consistently executed faster. I also got some fractional FPS increases by using the age-old optimization of putting real values (eg 1.2) in the evaluation statement instead of references (eg pixel.r). See the last blog I linked above for some other obvious and not-so-obvious performance tips.

PB math is much faster than straight AS3 math but it's slightly brighter (I wouldn't say it shines per se...) when it runs in asynchronous mode, which is enabled by using ShaderJob. You use addEventListener(Event:ShaderEvent...) and then run start(false) to put it in asynchronous mode (the param is waitForCompletion and it's already false by default). See Ryan's post for a great example of how the ShaderJob has to be setup (Squize's post, linked above, is an even clearer example).

Realtime use of Pixel Bender

Asynchronous mode

Reading the above linked performance tips for PB you, like me, might be thinking "OH MAN I can rule the universe with ShaderJob doing bitchwork like heavy collision solving" and you'd be totally wrong. You only have to set the input for a shader once, but you do have to create a new ShaderJob per computation of the filter every frame/tick. This is the depressing because ShaderJob takes a LONG time to start up and it, unlike the job itself, does use CPU from Flash's main thread--you do not get the asynchronous hotness until the actual job is started. And it is sloooooowwwww. Unless you're doing some serious number crunching or temporary special effect, you will not see a huge benefit from using PB in your game.

To be clear, ShaderJob works well enough for realtime usage but my experiments have shown that it's not fast enough to be executed every frame (unless you're SWF is running at 20 FPS or so). I tried to get it to fulfill my game's collision detection system by processing the entire map, but PB just couldn't handle the job. Still, I do recommend you try it (using Squize's recursive implementation) and see if it works for you. Just keep your hopes down

Synchronous mode

You can set ShaderJob.start(true) but if you're going the synchronous route, I suggest applying your Pixel Bender kernel by using the filter method. It starts up much faster than ShaderJob and doesn't have to be restarted every time you want to update the input. You do have to wait for it to finish processing before it will move to the next line in your code though, but as I mentioned above, PB math is a lot faster than AS3's Math library. So if you're doing something intense(r) like severe image distortion then PB is definitely worth a shot, but if it's just conditionals then you're probably better off in pure AS3 land.

Conclusion

Besides doing complex calculations, another place where PB would really help though is processing large (like 600 or 10000 pixels wide or bigger) images. It loops through each pixel faster than AS3 does. But remember that in AS3 you can do loops, so easily skipping pixels (using the continue statement) can result in some significant performance gains if you're not processing all the pixels in the input data (eg skipping transparent pixels). There's a lot of pro/cons so experimenting is, as always, the way to go (if you can afford it).

So there it is, all the info I wish was out there when I started learning PB (I can't stop thinking of Peanut Butter!). Hope some of it was helpful and of course I could be wrong about something (except about declaring input once, I've heard otherwise but in practice it worked fine) so please don't hesitate to correct me if so. Good luck and have fun