#

API Docs for: 1.4.0
Show: Inherited Protected Private Deprecated

# File: src/pixi/textures/Texture.js

    /**
     * @author Mat Groves http://matgroves.com/ @Doormat23
     */

    PIXI.TextureCache = {};
    PIXI.FrameCache = {};

    /**
     * A texture stores the information that represents an image or part of an image. It cannot be added
     * to the display list directly. To do this use PIXI.Sprite. If no frame is provided then the whole image is used
     *
     * @class Texture
     * @uses EventTarget
     * @constructor
     * @param baseTexture {BaseTexture} The base texture source to create the texture from
     * @param frame {Rectangle} The rectangle frame of the texture to show
     */
    PIXI.Texture = function(baseTexture, frame)
    {
        PIXI.EventTarget.call( this );

        if(!frame)
        {
            this.noFrame = true;
            frame = new PIXI.Rectangle(0,0,1,1);
        }

        if(baseTexture instanceof PIXI.Texture)
            baseTexture = baseTexture.baseTexture;

        /**
         * The base texture of this texture
         *
         * @property baseTexture
         * @type BaseTexture
         */
        this.baseTexture = baseTexture;

        /**
         * The frame specifies the region of the base texture that this texture uses
         *
         * @property frame
         * @type Rectangle
         */
        this.frame = frame;

        /**
         * The trim point
         *
         * @property trim
         * @type Point
         */
        this.trim = new PIXI.Point();

        this.scope = this;

        if(baseTexture.hasLoaded)
        {
            if(this.noFrame)frame = new PIXI.Rectangle(0,0, baseTexture.width, baseTexture.height);

            this.setFrame(frame);
        }
        else
        {
            var scope = this;
            baseTexture.addEventListener('loaded', function(){ scope.onBaseTextureLoaded(); });
        }
    };

    PIXI.Texture.prototype.constructor = PIXI.Texture;

    /**
     * Called when the base texture is loaded
     *
     * @method onBaseTextureLoaded
     * @param event
     * @private
     */
    PIXI.Texture.prototype.onBaseTextureLoaded = function()
    {
        var baseTexture = this.baseTexture;
        baseTexture.removeEventListener( 'loaded', this.onLoaded );

        if(this.noFrame)this.frame = new PIXI.Rectangle(0,0, baseTexture.width, baseTexture.height);

        this.setFrame(this.frame);

        this.scope.dispatchEvent( { type: 'update', content: this } );
    };

    /**
     * Destroys this texture
     *
     * @method destroy
     * @param destroyBase {Boolean} Whether to destroy the base texture as well
     */
    PIXI.Texture.prototype.destroy = function(destroyBase)
    {
        if(destroyBase) this.baseTexture.destroy();
    };

    /**
     * Specifies the rectangle region of the baseTexture
     *
     * @method setFrame
     * @param frame {Rectangle} The frame of the texture to set it to
     */
    PIXI.Texture.prototype.setFrame = function(frame)
    {
        this.frame = frame;
        this.width = frame.width;
        this.height = frame.height;

        if(frame.x + frame.width > this.baseTexture.width || frame.y + frame.height > this.baseTexture.height)
        {
            throw new Error('Texture Error: frame does not fit inside the base Texture dimensions ' + this);
        }

        this.updateFrame = true;

        PIXI.Texture.frameUpdates.push(this);
        //this.dispatchEvent( { type: 'update', content: this } );
    };

    PIXI.Texture.prototype._updateWebGLuvs = function()
    {
        if(!this._uvs)this._uvs = new Float32Array(8);

        var frame = this.frame;
        var tw = this.baseTexture.width;
        var th = this.baseTexture.height;

        this._uvs[0] = frame.x / tw;
        this._uvs[1] = frame.y / th;

        this._uvs[2] = (frame.x + frame.width) / tw;
        this._uvs[3] = frame.y / th;

        this._uvs[4] = (frame.x + frame.width) / tw;
        this._uvs[5] = (frame.y + frame.height) / th;

        this._uvs[6] = frame.x / tw;
        this._uvs[7] = (frame.y + frame.height) / th;
    };

    /**
     * Helper function that returns a texture based on an image url
     * If the image is not in the texture cache it will be  created and loaded
     *
     * @static
     * @method fromImage
     * @param imageUrl {String} The image url of the texture
     * @param crossorigin {Boolean} Whether requests should be treated as crossorigin
     * @return Texture
     */
    PIXI.Texture.fromImage = function(imageUrl, crossorigin, scaleMode)
    {
        var texture = PIXI.TextureCache[imageUrl];

        if(!texture)
        {
            texture = new PIXI.Texture(PIXI.BaseTexture.fromImage(imageUrl, crossorigin, scaleMode));
            PIXI.TextureCache[imageUrl] = texture;
        }

        return texture;
    };

    /**
     * Helper function that returns a texture based on a frame id
     * If the frame id is not in the texture cache an error will be thrown
     *
     * @static
     * @method fromFrame
     * @param frameId {String} The frame id of the texture
     * @return Texture
     */
    PIXI.Texture.fromFrame = function(frameId)
    {
        var texture = PIXI.TextureCache[frameId];
        if(!texture) throw new Error('The frameId "' + frameId + '" does not exist in the texture cache ' + this);
        return texture;
    };

    /**
     * Helper function that returns a texture based on a canvas element
     * If the canvas is not in the texture cache it will be  created and loaded
     *
     * @static
     * @method fromCanvas
     * @param canvas {Canvas} The canvas element source of the texture
     * @return Texture
     */
    PIXI.Texture.fromCanvas = function(canvas, scaleMode)
    {
        var baseTexture = new PIXI.BaseTexture(canvas, scaleMode);
        return new PIXI.Texture(baseTexture);
    };

    /**
     * Adds a texture to the textureCache.
     *
     * @static
     * @method addTextureToCache
     * @param texture {Texture}
     * @param id {String} the id that the texture will be stored against.
     */
    PIXI.Texture.addTextureToCache = function(texture, id)
    {
        PIXI.TextureCache[id] = texture;
    };

    /**
     * Remove a texture from the textureCache.
     *
     * @static
     * @method removeTextureFromCache
     * @param id {String} the id of the texture to be removed
     * @return {Texture} the texture that was removed
     */
    PIXI.Texture.removeTextureFromCache = function(id)
    {
        var texture = PIXI.TextureCache[id];
        PIXI.TextureCache[id] = null;
        return texture;
    };

    // this is more for webGL.. it contains updated frames..
    PIXI.Texture.frameUpdates = [];

    PIXI.Texture.SCALE_MODE = PIXI.BaseTexture.SCALE_MODE;