#

API Docs for: 1.5.0
Show: Inherited Protected Private Deprecated

# File: src/pixi/primitives/Graphics.js

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

    /**
     * The Graphics class contains a set of methods that you can use to create primitive shapes and lines.
     * It is important to know that with the webGL renderer only simple polygons can be filled at this stage
     * Complex polygons will not be filled. Heres an example of a complex polygon: http://www.goodboydigital.com/wp-content/uploads/2013/06/complexPolygon.png
     *
     * @class Graphics
     * @extends DisplayObjectContainer
     * @constructor
     */
    PIXI.Graphics = function()
    {
        PIXI.DisplayObjectContainer.call( this );

        this.renderable = true;

        /**
         * The alpha of the fill of this graphics object
         *
         * @property fillAlpha
         * @type Number
         */
        this.fillAlpha = 1;

        /**
         * The width of any lines drawn
         *
         * @property lineWidth
         * @type Number
         */
        this.lineWidth = 0;

        /**
         * The color of any lines drawn
         *
         * @property lineColor
         * @type String
         */
        this.lineColor = "black";

        /**
         * Graphics data
         *
         * @property graphicsData
         * @type Array
         * @private
         */
        this.graphicsData = [];

        /**
         * The tint applied to the graphic shape. This is a hex value
         *
         * @property tint
         * @type Number
         * @default 0xFFFFFF
         */
        this.tint = 0xFFFFFF;// * Math.random();

        /**
         * The blend mode to be applied to the graphic shape
         *
         * @property blendMode
         * @type Number
         * @default PIXI.blendModes.NORMAL;
         */
        this.blendMode = PIXI.blendModes.NORMAL;

        /**
         * Current path
         *
         * @property currentPath
         * @type Object
         * @private
         */
        this.currentPath = {points:[]};

        /**
         * Array containing some WebGL-related properties used by the WebGL renderer
         *
         * @property _webGL
         * @type Array
         * @private
         */
        this._webGL = [];

        /**
         * Whether this shape is being used as a mask
         *
         * @property isMask
         * @type isMask
         */
        this.isMask = false;

        /**
         * The bounds of the graphic shape as rectangle object
         *
         * @property bounds
         * @type Rectangle
         */
        this.bounds = null;

        /**
         * the bounds' padding used for bounds calculation
         *
         * @property bounds
         * @type Number
         */
        this.boundsPadding = 10;
    };

    // constructor
    PIXI.Graphics.prototype = Object.create( PIXI.DisplayObjectContainer.prototype );
    PIXI.Graphics.prototype.constructor = PIXI.Graphics;

    /**
     * If cacheAsBitmap is true the graphics object will then be rendered as if it was a sprite.
     * This is useful if your graphics element does not change often as it will speed up the rendering of the object
     * It is also usful as the graphics object will always be antialiased because it will be rendered using canvas
     * Not recommended if you are constanly redrawing the graphics element.
     *
     * @property cacheAsBitmap
     * @default false
     * @type Boolean
     * @private
     */
    Object.defineProperty(PIXI.Graphics.prototype, "cacheAsBitmap", {
        get: function() {
            return  this._cacheAsBitmap;
        },
        set: function(value) {
            this._cacheAsBitmap = value;

            if(this._cacheAsBitmap)
            {
                this._generateCachedSprite();
            }
            else
            {
                this.destroyCachedSprite();
                this.dirty = true;
            }

        }
    });

    /**
     * Specifies the line style used for subsequent calls to Graphics methods such as the lineTo() method or the drawCircle() method.
     *
     * @method lineStyle
     * @param lineWidth {Number} width of the line to draw, will update the object's stored style
     * @param color {Number} color of the line to draw, will update the object's stored style
     * @param alpha {Number} alpha of the line to draw, will update the object's stored style
     */
    PIXI.Graphics.prototype.lineStyle = function(lineWidth, color, alpha)
    {
        if (!this.currentPath.points.length) this.graphicsData.pop();

        this.lineWidth = lineWidth || 0;
        this.lineColor = color || 0;
        this.lineAlpha = (arguments.length < 3) ? 1 : alpha;

        this.currentPath = {lineWidth:this.lineWidth, lineColor:this.lineColor, lineAlpha:this.lineAlpha,
                            fillColor:this.fillColor, fillAlpha:this.fillAlpha, fill:this.filling, points:[], type:PIXI.Graphics.POLY};

        this.graphicsData.push(this.currentPath);

        return this;
    };

    /**
     * Moves the current drawing position to (x, y).
     *
     * @method moveTo
     * @param x {Number} the X coordinate to move to
     * @param y {Number} the Y coordinate to move to
     */
    PIXI.Graphics.prototype.moveTo = function(x, y)
    {
        if (!this.currentPath.points.length) this.graphicsData.pop();

        this.currentPath = this.currentPath = {lineWidth:this.lineWidth, lineColor:this.lineColor, lineAlpha:this.lineAlpha,
                            fillColor:this.fillColor, fillAlpha:this.fillAlpha, fill:this.filling, points:[], type:PIXI.Graphics.POLY};

        this.currentPath.points.push(x, y);

        this.graphicsData.push(this.currentPath);

        return this;
    };

    /**
     * Draws a line using the current line style from the current drawing position to (x, y);
     * the current drawing position is then set to (x, y).
     *
     * @method lineTo
     * @param x {Number} the X coordinate to draw to
     * @param y {Number} the Y coordinate to draw to
     */
    PIXI.Graphics.prototype.lineTo = function(x, y)
    {
        this.currentPath.points.push(x, y);
        this.dirty = true;

        return this;
    };

    /**
     * Specifies a simple one-color fill that subsequent calls to other Graphics methods
     * (such as lineTo() or drawCircle()) use when drawing.
     *
     * @method beginFill
     * @param color {Number} the color of the fill
     * @param alpha {Number} the alpha of the fill
     */
    PIXI.Graphics.prototype.beginFill = function(color, alpha)
    {

        this.filling = true;
        this.fillColor = color || 0;
        this.fillAlpha = (arguments.length < 2) ? 1 : alpha;

        return this;
    };

    /**
     * Applies a fill to the lines and shapes that were added since the last call to the beginFill() method.
     *
     * @method endFill
     */
    PIXI.Graphics.prototype.endFill = function()
    {
        this.filling = false;
        this.fillColor = null;
        this.fillAlpha = 1;

        return this;
    };

    /**
     * @method drawRect
     *
     * @param x {Number} The X coord of the top-left of the rectangle
     * @param y {Number} The Y coord of the top-left of the rectangle
     * @param width {Number} The width of the rectangle
     * @param height {Number} The height of the rectangle
     */
    PIXI.Graphics.prototype.drawRect = function( x, y, width, height )
    {
        if (!this.currentPath.points.length) this.graphicsData.pop();

        this.currentPath = {lineWidth:this.lineWidth, lineColor:this.lineColor, lineAlpha:this.lineAlpha,
                            fillColor:this.fillColor, fillAlpha:this.fillAlpha, fill:this.filling,
                            points:[x, y, width, height], type:PIXI.Graphics.RECT};

        this.graphicsData.push(this.currentPath);
        this.dirty = true;

        return this;
    };

    /**
     * Draws a circle.
     *
     * @method drawCircle
     * @param x {Number} The X coordinate of the center of the circle
     * @param y {Number} The Y coordinate of the center of the circle
     * @param radius {Number} The radius of the circle
     */
    PIXI.Graphics.prototype.drawCircle = function( x, y, radius)
    {

        if (!this.currentPath.points.length) this.graphicsData.pop();

        this.currentPath = {lineWidth:this.lineWidth, lineColor:this.lineColor, lineAlpha:this.lineAlpha,
                            fillColor:this.fillColor, fillAlpha:this.fillAlpha, fill:this.filling,
                            points:[x, y, radius, radius], type:PIXI.Graphics.CIRC};

        this.graphicsData.push(this.currentPath);
        this.dirty = true;

        return this;
    };

    /**
     * Draws an ellipse.
     *
     * @method drawEllipse
     * @param x {Number} The X coordinate of the upper-left corner of the framing rectangle of this ellipse
     * @param y {Number} The Y coordinate of the upper-left corner of the framing rectangle of this ellipse
     * @param width {Number} The width of the ellipse
     * @param height {Number} The height of the ellipse
     */
    PIXI.Graphics.prototype.drawEllipse = function( x, y, width, height)
    {

        if (!this.currentPath.points.length) this.graphicsData.pop();

        this.currentPath = {lineWidth:this.lineWidth, lineColor:this.lineColor, lineAlpha:this.lineAlpha,
                            fillColor:this.fillColor, fillAlpha:this.fillAlpha, fill:this.filling,
                            points:[x, y, width, height], type:PIXI.Graphics.ELIP};

        this.graphicsData.push(this.currentPath);
        this.dirty = true;

        return this;
    };

    /**
     * Clears the graphics that were drawn to this Graphics object, and resets fill and line style settings.
     *
     * @method clear
     */
    PIXI.Graphics.prototype.clear = function()
    {
        this.lineWidth = 0;
        this.filling = false;

        this.dirty = true;
        this.clearDirty = true;
        this.graphicsData = [];

        this.bounds = null; //new PIXI.Rectangle();

        return this;
    };

    /**
     * Useful function that returns a texture of the graphics object that can then be used to create sprites
     * This can be quite useful if your geometry is complicated and needs to be reused multiple times.
     *
     * @method generateTexture
     * @return {Texture} a texture of the graphics object
     */
    PIXI.Graphics.prototype.generateTexture = function()
    {
        var bounds = this.getBounds();

        var canvasBuffer = new PIXI.CanvasBuffer(bounds.width, bounds.height);
        var texture = PIXI.Texture.fromCanvas(canvasBuffer.canvas);

        canvasBuffer.context.translate(-bounds.x,-bounds.y);

        PIXI.CanvasGraphics.renderGraphics(this, canvasBuffer.context);

        return texture;
    };

    /**
    * Renders the object using the WebGL renderer
    *
    * @method _renderWebGL
    * @param renderSession {RenderSession}
    * @private
    */
    PIXI.Graphics.prototype._renderWebGL = function(renderSession)
    {
        // if the sprite is not visible or the alpha is 0 then no need to render this element
        if(this.visible === false || this.alpha === 0 || this.isMask === true)return;

        if(this._cacheAsBitmap)
        {

            if(this.dirty)
            {
                this._generateCachedSprite();
                // we will also need to update the texture on the gpu too!
                PIXI.updateWebGLTexture(this._cachedSprite.texture.baseTexture, renderSession.gl);

                this.dirty =  false;
            }

            this._cachedSprite.alpha = this.alpha;
            PIXI.Sprite.prototype._renderWebGL.call(this._cachedSprite, renderSession);

            return;
        }
        else
        {
            renderSession.spriteBatch.stop();

            if(this._mask)renderSession.maskManager.pushMask(this.mask, renderSession);
            if(this._filters)renderSession.filterManager.pushFilter(this._filterBlock);

            // check blend mode
            if(this.blendMode !== renderSession.spriteBatch.currentBlendMode)
            {
                renderSession.spriteBatch.currentBlendMode = this.blendMode;
                var blendModeWebGL = PIXI.blendModesWebGL[renderSession.spriteBatch.currentBlendMode];
                renderSession.spriteBatch.gl.blendFunc(blendModeWebGL[0], blendModeWebGL[1]);
            }

            PIXI.WebGLGraphics.renderGraphics(this, renderSession);

            // only render if it has children!
            if(this.children.length)
            {
                renderSession.spriteBatch.start();

                 // simple render children!
                for(var i=0, j=this.children.length; i<j; i++)
                {
                    this.children[i]._renderWebGL(renderSession);
                }

                renderSession.spriteBatch.stop();
            }

            if(this._filters)renderSession.filterManager.popFilter();
            if(this._mask)renderSession.maskManager.popMask(renderSession);

            renderSession.drawCount++;

            renderSession.spriteBatch.start();
        }
    };

    /**
    * Renders the object using the Canvas renderer
    *
    * @method _renderCanvas
    * @param renderSession {RenderSession}
    * @private
    */
    PIXI.Graphics.prototype._renderCanvas = function(renderSession)
    {
        // if the sprite is not visible or the alpha is 0 then no need to render this element
        if(this.visible === false || this.alpha === 0 || this.isMask === true)return;

        var context = renderSession.context;
        var transform = this.worldTransform;

        if(this.blendMode !== renderSession.currentBlendMode)
        {
            renderSession.currentBlendMode = this.blendMode;
            context.globalCompositeOperation = PIXI.blendModesCanvas[renderSession.currentBlendMode];
        }

        context.setTransform(transform.a, transform.c, transform.b, transform.d, transform.tx, transform.ty);
        PIXI.CanvasGraphics.renderGraphics(this, context);

         // simple render children!
        for(var i=0, j=this.children.length; i<j; i++)
        {
            this.children[i]._renderCanvas(renderSession);
        }
    };

    /**
     * Retrieves the bounds of the graphic shape as a rectangle object
     *
     * @method getBounds
     * @return {Rectangle} the rectangular bounding area
     */
    PIXI.Graphics.prototype.getBounds = function( matrix )
    {
        if(!this.bounds)this.updateBounds();

        var w0 = this.bounds.x;
        var w1 = this.bounds.width + this.bounds.x;

        var h0 = this.bounds.y;
        var h1 = this.bounds.height + this.bounds.y;

        var worldTransform = matrix || this.worldTransform;

        var a = worldTransform.a;
        var b = worldTransform.c;
        var c = worldTransform.b;
        var d = worldTransform.d;
        var tx = worldTransform.tx;
        var ty = worldTransform.ty;

        var x1 = a * w1 + c * h1 + tx;
        var y1 = d * h1 + b * w1 + ty;

        var x2 = a * w0 + c * h1 + tx;
        var y2 = d * h1 + b * w0 + ty;

        var x3 = a * w0 + c * h0 + tx;
        var y3 = d * h0 + b * w0 + ty;

        var x4 =  a * w1 + c * h0 + tx;
        var y4 =  d * h0 + b * w1 + ty;

        var maxX = -Infinity;
        var maxY = -Infinity;

        var minX = Infinity;
        var minY = Infinity;

        minX = x1 < minX ? x1 : minX;
        minX = x2 < minX ? x2 : minX;
        minX = x3 < minX ? x3 : minX;
        minX = x4 < minX ? x4 : minX;

        minY = y1 < minY ? y1 : minY;
        minY = y2 < minY ? y2 : minY;
        minY = y3 < minY ? y3 : minY;
        minY = y4 < minY ? y4 : minY;

        maxX = x1 > maxX ? x1 : maxX;
        maxX = x2 > maxX ? x2 : maxX;
        maxX = x3 > maxX ? x3 : maxX;
        maxX = x4 > maxX ? x4 : maxX;

        maxY = y1 > maxY ? y1 : maxY;
        maxY = y2 > maxY ? y2 : maxY;
        maxY = y3 > maxY ? y3 : maxY;
        maxY = y4 > maxY ? y4 : maxY;

        var bounds = this._bounds;

        bounds.x = minX;
        bounds.width = maxX - minX;

        bounds.y = minY;
        bounds.height = maxY - minY;

        return bounds;
    };

    /**
     * Update the bounds of the object
     *
     * @method updateBounds
     */
    PIXI.Graphics.prototype.updateBounds = function()
    {

        var minX = Infinity;
        var maxX = -Infinity;

        var minY = Infinity;
        var maxY = -Infinity;

        var points, x, y, w, h;

        for (var i = 0; i < this.graphicsData.length; i++) {
            var data = this.graphicsData[i];
            var type = data.type;
            var lineWidth = data.lineWidth;

            points = data.points;

            if(type === PIXI.Graphics.RECT)
            {
                x = points[0] - lineWidth/2;
                y = points[1] - lineWidth/2;
                w = points[2] + lineWidth;
                h = points[3] + lineWidth;

                minX = x < minX ? x : minX;
                maxX = x + w > maxX ? x + w : maxX;

                minY = y < minY ? x : minY;
                maxY = y + h > maxY ? y + h : maxY;
            }
            else if(type === PIXI.Graphics.CIRC || type === PIXI.Graphics.ELIP)
            {
                x = points[0];
                y = points[1];
                w = points[2] + lineWidth/2;
                h = points[3] + lineWidth/2;

                minX = x - w < minX ? x - w : minX;
                maxX = x + w > maxX ? x + w : maxX;

                minY = y - h < minY ? y - h : minY;
                maxY = y + h > maxY ? y + h : maxY;
            }
            else
            {
                // POLY
                for (var j = 0; j < points.length; j+=2)
                {

                    x = points[j];
                    y = points[j+1];
                    minX = x-lineWidth < minX ? x-lineWidth : minX;
                    maxX = x+lineWidth > maxX ? x+lineWidth : maxX;

                    minY = y-lineWidth < minY ? y-lineWidth : minY;
                    maxY = y+lineWidth > maxY ? y+lineWidth : maxY;
                }
            }
        }

        var padding = this.boundsPadding;
        this.bounds = new PIXI.Rectangle(minX - padding, minY - padding, (maxX - minX) + padding * 2, (maxY - minY) + padding * 2);
    };

    /**
     * Generates the cached sprite when the sprite has cacheAsBitmap = true
     *
     * @method _generateCachedSprite
     * @private
     */
    PIXI.Graphics.prototype._generateCachedSprite = function()
    {
        var bounds = this.getLocalBounds();

        if(!this._cachedSprite)
        {
            var canvasBuffer = new PIXI.CanvasBuffer(bounds.width, bounds.height);
            var texture = PIXI.Texture.fromCanvas(canvasBuffer.canvas);

            this._cachedSprite = new PIXI.Sprite(texture);
            this._cachedSprite.buffer = canvasBuffer;

            this._cachedSprite.worldTransform = this.worldTransform;
        }
        else
        {
            this._cachedSprite.buffer.resize(bounds.width, bounds.height);
        }

        // leverage the anchor to account for the offset of the element
        this._cachedSprite.anchor.x = -( bounds.x / bounds.width );
        this._cachedSprite.anchor.y = -( bounds.y / bounds.height );

       // this._cachedSprite.buffer.context.save();
        this._cachedSprite.buffer.context.translate(-bounds.x,-bounds.y);

        PIXI.CanvasGraphics.renderGraphics(this, this._cachedSprite.buffer.context);
        this._cachedSprite.alpha = this.alpha;

       // this._cachedSprite.buffer.context.restore();
    };

    PIXI.Graphics.prototype.destroyCachedSprite = function()
    {
        this._cachedSprite.texture.destroy(true);

        // let the gc collect the unused sprite
        // TODO could be object pooled!
        this._cachedSprite = null;
    };

    // SOME TYPES:
    PIXI.Graphics.POLY = 0;
    PIXI.Graphics.RECT = 1;
    PIXI.Graphics.CIRC = 2;
    PIXI.Graphics.ELIP = 3;