/*
 * Paper.js
 *
 * This file is part of Paper.js, a JavaScript Vector Graphics Library,
 * based on Scriptographer.org and designed to be largely API compatible.
 * http://paperjs.org/
 * http://scriptographer.org/
 *
 * Copyright (c) 2011, Juerg Lehni & Jonathan Puckey
 * http://lehni.org/ & http://jonathanpuckey.com/
 *
 * Distributed under the MIT license. See LICENSE file for details.
 *
 * All rights reserved.
 */

/**
 * @name PlacedItem
 *
 * @class The PlacedItem class is the base for any items that have a matrix
 * associated with them, describing their placement in the project, such as
 * {@link Raster} and {@link PlacedSymbol}.
 *
 * @extends Item
 */
var PlacedItem = this.PlacedItem = Item.extend(/** @lends PlacedItem# */{

	_transform: function(matrix, flags) {
		// In order to set the right context transformation when drawing the
		// raster, simply preconcatenate the internal matrix with the provided
		// one.
		this._matrix.preConcatenate(matrix);
	},

	_changed: function(flags) {
		// Don't use base() for reasons of performance.
		Item.prototype._changed.call(this, flags);
		if (flags & ChangeFlag.GEOMETRY) {
			delete this._strokeBounds;
			// TODO: These are not used in Raster. Do we mind?
			delete this._handleBounds;
			delete this._roughBounds;
		}
	},

	/**
	 * The item's transformation matrix, defining position and dimensions in the
	 * document.
	 *
	 * @type Matrix
	 * @bean
	 */
	getMatrix: function() {
		return this._matrix;
	},

	setMatrix: function(matrix) {
		this._matrix = matrix.clone();
		this._changed(Change.GEOMETRY);
	},

	getBounds: function(/* matrix */) {
		// The bounds of PlacedItems are the same as the strokeBounds, but are
		// wrapped in a LinkedRectangle that catch changes for us.
		var useCache = arguments[0] === undefined;
		if (useCache && this._bounds)
			return this._bounds;
		var bounds = this.getStrokeBounds(arguments[0]);
		if (useCache)
			bounds = this._bounds = this._createBounds(bounds);
		return bounds;
	},

	_getBounds: function(getter, cacheName, args) {
		var matrix = args[0],
			useCache = matrix === undefined;
		if (useCache && this[cacheName])
			return this[cacheName];
		matrix = matrix ? matrix.clone().concatenate(this._matrix)
				: this._matrix;
		// Call _calculateBounds, which needs to be defined in the subclasses:
		var bounds = this._calculateBounds(getter, matrix);
		// TODO: Clear cache
		if (useCache)
			this[cacheName] = bounds;
		return bounds;
	}
});

@@ -1613,24 +1613,125 @@
 atrix */) %7B%0A
+%09%09var useCache = arguments%5B0%5D === undefined;%0A%09%09if (useCache && this._bounds)%0A%09%09%09return this._bounds;%0A
 %09%09// The bou
@@ -1856,109 +1856,8 @@
 us.%0A
-%09%09var useCache = arguments%5B0%5D === undefined;%0A%09%09if (useCache && this._bounds)%0A%09%09%09return this._bounds;%0A
 %09%09va
@@ -2167,16 +2167,73 @@
 eName%5D;%0A
+%09%09// Concatenate the passed matrix with the internal one%0A
 %09%09matrix
@@ -2436,31 +2436,8 @@
 x);%0A
-%09%09// TODO: Clear cache%0A
 %09%09if

Improve comments for bounds functions.