spritesheet

Spritesheet blueprint

This page describes how to can render a spritesheet animation using a highly performant CSS animation technique, and is used as a blueprint to track the progress on finding a more user-friendly API.

WARNING: This API is subject to change due to feedback and improvements.

It should be noted that this technique only works on chrome, firefox, latest safari, opera 12, and IE10.

Background


NME uses the drawTiles and the Tilesheet interface for drawing spritesheets, which provides a fast API for rendering spritesheets in CPP. Jeash implements a different API, which takes advantage of CSS animations to draw spritesheets against a displayobject in the browser. The API methods are low-level, and are not intended to integrate with the flash API:
  • jeash.Lib.jeashSetSurfaceSpritesheetAnimation
  • jeash.Lib.jeashCreateSurfaceAnimationCSS

A jeash spritesheet animation only works on one image, that has its frames split into rectangular sections of the image.

jeashSetSurfaceSpritesheetAnimation


Each Graphics instance is associated with an HTML node, and this element can be assigned a set of CSS keyframes and animations. Each keyframe is a single frame in the animation. Let's look at the interface:
Lib.jeashSetSurfaceSpritesheetAnimation(surface:HTMLCanvasElement, spec:Array<Rectangle>, fps:Float) : HTMLElement

This method takes a canvas element and an array of Rectangle instances, and returns an html element (in this case a DIV). It's important to note, that by default all Graphics instances are possible candidates for a spritesheet animation, and each DisplayObject is associated with a Graphics instance, so the first step is to use a DisplayObject that contains the entire spritesheet image.

The array of Rectangles describes rendering frame regions, which are associated with each keyframe in your animation. Each rectangle contains the frame's x, y, width and height co-ordinates where the spritesheet's image should be cropped.

The fps paramter declares how fast the animation should play.

Accessing the DOM from the flash API


Assuming we have an animation of 3 frames, rendering a box of 50 width and height, and using NME:
var tiles = [new Rectangle(0, 0, 50, 50), new Rectangle(50, 0, 50, 50), new Rectangle(100, 0, 50, 50)];
var bitmap = new Bitmap (Assets.getBitmapData ("assets/spritesheet.png"));
Lib.jeashSetSurfaceSpritesheetAnimation(bitmap.jeashGetGraphics().jeashSurface, tiles, 15);

The method call jeashGetGraphics() is a jeash system call to retrieve the underlying Graphics instance. The jeashSurface getter retrieves the underlying HTML node associated with a Graphics instance.

Adding the spritesheet back into the flash API


The underlying implementation for jeashSetSurfaceSpritesheetAnimation paints the canvas into a DIV element, and applies CSS stylesheet rules onto this node, and returns the newly created DIV element. By having a handle on this node, it's then necessary to associate the element back into the flash API. The easiest way to do this is to extend the Sprite class
class MyAnimation extends Sprite {
  function new () {
    var tiles = [new Rectangle(0, 0, 50, 50), new Rectangle(50, 0, 50, 50), new Rectangle(100, 0, 50, 50)];
    var bitmap = new Bitmap (Assets.getBitmapData ("assets/spritesheet.png"));
    jeashGraphics = new Graphics(Lib.jeashSetSurfaceSpritesheetAnimation(bitmap.jeashGetGraphics().jeashSurface, tiles, 15));
  }
}
version #12678, modified 2012-04-06 12:02:50 by grumpytoad