Correct way to instantiate a FlxPoint

Question

(I'm using the dev branch of HaxeFlixel)

To create a new FlxPoint variable I can do one of three things...

var pt:FlxPoint = new FlxPoint();
var pt:FlxPoint = FlxPoint.weak();
var pt:FlxPoint = FlxPoint.get();

From reading the method comments, I've figured out there's some sort of pooling going on to presumably speed up creating FlxPoints. Under what circumstances should I use each of the three ways to create a new FlxPoint?

I have several functions that either accept FlxPoints as parameters, or return them. Should I copy what FlxPoint itself does, and use .weak() to create them, and .putWeak() to recycle points passed into functions?

To me it seems .get() is for long-lived variables (player start positions, points stored in an array for path finding, etc), and .weak() is for temporary ones (intermediate values calculated within a function). Is this right?

Broca

Answer 1

FlxPoint provides a pooling mechanism that is supposed to help reduce garbage collection.

FlxPoint.get() attempts to retrieve an unused point from the pool. If there isn't one, it's effectively the same as new FlxPoint(). Either one can be recycled by being put() back into the pool.

weak() is more about being used for library calls than longevity (though that does often mean it's short-lived) - here is its documentation:

Recycle or create a new FlxPoint which will automatically be released to the pool when passed into a flixel function.

This means you don't need to worry about keeping a reference to the pivot point and recycling it in this example, since rotate() calls putWeak() on it for you:

point.rotate(FlxPoint.weak(0, 0), 45);

Bicyclic

I wish I could mark all three answers as being "correct", but your bit about library calls explains it the best. Library functions accepting FlxPoints should try to release them, and should weakly create them because they could be - like your rotate example, be called every frame multiple times. – Broca

Answer 2

FlxPoint.get() retrieves a FlxPoint from the pool and requires you to manually put() it back when you are finished with it. Use this for long-lived variables. You might use get() in a constructor and put() in the destroy method of a class that needs a point member variable.

FlxPoint.weak() gives you a point that gets returned to the pool when put() or putWeak() is called on it. Like you say, using them for temporary or intermediate values is best. HaxeFlixel does this for methods that take FlxPoints, and you can follow that pattern in your own code too.

Instantiating a FlxPoint with new creates one without pooling. The garbage collector takes care of it, provided you don't hang on to references to it. It's fine to do this for the odd point, and it's fine whenever performance or garbage collection pauses aren't a big concern.

Trove

Answer 3

You are pretty much correct.

var pt:FlxPoint = new FlxPoint(); This creates a new FlxPoint, without adding it to the 'pool' or setting it as weak. A 'weak' FlxPoint is one that will be destroyed after being passed to a standard haxeflixel method. Again, calling new makes it not weak, and not in a pool.

As you said, it is useful for more permanent FlxPoints, such as storing where the level begins.

---

var pt:FlxPoint = FlxPoint.weak(); This is identical to calling new FlxPoint however it also sets the point to be weak. A weak FlxPoint is recycled once it is used in a Haxeflixel function. It is not in a pool by default, however will be added to the pool if .putWeak() is called. putWeak() just recycles a temporary (weak) FlxPoint. Although putWeak() is in the haxeflixel code, you can just as easily call putWeak if you want to discard a temporary, weak FlxPoint.

This is most useful for points that are used during temporary calculations. You can see it being used in FlxPoint itself, when math is does between two points (such as when they are added).

---

var pt:FlxPoint = FlxPoint.get(); This method of getting a FlxPoint attempts to retrieve a FlxPoint from the pool of FlxPoints. This is useful because retrieving an existing point from memory and mordifying it is cheaper than creating a new point. You can (and should) return this Point back to the pool by calling .put() when you are finished with it.

This is most useful for when you will be creating loads of FlxPoint but only using them temporarily. For example, if you need a FlxPoint to show where a bullet will land, and the player is shooting hundreds of bullets, recycling a FlxPoint from a pool is much less expensive than calling new FlxPoint every bullet.

As you can see, they are all somehow linked, and are very similar.

Bellda