The problem with Flixel’s memory management system is that it doesn’t exist. However, every time you switch states, it does call destroy() on almost every object. The problem is that most of the destroy() functions are completely empty. Obviously, this is not enough.

UPDATE: I got onto github and forked flixel, wrote a patch, and did a pull request. I can’t solve the biggest problem though, which is that FlxQuadTree is being completely recreated on every frame. This is extremely terrible practice and causing the Flash GC to bust ass. I don’t use FlxQuadTree and I recommend building a persistent static grid to handle collisions instead (MUCH simpler and faster than quadtrees anyway). I’m pretty sure the quadtree is causing a huge performance hit alongside the memory thrashing, since my games don’t experience what I see in vanilla Flixel. Good luck!

You will need to go through every class yourself and override (or fill in) the destroy() method to nullify any significant variable in the class itself. Remember to call super.destroy() so that it chains through all super-classes too. Here’s what the FlxObject.destroy() should look something like:

public function destroy():void {
  velocity = acceleration = drag = maxVelocity = null;
  origin = scrollFactor = null;
  _point = null;
  _rect = null;
  _flashPoint = null;
  colHullX = colHullY = colVector = colOffsets = null;
}

Don’t actually use the code in this post–none of it compiles without errors, it’s merely an example (I will be submitting a tested patch for this whole thing to the trunk soon). Also, I’m using the latest build I got from the Flixel homepage–v2.43.

What I’m showing here is pretty straightforward. It just nullifies all object variables so the Flash GC will pick it up. We do the same thing in FlxSprite.destroy(), but we’re going to have to add the function ourselves because for some reason it doesn’t exist. So put this function at the end of FlxSprite:


override public function destroy():void {
  super.destroy();
  offset = scale = null;
  _curAnim = null;
  _callback = null;
  _flashRect = _flashRect2 = null;
  _flashPointZero = null;
  //_pixels.dispose(); // only do this if you don't use FlxG.addBitmap()
  //_pixels = null;
  _framePixels.dispose();
  _bbb.dispose();
  _framePixels = _bbb = null;
  _ct = null;
  _mtx = null;
  for (var i:int = 0; i < _animations.length; ++i) _animations[i] = null;
  _animations.length = 0;
  _animations = null;
}

So those are the first classes to hit. But there are dozens more. Other ones you should get to include (but not limited to) FlxQuadTree, FlxGroup, FlxButton, FlxEmitter, and FlxTilemap. There are a bunch more in flixel.data that you need to do too, in addition to adding destroy code to FlxGame itself.

FlxG._cache and what it does

An important thing to note is FlxG._cache. Whenever you create a new sprite, it stores the bitmapData in that Object. Adam’s reasoning for this was so that only one instance of the BitmapData object remains in memory, so new sprites just reference that one instead of creating new instances. I think this is a pretty solid idea, but I’m not sure how much it actually helps. If anyone has tested this, please post your results in the comments.

Anyway, if you loop through it like I did with FlxSprite._animations though, you will get a ton of null reference errors because you already nullified most of it by disposing of _framePixels in FlxSprite. I recommend adding a new destroy function to FlxG itself and going through _cache and running dispose on each object regardless (IF it’s BitmapData AND not already null)… just to be sure. Don’t forget to null the _cache Object itself.

Cleaning up your own mess

It is very important to override destroy() in ALL of your custom classes to nullify any new variables you added in them. In every class you create, add a destroy() override that also calls super.destroy() in order to ensure that the GC picks up everything. Don’t forget to remove any event listeners as well!

So that’s the memory problem in Flixel and how to fix it. Please retweet this post and share it with others. I think this is an important issue that needs to address in a future version of Flixel, as others are always finding out about it and posting their troubles in the forums. Let’s do our part to keep Flash from crashing everyone’s browser Thanks!

And yes, it runs perfectly fine. I’ve run it at 60+ FPS with 7,000 particles, but that actually isn’t the limitation (unless your particles are crunching heavy math for eg movement). Rather it’s the size and number of sprites that we’re colliding with the particles.

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

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.

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:

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.(_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:

_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:

_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.

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