Understanding library implementation

What is a Library

A Library allows to use Spriter with your game engine. It has some methods to:

• find an image in your framework
• compute coordinates and other data
• request/prepare a rendering for an image
• render a frame
• clear a frame
• destroy the library itself and its data

You have to set a reference to the library your are using in the SpriterEngine or directly in the Spriter (if your are not using SpriterEngine).

There are already some libraries to start using SpriterHaxeEngine for your game made by different contributors. Some of them haven't been pull requested to this repo yet.

Some libraries implemented:

Library	State	Note	Targets	Best for	Performance
TilemapLibrary	need openfl 4.0.4 fix	Use Tilemap	openfl	cpp	many Tile allocations but then use a cache to reuse them. Can clamp the cache if needed to free some memory if needed
SpriterLibrary	working	Use Bitmaps with addchild	openfl	flash	many Bitmap allocations
BitmapLibrary	working	Use only one Bitmap with copypixels()	openfl	flash	some BitmapData allocations when no rotation and no scale
TilelayerLibrary	working	Use haxelib Tilelayer (drawTile())	openfl	cpp, html5, mobile	many TileSprite allocations
DrawTileLibrary	working	Allow using more than one Tilesheet	openfl (no flash fallback)	cpp, html5, mobile	one DrawList allocation per drawCall, and then use a pool.
FlixelLibrary	working	flixel 4.0	openfl	flixel :)	FlxSprite allocation for each image but reuse them with a cache. This cache should be used to improve non optimized libraries like SpriterLibrary and TilelayerLibrary.
HeapsLibrary	didn't test	h3d custom library by delahee	h3d	h3d:)	many h2d.Bitmap allocations. Use a cache for h2d.Tile.
LuxeLibrary	working	Luxe	Luxe	Luxe :)	many Sprite entities allocations
KhaG2	waiting for pullrequest		Kha	Kha :)	use a cache for TextureAsset. But there are many Anonymous Structure allocations.
KhaPunk	waiting for pullrequest	Use HaxePunk	Kha	Kha & HaxePunk :)	no data
FlambeLibrary	waiting for pullrequest	use Spriter v1	Flambe	Flambe :)	no data

Implement a new rendering target

To implement a new rendering target, you have to create a Library that inherits AbstractLibrary. The only mandatory method to override is addGraphic. This method is called when a Spriter is updated. One Spriter can call one or many times this method because a Spriter can contain many images.

The compute method shouldn't be overrided. But TilelayerLibrary is currently overriding this method because it uses the center of the sprite for the coordinates and not the top left.

SpriterEngine clears the Library first, then updates all Spriters and renders the Library. Overriding clear and render method is not mandatory. For example, you can render in addGraphic directly and you can also clear and render outside the Library if you think it will be more efficient in your game engine. But don't forget to comment the rendering process in your Library. Also, you can still override clear and render but you can forbid SpriterEngine to use it.

SpriterEngine.handleLibraryClearAndRender = false;

Mixing Spriters and other graphics in the same layer

Using SpriterEngine has some limitations depending on the framework you are using.

You may not use a single drawCall to render Spriters and other graphics. Set handleLibraryClearAndRender to false allows to handle this process yourself so you can have a single drawCall.

Example :

lib = new MyLibrary();
spriters = SpriterEngine(..., lib, ..., false);
function update()
{
lib.clear();//usually called in spriters.update()
spriters.update();
otherGraphics.update();
lib.render();//render Spriters and other graphics in one drawCall //usually called in spriters.update()
}

Note that in this configuration, you will have your spriters rendered first and the other graphics on top. If you want to mix their z-order, you shouldn't use SpriterEngine but directly Spriter.

Example :

• Create and store by yourself all Spriter.
• Put all Spriters and other graphics in the same z-ordered list
• Update the list each frame
• Render everything