lasertank-js/src/TileMasker.js

/**
 * Handles the masking of tile sets
 *
 *  Copyright (C) 2012  Mike Gerwitz
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Affero General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Affero General Public License for more details.
 *
 *  You should have received a copy of the GNU Affero General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 *
 * This handles the masking and slicing of tiles found in LTG files (see
 * LtgLoader for more information).
 *
 * We must think back to the good ol' days - before transparency was represented
 * in the image format itself and before alphatransparency even existed. Bitmaps
 * have no alpha channel like PNG, nor can they designate any color as
 * transparent like GIFs. That is what the mask bitmap is for. In the case of
 * the LT mask, black is used to denote opacity whereas white denotes
 * transparency. Furthermore, not all tiles have masks associated with them
 * (e.g. blocks and walls). Rather than those mask tiles being represented as
 * solid black boxes, some tileset masks are solid *white*. This, as we will
 * see, complicates our masking algorithm.
 *
 * When rendering the tiles, we obviously need to support transparency. In the
 * browser, this must be done either with a GIF or an alpha channel. In other
 * words --- we need to apply the mask to the tiles to result in a tile set with
 * an alpha channel which can be directly drawn to the screen. Applying this
 * mask when the LTG file is initially loaded will also improve performance by
 * eliminating the need to re-apply the mask each and every time a particular
 * tile is drawn.
 *
 * To apply this mask, since CSS masking is (at this time) in its infancy, we
 * must use the canvas element. Canvas XOR masks, however, do not help us ---
 * they apply the mask using the alpha channel, whereas we want to apply based
 * on the brightness of a particular pixel. Therefore, our solution will be to
 * grab the image data and manipulate each pixel individually, adjusting the
 * alpha channel to either 255 for opaque or 0 for transparent. Since the mask
 * is either black or white, we needn't calculate the brightness --- we can
 * simply check the color value of a single channel (e.g. R) and make the pixel
 * entirely transparent if the value is !== 0.
 *
 * Remember that certain tiles contain no mask. Since they are not filled with
 * black, we must be able to recognize when we should *not* apply a mask;
 * otherwise, the tile will be entire transparent! Coupling this unfortunate
 * detail with the fact that putImageData() does not support slicing like
 * drawImage() does, it makes more sense to store each tile individually in
 * memory rather than as a single image. Otherwise, we would be forced to use
 * drawImage() and re-apply the mask each time a tile is drawn, which is not
 * worth the little extra memory that will be consumed by separate tile images.
 * Given this implementation, we may then let the LtgLoader know specifically
 * what tiles should have masks applied.
 *
 * With that, we should have an easy-to-use set of tile graphics ready for
 * rendering.
 */

/**
 * Slices tiles and applies masks
 */
