Understanding library implementation
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.
| 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 |
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;
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