#

API Documentation for: 1.0.0
Show: Inherited Protected Private Deprecated

# File:SpriteSheetUtils.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.
    */

    /**
     * @module EaselJS
     */

    // namespace:
    this.createjs = this.createjs||{};

    (function() {
    	"use strict";

    // 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
    	 **/
    	function SpriteSheetUtils() {
    		throw "SpriteSheetUtils cannot be instantiated";
    	}

    // private static properties:
    	/**
    	 * @property _workingCanvas
    	 * @static
    	 * @type HTMLCanvasElement | Object
    	 * @protected
    	*/
    	/**
    	 * @property _workingContext
    	 * @static
    	 * @type CanvasRenderingContext2D
    	 * @protected
    	*/
    	var canvas = (createjs.createCanvas?createjs.createCanvas():document.createElement("canvas"));
    	if (canvas.getContext) {
    		SpriteSheetUtils._workingCanvas = canvas;
    		SpriteSheetUtils._workingContext = canvas.getContext("2d");
    		canvas.width = canvas.height = 1;
    	}

    // public static methods:
    	/**
    	 * Returns a single frame of the specified sprite sheet as a new PNG image. An example of when this may be useful is
    	 * to use a spritesheet frame as the source for a bitmap fill.
    	 *
    	 * <strong>WARNING:</strong> In almost all cases it is better to display a single frame using a {{#crossLink "Sprite"}}{{/crossLink}}
    	 * with a {{#crossLink "Sprite/gotoAndStop"}}{{/crossLink}} call 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 {{#crossLink "Bitmap/sourceRect"}}{{/crossLink}}
    	 * property of {{#crossLink "Bitmap"}}{{/crossLink}}.
    	 *
    	 * The extractFrame method may cause cross-domain warnings since it accesses pixels directly on the canvas.
    	 * @method extractFrame
    	 * @static
    	 * @param {SpriteSheet} spriteSheet The SpriteSheet instance to extract a frame from.
    	 * @param {Number|String} frameOrAnimation The frame number or animation name to extract. If an animation
    	 * name is specified, only the first frame of the animation will be extracted.
    	 * @return {HTMLImageElement} a single frame of the specified sprite sheet as a new PNG image.
    	*/
    	SpriteSheetUtils.extractFrame = function(spriteSheet, frameOrAnimation) {
    		if (isNaN(frameOrAnimation)) {
    			frameOrAnimation = spriteSheet.getAnimation(frameOrAnimation).frames[0];
    		}
    		var data = spriteSheet.getFrame(frameOrAnimation);
    		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 = document.createElement("img");
    		img.src = canvas.toDataURL("image/png");
    		return img;
    	};

    	// SpriteSheetUtils.addFlippedFrames is @deprecated. Remove for 1.1+
    	SpriteSheetUtils.addFlippedFrames = createjs.deprecate(null, "SpriteSheetUtils.addFlippedFrames");

    	// SpriteSheetUtils.addFlippedFrames is @deprecated. Remove for 1.1+
    	SpriteSheetUtils.mergeAlpha = createjs.deprecate(null, "SpriteSheetUtils.mergeAlpha");

    // 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+1,canvas.height+1);
    			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 = document.createElement("img");
    			img.src = canvas.toDataURL("image/png");
    			// work around a strange bug in Safari:
    			img.width = (src.width||src.naturalWidth);
    			img.height = (src.height||src.naturalHeight);
    			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||img.naturalWidth)-rect.x-rect.width; // update rect
    				frame.regX = rect.width-src.regX; // update registration point
    			}
    			if (v) {
    				rect.y = (img.height||img.naturalHeight)-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,speed:src.speed,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;
    }());