ltjs.TileMasker = Class( 'TileMasker',
{
    /**
     * Canvas 2D context (used for masking and tile slicing)
     * @type {CanvasRenderingContext2d}
     */
    'private _context': null,

    /**
     * Tile definition to use for all operations
     * @type {Array.<Array.<string,number>>}
     */
    'private _tileDfn': null,

    /**
     * Width of each individual tile
     * @type {number}
     */
    'private _tileWidth': 0,

    /**
     * Height of each individual tile
     * @type {number}
     */
    'private _tileHeight': 0,

    /**
     * Number of tiles per row
     * @type {number}
     */
    'private _tilesPerRow': 0,

    /**
     * Calculated width of tile set provided a tile definition
     * @type {number}
     */
    'private _setWidth': 0,

    /**
     * Calculated height of tile set provided a tile definition
     * @type {number}
     */
    'private _setHeight': 0,


    /**
     * Initialize loader with a tile definition
     *
     * The tile definition defines how a tile set should be interpreted. This
     * allows us to support *any* type of tile set -- not just those that are
     * defined by the original game.
     *
     * @param  {ltjs.TileDfn}  tile_dfn  tile definition object
     */
    __construct: function( tile_dfn )
    {
        if ( !( Class.isA( ltjs.TileDfn, tile_dfn ) ) )
        {
            throw TypeError( "Invalid tile definition provided." );
        }

        // pre-calculate our tile information
        this._tileDfn = tile_dfn.getTileDefinition();
        this._calcSetDimensions( tile_dfn );

        // rather than accepting a context, we will create our own canvas in
        // memory to perform our operations (it will not be added to the DOM, so
        // these operations will not be visible to the user)
        var context = document.createElement( 'canvas' ).getContext( '2d' );

        // size the canvas so that it can fit the entire tileset
        context.canvas.width  = this._setWidth;
        context.canvas.height = this._setHeight;

        this._context = context;
    },


    /**
     * Calculate tile set dimensions from the given tile definition object
     *
     * These dimensions are cached, as these are frequently used and it is
     * unwise to continuously invoke methods unnecessarily (who knows what the
     * developer of the given tile definition did!).
     *
     * @param  {ltjs.TileDfn}  tile_dfn  tile definition object
     *
     * @return  {undefined}
     */
    'private _calcSetDimensions': function( tile_dfn )
    {
        // these vars are for clarity
        var sizes = tile_dfn.getTileDimensions(),
            n     = this._tileDfn.length;

        // store values so that we do not have to make additional calls to our
        // TileDfn instance
        this._tileWidth   = sizes[ 0 ];
        this._tileHeight  = sizes[ 1 ];
        this._tilesPerRow = sizes[ 2 ];

        // calculate full width and height of tile set
        this._setWidth  = ( this._tileWidth * this._tilesPerRow );
        this._setHeight = (
            Math.ceil( n / this._tilesPerRow ) * this._tileHeight
        );
    },


    /**
     * Retrieve image data for each individual tile (pre-masked)
     *
     * Each tile will have the mask applied before being returned. This allows
     * the tile to be rendered without any additional processing, but at the
     * cost of additional overhead for the tile loading (which is well worth it,
     * since we will be spending the majority of our time rendering tiles, not
     * loading them).
     *
     * This operation is asynchronous, but the masking algorithm is not. If
     * performance is a concern during the masking process (for example, if one
     * were to create an extension to support very large tilesets), one can
     * extend this class to make the operation asynchronous.
     *
     * @param  {string}  bmp_game  game tileset bitmap (URL or data URL)
     * @param  {string}  bmp_mask  game tileset mask bitmap (URL or data URL)
     *
     * @param  {function(Object)}  callback  function to call with tiles
     *
     * @return  {ltjs.TileMasker}  self
     */
    'public getMaskedTiles': function( bmp_game, bmp_mask, callback )
    {
        var _self = this;

        this._getImageData( bmp_mask, function( data_mask )
        {
            // we will render the game image after the mask so that it does not
            // need to be re-rendered in order to pull out the image data
            _self._renderImage( bmp_game, function()
            {
                _self.getMaskedTileSet( data_mask, callback );
            } );
        } );

        return this;
    },


    /**
     * For use by subtypes that may need access to the otherwise private data
     *
     * See getMaskedTileSet().
     *
     * @return  {Array.<number>}  tile width, height and number per row
     */
    'protected getTileDimensions': function()
    {
        return [ this._tileWidth, this._tileHeight, this._tilesPerRow ];
    },


    /**
     * Apply mask to each tile and return individual tiles
     *
     * This method requires that the tileset has already been rendered to the
     * canvas.
     *
     * Note that, although this method accepts a callback, it is not
     * asynchronous. It does, however, allow subtypes to make this algorithm
     * asynchronous should the need arise. See getMaskedTiles() for more
     * information.
     *
     * @param  {Object}            data_mask  image data for mask bitmap
     * @param  {function(Object)}  callback   function to call with tiles
     *
     * @return  {undefined}
     */
    'virtual protected getMaskedTileSet': function( data_mask, callback )
    {
        var tdata = this._tileDfn,
            tiles = {},
            i     = -1,
            len   = tdata.length,

            // shorten the names
            tw = this._tileWidth,
            th = this._tileHeight,
            xn = this._tilesPerRow;

        // create each tile (preserving order, thus no decrementing)
        while ( ++i < len )
        {
            var id   = tdata[ i ][ 0 ],
                mask = tdata[ i ][ 1 ],

                // calculate the X and Y position of this tile based on the tile
                // and bitmap dimensions
                x = ( ( i % xn ) * th ),
                y = ( ( Math.floor( i / xn ) ) * tw );

            // the third index indicates whether or not a mask should be applied
            // to the tile
            this.appendTileFrame( tiles, id, mask, ( mask === 1 )
                ? this.getMaskedTileData( data_mask, x, y )
                : this.getTileData( x, y )
            );
        }

        callback( tiles );
    },


    /**
     * Adds a tile frame to the set, permitting animation
     *
     * This creates a circular linked list with each of the frames for a given
     * tile id. This structure is ideal for looping animations. One can simply
     * check to see if the tile has a single frame by performing a strict
     * equality check on the current tile and its 'next' entry.
     *
     * @param  {Object.<string>}  set   set to append tile frame to
     * @param  {string}           id    tile id
     * @param  {Object}           data  tile ImageData
     *
     * @return  {undefined}
     */
    'protected appendTileFrame': function( set, id, mask, data )
    {
        var prev = set[ id ];

        set[ id ] = {
            data:   data,
            masked: mask
        };

        // If there is a previous frame, set the 'next' entry to its 'next'
        // entry to maintain the circular reference. Otherwise, set to self.
        // This can also be stored as the 'first' reference to permit quickly
        // resetting an animation.
        set[ id ].next = set[ id ].first = ( prev )
            ? prev.next
            : set[ id ];

        // if there was a previous entry, set its 'next' entry to our new frame,
        // expanding the linked list
        prev && ( prev.next = set[ id ] )
    },


    /**
     * Retrieve a tile with the mask applied
     *
     * This algorithm uses the image rendered to the canvas along with the given
     * mask image data to alter the alpha channel of the tile, producing a tile
     * with the appropriate transparency.
     *
     * The LaserTank mask considered black to be opaque and white to be
     * transparent. Since those are the only two colors permitted, we can
     * improve performance by checking only a single channel rather than
     * calculating brightness. If not black, the respective pixel in the tile
     * will be considered transparent.
     *
     * Only the image data for the requested tile will be returned. That is, the
     * image data will represent a single tile and it can be rendered directly
     * to the canvas.
     *
     * WARNING: Not all tiles have masks. This method should not be used unless
     * the tile has a mask. The result is otherwise LTG-dependent, since some
     * LTG files do not have fully opaque masks for those tiles.
     *
     * @param  {Object}  data_mask  image data for the mask bitmap
     * @param  {number}  x          tile X position in game/mask bitmap
     * @param  {number}  y          tile Y position in game/mask bitmap
     *
     * @return  {Object}  image data for the requested tile
     */
    'virtual protected getMaskedTileData': function( data_mask, x, y )
    {
        var raw = this.getTileData( x, y ),
            w   = raw.width,
            h   = raw.height,
            mw  = data_mask.width,
            yi  = h;

        // apply the mask to the raw tile data (simple and easy-to-understand
        // algorithm; we can refine it later if need be), looping through each
        // pixel
        while ( yi-- )
        {
            xi = w;

            while ( xi-- )
            {
                // get the R value for the associated pixel in the mask bitmap
                // (remember that, although we are dealing with applying the
                // mask to a single tile, the mask image contains all tiles, so
                // we must calculate its position accordingly)
                var mi = ( ( ( yi + y ) * ( mw * 4 ) ) + ( ( xi + x ) * 4 ) ),
                    mr = data_mask.data[ mi ];

                // manipulate the alpha channel of our tile; if the R value for
                // the mask is not 0, then this pixel in our tile should be
                // transparent (we need only check the R pixel since the mask
                // consists of only black and white, so there is no need to
                // calculate brightness)
                raw.data[ ( ( yi * w * 4 ) + ( xi * 4 ) ) + 3 ] =
                    ( mr === 0 ) ? 255 : 0;
            }
        }

        return raw;
    },


    /**
     * Retrieve image data for the tile at the given position
     *
     * @param  {number}  x  tile X position in bitmap
     * @param  {number}  y  tile Y position in bitmap
     *
     * @return  {Object}  image data for tile
     **/
    'protected getTileData': function( x, y )
    {
        return this._context.getImageData(
            x, y, this._tileWidth, this._tileHeight
        );
    },


    /**
     * Render an image to the canvas
     *
     * This operation is asynchronous and supports loading of external
     * resources. Note that an external resource that violates the browser's
     * cross-site security policies will taint the canvas, preventing the
     * masking operation. Using data URLs will avoid this issue entirely.
     *
     * @param  {string}           bmp       image URL or data URL
     * @param  {function(Image)}  callback  function to call when complete
     *
     * @return  {undefined}
     */
    'private _renderImage': function( bmp, callback )
    {
        var _self = this,
            img   = new Image();

        img.onload = function()
        {
            _self._context.drawImage( img, 0, 0 );
            callback( img );
        };

        img.src = bmp;
    },


    /**
     * Retrieve the canvas image data of the given bitmap
     *
     * @param  {string}           bmp       image URL or data URL
     * @param  {function(Image)}  callback  function to call when complete
     *
     * @return  {undefined}
     */
    'private _getImageData': function( bmp, callback )
    {
        var _self = this;

        this._renderImage( bmp, function()
        {
            callback(
                _self._context.getImageData(
                    0, 0, _self._setWidth, _self._setHeight
                )
            );

        } );
    }
} );