topical media & game development

talk show tell print

mobile-graphic-easel-src-easeljs-utils-SpriteSheetUtils.js / js



  /*
  * SpriteSheetUtils
  * Visit http://createjs.com/ for documentation, updates and examples.
  *
  * Copyright (c) 2010 gskinner.com, inc.
  * 
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
  * files (the "Software"), to deal in the Software without
  * restriction, including without limitation the rights to use,
  * copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the
  * Software is furnished to do so, subject to the following
  * conditions:
  * 
  * The above copyright notice and this permission notice shall be
  * included in all copies or substantial portions of the Software.
  * 
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  * OTHER DEALINGS IN THE SOFTWARE.
  */
  
  // namespace:
  this.createjs = this.createjs||{};
  
  (function() {
  // constructor:
  
The SpriteSheetUtils class is a collection of static methods for working with {{#crossLink "SpriteSheet"}}{{/crossLink}}s. A sprite sheet is a series of images (usually animation frames) combined into a single image on a regular grid. For example, an animation consisting of 8 100x100 images could be combined into a 400x200 sprite sheet (4 frames across by 2 high). The SpriteSheetUtils class uses a static interface and should not be instantiated. @class SpriteSheetUtils @static

  
  var SpriteSheetUtils = function() {
          throw "SpriteSheetUtils cannot be instantiated";
  }
  
          
@property _workingCanvas @static @type HTMLCanvasElement | Object @protected

  
          SpriteSheetUtils._workingCanvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas");
  
          
@property _workingContext @static @type CanvasRenderingContext2D @protected

  
          SpriteSheetUtils._workingContext = SpriteSheetUtils._workingCanvas.getContext("2d");
  
  // public static methods:
          
<b>This is an experimental method, and may be buggy. Please report issues.</b><br/><br/> Extends the existing sprite sheet by flipping the original frames horizontally, vertically, or both, and adding appropriate animation & frame data. The flipped animations will have a suffix added to their names (_h, _v, _hv as appropriate). Make sure the sprite sheet images are fully loaded before using this method. <br/><br/> For example:<br/> SpriteSheetUtils.addFlippedFrames(mySpriteSheet, true, true); The above would add frames that are flipped horizontally AND frames that are flipped vertically. <br/><br/> Note that you can also flip any display object by setting its scaleX or scaleY to a negative value. On some browsers (especially those without hardware accelerated canvas) this can result in slightly degraded performance, which is why addFlippedFrames is available. @method addFlippedFrames @static
parameter: {SpriteSheet} spriteSheet
parameter: {Boolean} horizontal If true, horizontally flipped frames will be added.
parameter: {Boolean} vertical If true, vertically flipped frames will be added.
parameter: {Boolean} both If true, frames that are flipped both horizontally and vertically will be added.

  
          SpriteSheetUtils.addFlippedFrames = function(spriteSheet, horizontal, vertical, both) {
                  if (!horizontal && !vertical && !both) { return; }
                  
                  var count = 0;
                  if (horizontal) { SpriteSheetUtils._flip(spriteSheet,++count,true,false); }
                  if (vertical) { SpriteSheetUtils._flip(spriteSheet,++count,false,true); }
                  if (both) { SpriteSheetUtils._flip(spriteSheet,++count,true,true); }
          }
  
          
Returns a single frame of the specified sprite sheet as a new PNG image. Note that in almost all cases it is better to display a single frame using a paused instance of BitmapAnimation, than it is to slice out a frame using this method and display it with a Bitmap instance. You can also crop an image using the <code>sourceRect</code> property of {{#crossLink "Bitmap"}}{{/crossLink}}. This method may cause cross-domain issues since it accesses pixels directly on the canvas. @method extractFrame @static
parameter: {Image} spriteSheet The SpriteSheet instance to extract a frame from.
parameter: {Number|String} frame The frame number or animation name to extract. If an animation name is specified, only the first frame of the animation will be extracted.
returns: {Image} a single frame of the specified sprite sheet as a new PNG image.

  
          SpriteSheetUtils.extractFrame = function(spriteSheet, frame) {
                  if (isNaN(frame)) {
                          frame = spriteSheet.getAnimation(frame).frames[0];
                  }
                  var data = spriteSheet.getFrame(frame);
                  if (!data) { return null; }
                  var r = data.rect;
                  var canvas = SpriteSheetUtils._workingCanvas;
                  canvas.width = r.width;
                  canvas.height = r.height;
                  SpriteSheetUtils._workingContext.drawImage(data.image, r.x, r.y, r.width, r.height, 0, 0, r.width, r.height);
                  var img = new Image();
                  img.src = canvas.toDataURL("image/png");
                  return img;
          }
  
          
Merges the rgb channels of one image with the alpha channel of another. This can be used to combine a compressed JPEG image containing color data with a PNG32 monochromatic image containing alpha data. With certain types of images (those with detail that lend itself to JPEG compression) this can provide significant file size savings versus a single RGBA PNG32. This method is very fast (generally on the order of 1-2 ms to run). @method mergeAlpha @static
parameter: {Image} rbgImage The image (or canvas) containing the RGB channels to use.
parameter: {Image} alphaImage The image (or canvas) containing the alpha channel to use.
parameter: {Canvas} canvas Optional. If specified, this canvas will be used and returned. If not, a new canvas will be created.
returns: {Canvas} A canvas with the combined image data. This can be used as a source for Bitmap or SpriteSheet.

  
          SpriteSheetUtils.mergeAlpha = function(rgbImage, alphaImage, canvas) {
                  if (!canvas) { canvas = createjs.createCanvas?createjs.createCanvas():document.createElement("canvas"); }
                  canvas.width = Math.max(alphaImage.width, rgbImage.width);
                  canvas.height = Math.max(alphaImage.height, rgbImage.height);
                  var ctx = canvas.getContext("2d");
                  ctx.save();
                  ctx.drawImage(rgbImage,0,0);
                  ctx.globalCompositeOperation = "destination-in";
                  ctx.drawImage(alphaImage,0,0);
                  ctx.restore();
                  return canvas;
          }
  
          
  // private static methods:
          SpriteSheetUtils._flip = function(spriteSheet, count, h, v) {
                  var imgs = spriteSheet._images;
                  var canvas = SpriteSheetUtils._workingCanvas;
                  var ctx = SpriteSheetUtils._workingContext;
                  var il = imgs.length/count;
                  for (var i=0;i<il;i++) {
                          var src = imgs[i];
                          src.__tmp = i; // a bit hacky, but faster than doing indexOf below.
                          ctx.setTransform(1,0,0,1,0,0);
                          ctx.clearRect(0,0,canvas.width,canvas.height);
                          canvas.width = src.width;
                          canvas.height = src.height;
                          ctx.setTransform(h?-1:1, 0, 0, v?-1:1, h?src.width:0, v?src.height:0);
                          ctx.drawImage(src,0,0);
                          var img = new Image();
                          img.src = canvas.toDataURL("image/png");
                          // work around a strange bug in Safari:
                          img.width = src.width;
                          img.height = src.height;
                          imgs.push(img);
                  }
                  
                  var frames = spriteSheet._frames;
                  var fl = frames.length/count;
                  for (i=0;i<fl;i++) {
                          src = frames[i];
                          var rect = src.rect.clone();
                          img = imgs[src.image.__tmp+il*count];
                          
                          var frame = {image:img,rect:rect,regX:src.regX,regY:src.regY};
                          if (h) {
                                  rect.x = img.width-rect.x-rect.width; // update rect
                                  frame.regX = rect.width-src.regX; // update registration point
                          }
                          if (v) {
                                  rect.y = img.height-rect.y-rect.height;  // update rect
                                  frame.regY = rect.height-src.regY; // update registration point
                          }
                          frames.push(frame);
                  }
                  
                  var sfx = "_"+(h?"h":"")+(v?"v":"");
                  var names = spriteSheet._animations;
                  var data = spriteSheet._data;
                  var al = names.length/count;
                  for (i=0;i<al;i++) {
                          var name = names[i];
                          src = data[name];
                          var anim = {name:name+sfx,frequency:src.frequency,next:src.next,frames:[]};
                          if (src.next) { anim.next += sfx; }
                          frames = src.frames;
                          for (var j=0,l=frames.length;j<l;j++) {
                                  anim.frames.push(frames[j]+fl*count);
                          }
                          data[anim.name] = anim;
                          names.push(anim.name);
                  }
          }
          
  
  createjs.SpriteSheetUtils = SpriteSheetUtils;
  }());


(C) Æliens 04/09/2009

You may not copy or print any of this material without explicit permission of the author or the publisher. In case of other copyright issues, contact the author.