Merge remote-tracking branch 'refs/remotes/mrdoob/dev' into dev

docs/api/core/BufferAttribute.html

@@ -11,47 +11,86 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		This class stores data for an attribute associated with a [page:BufferGeometry]. See that page for details and a usage example. This class is used to store builtin attributes such as vertex position, normals, color, etc., but can also be used in your code to store custom attributes in a [page:BufferGeometry].
+		This class stores data for an attribute (such as vertex positions, face indices, normals,
+		colors, UVs, and any custom attributes ) associated with a [page:BufferGeometry], which allows
+		for more efficient passing of data to the GPU. See that page for details and a usage example.<br /><br />
+
+		Data is stored as vectors of any length (defined by [page:BufferAttribute.itemSize itemSize]),
+		and in general in the methods outlined below if passing in an index, this is automatically
+		multiplied by the vector length.
 		</div>
 
 		<h2>Constructor</h2>
 		<h3>[name]( [page:TypedArray array], [page:Integer itemSize], [page:Boolean normalized] )</h3>
 		<div>
-		Instantiates this attribute with data from the associated buffer.
-		itemSize gives the number of values of the array that should be associated with a particular vertex. normalized indicates how the underlying data in the buffer maps to the values in the GLSL shader code.
+		[page:TypedArray array] -- Must be a [link:https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/TypedArray TypedArray].
+		Used to instantiate the buffer. <br />
+		This array should have
+	 	<code>itemSize * numVertices</code>
+		elements, where numVertices is the number of vertices in the associated [page:BufferGeometry BufferGeometry].<br /><br />
+
+
+		[page:Integer itemSize] --  the number of values of the array that should be associated with
+		a particular vertex. For instance, if this
+		attribute is storing a 3-component vector (such as a position, normal, or color), then itemSize should be 3.
+		<br /><br />
+
+		[page:Boolean normalized] -- (optional) Indicates how the underlying data in the buffer maps
+		to the values in the GLSL code. For instance, if [page:TypedArray array] is an instance of
+		UInt16Array, and [page:Boolean normalized] is true, the values 0 - +65535 in the array
+		 data will be mapped to 0.0f - +1.0f in the GLSL attribute. An Int16Array (signed) would map
+		 from -32767 - +32767  to -1.0f - +1.0f. If [page:Boolean normalized] is false, the values
+		 will be converted to floats which contain the exact value, i.e. 32767 becomes 32767.0f.
 		</div>
 
 		<h2>Properties</h2>
 
 		<h3>[property:TypedArray array]</h3>
 		<div>
-		Stores the data associated with this attribute. This element should have <code>itemSize * numVertices</code> elements, where numVertices is the number of vertices in the associated [page:BufferGeometry geometry].  [page:TypedArray array] can be an instance of UInt8Array, Int8Array, UInt16Array, Int16Array, or Float32Array.
+		The [page:TypedArray array] holding data stored in the buffer.
 		</div>
 
-		<h3>[property:Integer itemSize]</h3>
+		<h3>[property:Integer count]</h3>
 		<div>
-		Records how many items of the array are associated with a particular vertex. For instance, if this
-		attribute is storing a 3-component vector (such as a position, normal, or color), then itemSize should be 3.
+		Stores the [page:BufferAttribute.array array]'s length divided by the [page:BufferAttribute.itemSize itemSize].<br /><br />
+
+		If the buffer is storing a 3-component vector (such as a position, normal, or color),
+		then this will count the number of such vectors stored.
 		</div>
 
-		<h3>[property:Integer count]</h3>
+		<h3>[property:Boolean dynamic]</h3>
 		<div>
-		Gives the total number of elements in the array.
+			Whether the buffer is dynamic or not. Default is *false*.<br />
+
+			If false, the GPU is informed that contents of the buffer are likely to be used often and not change often.
+			This corresponds to the  [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData gl.STATIC_DRAW] flag.<br />
+			if true, the GPU is informed that contents of the buffer are likely to be used often and change often.
+			This corresponds to the  [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData gl.DYNAMIC_DRAW] flag.
 		</div>
 
-		<h3>[property:Boolean needsUpdate]</h3>
+		<h3>[property:Boolean isBufferAttribute]</h3>
 		<div>
-		Flag to indicate that this attribute has changed and should be re-send to the GPU. Set this to true when you modify the value of the array.
+			Used to check whether this or derived classes are BufferAttributes. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
 		</div>
 
-		<h3>[property:Boolean normalized]</h3>
+		<h3>[property:Integer itemSize]</h3>
+		<div>The length of vectors that are being stored in the [page:BufferAttribute.array array].</div>
+
+
+		<h3>[property:Boolean needsUpdate]</h3>
 		<div>
-		Indicates how the underlying data in the buffer maps to the values in the GLSL code. For instance, if [page:TypedArray array] is an instance of UInt16Array, and [page:Boolean normalized] is true, the values 0 - +65535 in the array data will be mapped to 0.0f - +1.0f in the GLSL attribute. An Int16Array (signed) would map from -32767 - +32767  to -1.0f - +1.0f. If [page:Boolean normalized] is false, the values will be converted to floats which contain the exact value, i.e. 32767 becomes 32767.0f.
+		Flag to indicate that this attribute has changed and should be re-sent to the GPU.
+		Set this to true when you modify the value of the array.<br /><br />
+
+		Setting this to true also increments the [page:BufferAttribute.version version].
 		</div>
 
-		<h3>[property:Integer version]</h3>
+		<h3>[property:Boolean normalized]</h3>
 		<div>
-		A version number, incremented every time the needsUpdate property is set to true.
+		Indicates how the underlying data in the buffer maps to the values in the GLSL shader code.
+		See the constructor above for details.
 		</div>
 
 		<h3>[property:Function onUploadCallback]</h3>
@@ -59,64 +98,120 @@
 		A callback function that is executed after the Renderer has transfered the attribute array data to the GPU.
 		</div>
 
-		<h2>Methods</h2>
+		<h3>[property:Object updateRange]</h3>
+		<div>Object containing:<br />
+			[page:Integer offset]: Default is *0*. Position at whcih to start update.<br />
+			[page:Integer count]: Default is *-1*, which means don't use update ranges. <br /><br />
 
-		<h3>[method:null copyAt] ( [page:Integer index1], attribute, [page:Integer index2] ) </h3>
-		<div>
-		Copies itemSize values in the array from the vertex at index2 to the vertex at index1.
+			This can be used to only update some components of stored vectors (for example, just the component
+			related to color).
 		</div>
 
-		<h3>[method:null set] ( [page:Array value] ) </h3>
+		<h3>[property:String uuid]</h3>
 		<div>
-		Sets the associated array with values from the passed array.
+		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
+		This gets automatically assigned and this shouldn't be edited.
 		</div>
 
-		<h3>[method:null setX]( index, x ) </h3>
-		<div>
-		Sets the value of the array at <code>index * itemSize</code> to x
+		<h3>[property:Integer version]</h3>
+		<div>A version number, incremented every time the [page:BufferAttribute.needsUpdate needsUpdate] property is set to true.</div>
+
+
+		<h2>Methods</h2>
+
+		<h3>[method:BufferAttribute clone]() </h3>
+		<div>Return a copy of this bufferAttribute.</div>
+
+		<h3>[method:BufferAttribute copyArray]( array ) </h3>
+		<div>Copy the array given here (which can be a normal array or TypedArray) into
+			[page:BufferAttribute.array array].<br /><br />
+
+			See [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set TypedArray.set]
+			for notes on requirements if copying a TypedArray.
 		</div>
 
-		<h3>[method:null setY]( index, y ) </h3>
+		<h3>[method:null copyAt] ( [page:Integer index1], [page:BufferAttribute bufferAttribute], [page:Integer index2] ) </h3>
+		<div>Copy a vector from bufferAttribute[index2] to [page:BufferAttribute.array array][index1].</div>
+
+		<h3>[method:BufferAttribute copyColorsArray]( colors ) </h3>
+		<div>Copy an array representing RGB color values into [page:BufferAttribute.array array].</div>
+
+		<h3>[method:BufferAttribute copyIndicesArray]( indices ) </h3>
+		<div>Copy an array representing [page:Face3] indices into [page:BufferAttribute.array array].</div>
+
+		<h3>[method:BufferAttribute copyVector2sArray]( vectors ) </h3>
+		<div>Copy an array representing [page:Vector2]s into [page:BufferAttribute.array array].</div>
+
+		<h3>[method:BufferAttribute copyVector3sArray]( vectors ) </h3>
+		<div>Copy an array representing [page:Vector3]s into [page:BufferAttribute.array array].</div>
+
+		<h3>[method:BufferAttribute copyVector4sArray]( vectors ) </h3>
+		<div>Copy an array representing [page:Vector4]s into [page:BufferAttribute.array array].</div>
+
+		<h3>[method:Number getX]( index ) </h3>
+		<div>Returns the x component of the vector at the given index.</div>
+
+		<h3>[method:Number getY]( index ) </h3>
+		<div>Returns the y component of the vector at the given index.</div>
+
+		<h3>[method:Number getZ]( index ) </h3>
+		<div>Returns the z component of the vector at the given index.</div>
+
+		<h3>[method:Number getW]( index ) </h3>
+		<div>Returns the w component of the vector at the given index.</div>
+
+		<h3>[method:null onUpload]( [page:Function callback] ) </h3>
 		<div>
-		Sets the value of the array at <code>index * itemSize + 1</code> to y
+		Sets the value of the onUploadCallback property.<br /><br />
+
+		In the [example:webgl_buffergeometry WebGL / Buffergeometry] this is used to free memory
+		after the buffer has been	transfered to the GPU.
 		</div>
 
-		<h3>[method:null setZ]( index, z ) </h3>
+		<h3>[method:null set] ( [page:Array value], [page:Integer offset] ) </h3>
 		<div>
-		Sets the value of the array at <code>index * itemSize + 2</code> to z
+		value -- an [page:Array] or [page:TypedArray] from which to copy values. <br />
+		offset -- (optional) index of the [page:BufferAttribute.array array] at which to start copying.<br /><br />
+
+		Calls	[link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set TypedArray.set]( [page:Array value], [page:Integer offset] )
+		on the [page:BufferAttribute.array array].<br /><br />
+
+		In particular, see that page for requirements on [page:Array value]
+		being a [page:TypedArray].
 		</div>
 
-		<h3>[method:null setXY]( index, x, y ) </h3>
+		<h3>[method:null setArray] ( [page:TypedArray array] ) </h3>
 		<div>
-		Sets the value of the array at <code>index * itemSize</code> to x and
-		sets the value of the array at <code>index * itemSize + 1</code> to y
+		[page:BufferAttribute.array array] to the TypedArray passed in here.<br /><br />
+
+		After setting the array, [page:BufferAttribute.needsUpdate needsUpdate] should be set to true.
 		</div>
 
+		<h3>[method:BufferAttribute setDynamic] ( [page:Boolean value] ) </h3>
+		<div>Set [page:BufferAttribute.dynamic dynamic] to value.</div>
+
+		<h3>[method:null setX]( index, x ) </h3>
+		<div>Sets the x component of the vector at the given index.</div>
+
+		<h3>[method:null setY]( index, y ) </h3>
+		<div>Sets the y component of the vector at the given index.</div>
+
+		<h3>[method:null setZ]( index, z ) </h3>
+		<div>Sets the z component of the vector at the given index.</div>
+
+		<h3>[method:null setW]( index, w ) </h3>
+		<div>Sets the w component of the vector at the given index.</div>
+
+		<h3>[method:null setXY]( index, x, y ) </h3>
+		<div>Sets the x and y components of the vector at the given index.</div>
+
 		<h3>[method:null setXYZ]( index, x, y, z ) </h3>
-		<div>
-		Sets the value of the array at <code>index * itemSize</code> to x,
-		the value of the array at <code>index * itemSize + 1</code> to y, and
-		the value of the array at <code>index * itemSize + 2</code> to z.
-		</div>
+		<div>Sets the x, y and z components of the vector at the given index.</div>
 
 		<h3>[method:null setXYZW]( index, x, y, z, w ) </h3>
-		<div>
-		Sets the value of the array at <code>index * itemSize</code> to x,
-		the value of the array at <code>index * itemSize + 1</code> to y,
-		the value of the array at <code>index * itemSize + 2</code> to z, and
-		the value of the array at <code>index * itemSize + 3</code> to w.
-		</div>
+		<div>Sets the x, y, z and w components of the vector at the given index.</div>
 
-		<h3>[method:null onUpload]( [page:Function callback] ) </h3>
-		<div>
-		Sets the value of the onUploadCallback property.
-		</div>
-		<div>Example: [example:webgl_buffergeometry used to free memory after the buffer has been transfered to GPU].</div>
 
-		<h3>[method:BufferAttribute clone]() </h3>
-		<div>
-		Copies this attribute.
-		</div>
 
 		<h2>Source</h2>
 

docs/api/core/BufferGeometry.html

@@ -14,15 +14,15 @@
 		<p>
 		This class is an efficient alternative to [page:Geometry], because it stores all data, including
 		vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers; this
-		reduces the cost of passing all this data to the GPU.
+		reduces the cost of passing all this data to the GPU.<br />
 		This also makes BufferGeometry harder to work with than [page:Geometry]; rather than accessing
 		position data as [page:Vector3] objects, color data as [page:Color] objects, and so on, you have to
-		access the raw data from the appropriate [page:BufferAttribute attribute] buffer. This makes
+		access the raw data from the appropriate [page:BufferAttribute attribute buffer]. This makes
 		BufferGeometry best-suited for static objects where you don't need to manipulate the geometry much
 		after instantiating it.
 		</p>
 
-		<h3>Example</h3>
+		<h2>Example</h2>
 		<code>
 		var geometry = new THREE.BufferGeometry();
 		// create a simple square shape. We duplicate the top left and bottom right
@@ -42,16 +42,23 @@
 		var material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
 		var mesh = new THREE.Mesh( geometry, material );
 		</code>
-		<p>More examples: [example:webgl_buffergeometry Complex mesh with non-indexed faces], [example:webgl_buffergeometry_uint Complex mesh with indexed faces], [example:webgl_buffergeometry_lines Lines], [example:webgl_buffergeometry_lines_indexed Indexed Lines], [example:webgl_buffergeometry_custom_attributes_particles Particles], and [example:webgl_buffergeometry_rawshader Raw Shaders].</p>
+		<div>
+			[example:webgl_buffergeometry Complex mesh with non-indexed faces]<br />
+			[example:webgl_buffergeometry_uint Complex mesh with indexed faces]<br />
+			[example:webgl_buffergeometry_lines Lines]<br />
+			[example:webgl_buffergeometry_lines_indexed Indexed Lines]<br />
+			[example:webgl_buffergeometry_custom_attributes_particles Particles]<br />
+			[example:webgl_buffergeometry_rawshader Raw Shaders]
+		</div>
 
 
-		<h3>Accessing attributes</h3>
+		<h2>Accessing Attributes</h2>
 		<p>
 		WebGL stores data associated with individual vertices of a geometry in <em>attributes</em>.
 		Examples include the position of the vertex, the normal vector for the vertex, the vertex color,
 		and so on. When using [page:Geometry], the [page:WebGLRenderer renderer] takes care of wrapping
 		up this information into typed array buffers and sending this data to the shader. With
-		BufferGeometry, all of this data is stored in buffers associated with an individual attributes.
+		BufferGeometry, all of this data is stored in buffers associated with individual attributes.
 		This means that to get the position data associated with a vertex (for instance), you must call
 		[page:.getAttribute] to access the 'position' [page:BufferAttribute attribute], then access the individual
 		x, y, and z coordinates of the position.
@@ -59,27 +66,30 @@
 		<p>
 		The following attributes are set by various members of this class:
 		</p>
-		<h4>[page:BufferAttribute position] (itemSize: 3)</h4>
+		<h3>[page:BufferAttribute position] (itemSize: 3)</h3>
 		<div>
 		Stores the x, y, and z coordinates of each vertex in this geometry. Set by [page:.fromGeometry]().
 		</div>
 
-		<h4>[page:BufferAttribute normal] (itemSize: 3)</h4>
+		<h3>[page:BufferAttribute normal] (itemSize: 3)</h3>
 		<div>
 		Stores the x, y, and z components of the face or vertex normal vector of each vertex in this geometry.
 		Set by [page:.fromGeometry]().
 		</div>
 
-		<h4>[page:BufferAttribute color] (itemSize: 3)</h4>
+		<h3>[page:BufferAttribute color] (itemSize: 3)</h3>
 		<div>
 		Stores the red, green, and blue channels of vertex color of each vertex in this geometry.
 		Set by [page:.fromGeometry]().
 		</div>
 
-		<h4>[page:BufferAttribute index] (itemSize: 1)</h4>
-		Allows for vertices to be re-used across multiple triangles; this is called using "indexed triangles," and works much the same as it does in [page:Geometry]: each triangle is associated with the index of three vertices. This attribute therefore stores the index of each vertex for each triangular face.
+		<h3>[page:BufferAttribute index] (itemSize: 1)</h3>
+		Allows for vertices to be re-used across multiple triangles; this is called using "indexed triangles" and
+		works much the same as it does in [page:Geometry]: each triangle is associated with the indices of three vertices.
+		This attribute therefore stores the index of each vertex for each triangular face.
 
-		If this attribute is not set, the [page:WebGLRenderer renderer] assumes that each three contiguous positions represent a single triangle.
+		If this attribute is not set, the [page:WebGLRenderer renderer] assumes that each three contiguous
+		positions represent a single triangle.
 		</div>
 		<p>
 		In addition to the the built-in attributes, you can set your own custom attributes using the addAttribute method. With [page:Geometry], these attributes are set and stored on the [page:Material]. In BufferGeometry, the attributes are stored with the geometry itself. Note that you still need to set the attributes information on the material as well, but the value of each attribute is stored in the BufferGeometry.
@@ -97,141 +107,141 @@
 
 		<h2>Properties</h2>
 
-		<h3>[property:Integer id]</h3>
-		<div>
-		Unique number for this buffergeometry instance.
-		</div>
-
 		<h3>[property:Hashmap attributes]</h3>
 		<div>
 		This hashmap has as id the name of the attribute to be set and as value the [page:BufferAttribute buffer] to set it to.
 		Rather than accessing this property directly, use addAttribute and getAttribute to access attributes of this geometry.
 		</div>
 
-		<!--
- 		<h3>[property:Boolean dynamic]</h3>
+		<h3>[property:Box3 boundingBox]</h3>
 		<div>
-		When set, it holds certain buffers in memory to have faster updates for this object. When unset, it deletes those buffers and   saves memory.
-		</div> -->
+			Bounding box for the bufferGeometry, which can be calculated with
+			[page:.computeBoundingBox](). Default is *null*.
+		</div>
 
-		<h3>[property:Array drawcalls] (previously [property:Array offsets])</h3>
+		<h3>[property:Sphere boundingSphere]</h3>
 		<div>
-		For geometries that use indexed triangles, this Array can be used to split the object into multiple WebGL draw calls. Each draw call will draw some subset of the vertices in this geometry using the configured [page:Material shader]. This may be necessary if, for instance, you have more than 65535 vertices in your object.
-		Each element is an object of the form:
-		<code>{ start: Integer, count: Integer, index: Integer }</code>
-		where start specifies the index of the first vertex in this draw call, count specifies how many vertices are included, and index specifies an optional offset.
-
-		Use addDrawCall to add draw calls, rather than modifying this array directly.
+			Bounding sphere for the bufferGeometry, which can be calculated with
+			[page:.computeBoundingSphere](). Default is *null*.
 		</div>
 
-		<h3>[property:Box3 boundingBox]</h3>
+		<h3>[property:Object drawRange]</h3>
 		<div>
-		Bounding box.
-		<code>{ min: new THREE.Vector3(), max: new THREE.Vector3() }</code>
+			Used to determine what part of the geometry should be rendered. This should not
+			be set directly, instead use [page:.setDrawRange].<br />
+			Default is
+			<code>
+				{ start: 0, count: Infinity }
+			</code>
 		</div>
 
-		<h3>[property:Sphere boundingSphere]</h3>
+		<h3>[property:Array groups]</h3>
 		<div>
-		Bounding sphere.
-		<code>{ radius: float }</code>
+			Split the geometry into groups, each of which will be rendered in a separate WebGL draw call.
+			This allows a [page:MultiMaterial] to be used with the bufferGeometry.<br /><br />
+
+			Each group is an object of the form:
+			<code>{ start: Integer, count: Integer, materialIndex: Integer }</code>
+			where start specifies the index of the first vertex in this draw call, count specifies
+			how many vertices are included, and materialIndex specifies the [page:MultiMaterial] index to use.<br /><br />
+
+			Use [page:.addGroup] to add groups, rather than modifying this array directly.
 		</div>
 
-		<h2>Methods</h2>
 
-		<h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>
+		<!-- Note: groups used to be called drawCalls
 
-		<h3>[property:null addAttribute]( [page:String name], [page:BufferAttribute attribute] )</h3>
+		<h3>[property:Array drawcalls]</h3>
 		<div>
-		Adds an attribute to this geometry. Use this rather than the attributes property,
-		because an internal array of attributes is maintained to speed up iterating over
-		attributes.
-		</div>
+		For geometries that use indexed triangles, this Array can be used to split the object
+		into multiple WebGL draw calls. Each draw call will draw some subset of the vertices
+		in this geometry using the configured [page:Material shader]. This may be necessary if,
+		for instance, you have more than 65535 vertices in your object.
+		</div> -->
 
-		<h3>[method:null addDrawCall]( [page:Integer start], [page:Integer count], [page:Integer indexOffset] )</h3>
-		<div>
-		Adds a draw call to this geometry; see the [page:BufferGeometry.drawcalls drawcalls] property for details.
-		</div>
 
-		<h3>[method:null clearDrawCalls]( )</h3>
-		<div>
-		Clears all draw calls.
-		</div>
+		<h3>[property:Integer id]</h3>
+		<div>Unique number for this bufferGeometry instance.</div>
 
-		<h3>[method:null applyMatrix]( [page:Matrix4 matrix] )</h3>
+		<h3>[property:BufferAttribute index]</h3>
 		<div>
-		Bakes matrix transform directly into vertex coordinates.
+			See "Accessing Attributes" section above for a description of this property.
+			Default is *null*.
 		</div>
 
-		<h3>[method:null center] ()</h3>
+		<h3>[property:Boolean isBufferGeometry]</h3>
 		<div>
-		Center the geometry based on the bounding box.
-		</div>
+			Used to check whether this or derived classes are BufferGeometries. Default is *true*.<br /><br />
 
-		<h3>[method:BufferGeometry rotateX] ( [page:Float radians] )</h3>
-		<div>
-		Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
+			You should not change this, as it used internally for optimisation.
 		</div>
 
-		<h3>[method:BufferGeometry rotateY] ( [page:Float radians] )</h3>
-		<div>
-		Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
-		</div>
+		<h3>[property:Integer MaxIndex]</h3>
+		<div>Maximum number of vertices allowed, set to *65535*.</div>
 
-		<h3>[method:BufferGeometry rotateZ] ( [page:Float radians] )</h3>
+		<h3>[property:Object morphAttributes]</h3>
 		<div>
-		Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
+			Hashmap of [page:BufferAttribute]s holding details of the geometry's [page:Geometry.morphTargets morphTargets].
 		</div>
 
-		<h3>[method:BufferGeometry translate] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
+		<h3>[property:String name]</h3>
 		<div>
-		Translate the geometry. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.position] for typical real-time mesh translation.
+		Optional name for this bufferGeometry instance. Default is an empty string.
 		</div>
 
-		<h3>[method:BufferGeometry scale] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
+		<h3>[property:String uuid]</h3>
 		<div>
-		Scale the geometry data. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.scale] for typical real-time mesh scaling.
+		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
+		This gets automatically assigned and shouldn't be edited.
 		</div>
 
-		<h3>[method:BufferGeometry lookAt] ( [page:Vector3 vector] )</h3>
-		<div>
-		vector - A world vector to look at.<br />
-		</div>
-		<div>
-		Rotates the geometry to face point in space. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.lookAt] for typical real-time mesh usage.
-		</div>
+		<h2>Methods</h2>
 
-		<h3>[method:BufferGeometry setFromObject] ( [page:Object3D object] )</h3>
+		<h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>
+
+		<h3>[property:null addAttribute]( [page:String name], [page:BufferAttribute attribute] )</h3>
 		<div>
-		Sets the attributes for this BufferGeometry from an [page:Object3D].
+		Adds an attribute to this geometry. Use this rather than the attributes property,
+		because an internal hashmap of [page:.attributes] is maintained to speed up iterating over
+		attributes.
 		</div>
 
-		<h3>[method:null computeVertexNormals]()</h3>
+		<h3>[method:null addGroup]( [page:Integer start], [page:Integer count], [page:Integer materialIndex] )</h3>
 		<div>
-		Computes vertex normals by averaging face normals.<br />
+			Adds a group to this geometry; see the [page:BufferGeometry.groups groups]
+			property for details.
 		</div>
 
+
+		<h3>[method:null applyMatrix]( [page:Matrix4 matrix] )</h3>
+		<div>Bakes matrix transform directly into vertex coordinates.</div>
+
+		<h3>[method:null center] ()</h3>
+		<div>Center the geometry based on the bounding box.</div>
+
+		<h3>[method:BufferGeometry clone]()</h3>
+		<div>Creates a clone of this BufferGeometry.</div>
+
+		<h3>[method:BufferGeometry copy]( [page:BufferGeometry bufferGeometry] )</h3>
+		<div>Copies another BufferGeometry to this BufferGeometry.</div>
+
+		<h3>[method:null clearGroups]( )</h3>
+		<div>Clears all groups.</div>
+
 		<h3>[method:null computeBoundingBox]()</h3>
 		<div>
-		Computes bounding box of the geometry, updating [page:Geometry Geometry.boundingBox] attribute.<br />
+		Computes bounding box of the geometry, updating [page:.boundingBox] attribute.<br />
 		Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
 		</div>
 
 		<h3>[method:null computeBoundingSphere]()</h3>
 		<div>
-		Computes bounding sphere of the geometry, updating [page:Geometry Geometry.boundingSphere] attribute.<br />
+		Computes bounding sphere of the geometry, updating [page:.boundingSphere] attribute.<br />
 		Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
 		</div>
 
-		<h3>[method:null merge]( [page:BufferGeometry bufferGeometry], [page:Integer offset] )</h3>
-		<div>
-		Merge in another BufferGeometry with an optional offset of where to start merging in.
-		</div>
+		<h3>[method:null computeVertexNormals]()</h3>
+		<div>Computes vertex normals by averaging face normals.</div>
 
 		<h3>[method:null dispose]()</h3>
 		<div>
@@ -239,42 +249,105 @@
 		You need to call this when you want the bufferGeometry removed while the application is running.
 		</div>
 
-		<h3>[method:BufferGeometry fromGeometry]( [page:Geometry] )</h3>
+		<h3>[method:BufferGeometry fromDirectGeometry]( [page:Geometry] )</h3>
 		<div>
-		Populates this BufferGeometry with data from a [page:Geometry] object.
+			Populates this BufferGeometry with data from a [page:DirectGeometry] object.<br /><br />
+
+			Note: [page:DirectGeometry] is mainly used as an intermediary object for converting between [page:Geometry]
+			and BufferGeometry.
 		</div>
 
+		<h3>[method:BufferGeometry fromGeometry]( [page:Geometry] )</h3>
+		<div>Populates this BufferGeometry with data from a [page:Geometry] object.</div>
+
 		<h3>[method:BufferAttribute getAttribute]( [page:String name] )</h3>
-		<div>
-		Returns the [page:BufferAttribute attribute] with the specified name.
-		</div>
+		<div>Returns the [page:BufferAttribute attribute] with the specified name.</div>
 
-		<h3>[method:BufferAttribute removeAttribute]( [page:String name] )</h3>
+		<h3>[method:BufferAttribute getIndex] ()</h3>
+		<div>Return the [page:.index] buffer.</div>
+
+		<h3>[method:BufferGeometry lookAt] ( [page:Vector3 vector] )</h3>
 		<div>
-		Removes the [page:BufferAttribute attribute] with the specified name.
+		vector - A world vector to look at.<br /><br />
+
+		Rotates the geometry to face a point in space. This is typically done as a one time operation, and not during a loop.
+		Use [page:Object3D.lookAt] for typical real-time mesh usage.
 		</div>
 
+		<h3>[method:null merge]( [page:BufferGeometry bufferGeometry], [page:Integer offset] )</h3>
+		<div>Merge in another BufferGeometry with an optional offset of where to start merging in.</div>
+
 		<h3>[method:null normalizeNormals]()</h3>
 		<div>
 		Every normal vector in a geometry will have a magnitude of 1.
 		This will correct lighting on the geometry surfaces.
 		</div>
 
-		<h3>[method:Object toJSON]()</h3>
+		<h3>[method:BufferAttribute removeAttribute]( [page:String name] )</h3>
+		<div>Removes the [page:BufferAttribute attribute] with the specified name.</div>
+
+		<h3>[method:BufferGeometry rotateX] ( [page:Float radians] )</h3>
 		<div>
-		Returns a raw object representation of the BufferGeometry.
+		Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop.
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
 		</div>
 
-		<h3>[method:BufferGeometry clone]()</h3>
+		<h3>[method:BufferGeometry rotateY] ( [page:Float radians] )</h3>
 		<div>
-		Creates a clone of this BufferGeometry.
+		Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop.
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
 		</div>
 
-		<h3>[method:BufferGeometry copy]( [page:BufferGeometry bufferGeometry] )</h3>
+		<h3>[method:BufferGeometry rotateZ] ( [page:Float radians] )</h3>
+		<div>
+		Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop.
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
+		</div>
+
+		<h3>[method:BufferGeometry scale] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
 		<div>
-		Copies another BufferGeometry to this BufferGeometry.
+		Scale the geometry data. This is typically done as a one time operation, and not during a loop.
+		Use [page:Object3D.scale] for typical real-time mesh scaling.
 		</div>
 
+		<h3>[method:null setIndex] ( [page:BufferAttribute index] )</h3>
+		<div>Set the [page:.index] buffer.</div>
+
+		<h3>[method:null setDrawRange] ( [page:Integer start], [page:Integer count] )</h3>
+		<div>Set the [page:.drawRange] buffer. See that property for details.</div>
+
+		<h3>[method:BufferGeometry setFromObject] ( [page:Object3D object] )</h3>
+		<div>Sets the attributes for this BufferGeometry from an [page:Object3D].</div>
+
+		<h3>[method:Object toJSON]()</h3>
+		<div>Returns a JSON object representation of the BufferGeometry.</div>
+
+		<h3>[method:BufferGeometry toNonIndexed]()</h3>
+		<div>Return a non-index version of an indexed BufferGeometry.</div>
+
+		<h3>[method:BufferGeometry translate] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
+		<div>
+		Translate the geometry. This is typically done as a one time operation, and not during a loop.
+    Use [page:Object3D.position] for typical real-time mesh translation.
+		</div>
+
+		<h3>[method:BufferGeometry updateFromObject] ( [page:Object3D object] )</h3>
+		<div>Updates the attributes for this BufferGeometry from an [page:Object3D].</div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 		<h2>Source</h2>

docs/api/core/DirectGeometry.html

@@ -10,7 +10,9 @@
 	<body>
 		<h1>[name]</h1>
 
-		<div class="desc">This class is mainly used internally to convert from [page:Geometry] to [page:BufferGeometry].</div>
+		<div class="desc">
+			This class is used internally to convert from [page:Geometry] to [page:BufferGeometry].
+		</div>
 
 
 
@@ -18,117 +20,79 @@
 
 
 		<h3>[name]()</h3>
-		<div>
-		This creates a new [name].
-		</div>
+		<div>This creates a new [name].</div>
 
 
 		<h2>Properties</h2>
 
 		<h3>[property:Integer id]</h3>
-		<div>
-		Unique number for this [name] instance.
-		</div>
+		<div>Unique number for this [name] instance.</div>
 
 		<h3>[property:String name]</h3>
-		<div>
-		Optional name. Default is the empty string.
-		</div>
+		<div>Optional name. Default is the empty string.</div>
 
 		<h3>[property:Array type]</h3>
-		<div>
-		String 'DirectGeometry'.
-		</div>
+		<div>String 'DirectGeometry'.</div>
 
 		<h3>[property:Array indices]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array vertices]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array normals]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array colors]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array uvs]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array uvs2]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array groups]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array morphTargets]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array skinWeights]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
 		<h3>[property:Array skinIndices]</h3>
-		<div>
-			Default is empty array.
-		</div>
+		<div>Initialiased as an empty array, this is populated by [page:.fromGeometry]().</div>
 
-		<h3>[property:Box boundingBox]</h3>
+		<h3>[property:Box3 boundingBox]</h3>
 		<div>
-			Default is null.
+			Bounding box for the bufferGeometry, which can be calculated with
+			[page:.computeBoundingBox](). Default is *null*.
 		</div>
 
-		<h3>[property:Box boundingSphere]</h3>
+		<h3>[property:Sphere boundingSphere]</h3>
 		<div>
-			Default is null.
+			Bounding sphere for the bufferGeometry, which can be calculated with
+			[page:.computeBoundingSphere](). Default is *null*.
 		</div>
 
 		<h3>[property:Boolean verticesNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 		<h3>[property:Boolean normalsNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 		<h3>[property:Boolean verticesNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 		<h3>[property:Boolean colorsNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 		<h3>[property:Boolean uvsNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 		<h3>[property:Boolean groupsNeedUpdate]</h3>
-		<div>
-			Default is false.
-		</div>
+		<div>Default is false.</div>
 
 
 		<h2>Methods</h2>
@@ -145,17 +109,20 @@
 		 See [page:Geometry.computeBoundingSphere].
 		</div>
 
-		<h3>[property:null computeGroups]( page:Geometry geometry] )</h3>
+		<h3>[property:null computeGroups]( [page:Geometry geometry] )</h3>
 		<div>
+			Compute the parts of the geometry that have different materialIndex.
+			See [page:BufferGeometry.groups].
 		</div>
 
-		<h3>[property:null fromGeometry]( page:Geometry geometry] )</h3>
+		<h3>[method:null dispose]()</h3>
 		<div>
+		Disposes the object from memory. <br />
+		You need to call this when you want the directGeometry removed while the application is running.
 		</div>
 
-		<h3>[property:null dispose]( )</h3>
-		<div>
-		</div>
+		<h3>[property:null fromGeometry]( [page:Geometry geometry] )</h3>
+		<div>Pass in a [page:Geometry] instance for conversion.</div>
 
 
 		<h2>Source</h2>

docs/api/core/EventDispatcher.html

@@ -10,11 +10,44 @@
 	<body>
 		<h1>[name]</h1>
 
-		<div class="desc">JavaScript events for custom objects.<br />
-		<a href="https://github.com/mrdoob/eventdispatcher.js">https://github.com/mrdoob/eventdispatcher.js</a></div>
+		<div class="desc">
+			JavaScript events for custom objects.<br />
+			[link:https://github.com/mrdoob/eventdispatcher.js Eventdispatcher on GitHub]
+		</div>
 
-		<h2>Constructor</h2>
+		<h2>Example</h2>
+
+		<code>
+// Adding events to a custom object
+
+var Car = function () {
+
+    this.start = function () {
+
+        this.dispatchEvent( { type: 'start', message: 'vroom vroom!' } );
+
+    };
+
+};
+
+// Mixin the EventDispatcher.prototype with the custom object prototype
 
+Object.assign( Car.prototype, EventDispatcher.prototype );
+
+// Using events with the custom object
+
+var car = new Car();
+
+car.addEventListener( 'start', function ( event ) {
+
+    alert( event.message );
+
+} );
+
+car.start();
+		</code>
+
+		<h2>Constructor</h2>
 
 		<h3>[name]()</h3>
 		<div>

docs/api/core/Face3.html

@@ -11,15 +11,44 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		Triangle face.
+		Triangular face used in [page:Geometry]. These are created automatically for all
+		standard geometry types, however if you are building a custom geometry you will have to
+		create them manually.
 		</div>
 
 
-		<h2>Example</h2>
+		<h2>Examples</h2>
 
-		<code>var normal = new THREE.Vector3( 0, 1, 0 );
-		var color = new THREE.Color( 0xffaa00 );
-		var face = new THREE.Face3( 0, 1, 2, normal, color, 0 );</code>
+		<div>[example:misc_ubiquity_test ubiquity / test ]</div>
+		<div>[example:svg_sandbox svg / sandbox ]</div>
+		<div>[example:webgl_exporter_obj WebGL / exporter / obj ]</div>
+		<div>[example:webgl_shaders_vector WebGL / shaders / vector ]</div>
+
+
+		<code>
+var material = new THREE.MeshStandardMaterial( { color : 0x00cc00 } );
+
+//create a triangular geometry
+var geometry = new THREE.Geometry();
+geometry.vertices.push( new THREE.Vector3( -50, -50, 0 ) );
+geometry.vertices.push( new THREE.Vector3(  50, -50, 0 ) );
+geometry.vertices.push( new THREE.Vector3(  50,  50, 0 ) );
+
+//create a new face using vertices 0, 1, 2
+var normal = new THREE.Vector3( 0, 1, 0 ); //optional
+var color = new THREE.Color( 0xffaa00 ); //optional
+var materialIndex = 0; //optional
+var face = new THREE.Face3( 0, 1, 2, normal, color, materialIndex );
+
+//add the face to the geometry's faces array
+geometry.faces.push( face );
+
+//the face normals and vertex normals can be calculated automatically if not supplied above
+geometry.computeFaceNormals();
+geometry.computeVertexNormals();
+
+scene.add( new THREE.Mesh( geometry, material ) );
+	</code>
 
 
 		<h2>Constructor</h2>
@@ -28,10 +57,18 @@
 		<div>
 		a — Vertex A index.<br />
 		b — Vertex B index.<br />
-		c — Vertex C index.<br />
-		normal — Face normal or array of vertex normals.<br />
-		color — Face color or array of vertex colors.<br />
-		materialIndex — Material index.
+		c — Vertex C index.<br /><br />
+
+		normal — (optional) Face normal ([page:Vector3 Vector3]) or array of vertex normals.
+		If a single vector is passed in, this sets [page:.normal], otherwise if an array of three
+		vectors is passed in this sets [page:.vertexNormals]<br /><br />
+
+		color — (optional) Face [page:Color color] or array of vertex [page:Color colors].
+		If a single vector is passed in, this sets [page:.color], otherwise if an array of three
+		vectors is passed in this sets [page:.vertexColors]<br /><br />
+
+		materialIndex — (optional) which index of a [page:MultiMaterial] to associate
+		with the face.
 		</div>
 
 		<h2>Properties</h2>
@@ -53,36 +90,41 @@
 
 		<h3>[property:Vector3 normal]</h3>
 		<div>
-		Face normal.
+		Face normal - vector showing the direction of the Face3. If calculated automatically
+		(using [page:Geometry.computeFaceNormals]), this is the normalized cross product of two edges of the
+		triangle. Default is *(0, 0, 0)*.
 		</div>
 
 		<h3>[property:Color color]</h3>
 		<div>
-		Face color.
+		Face color - for this to be used a material's [page:Material.vertexColors vertexColors] property
+		must be set to [page:Materials THREE.FaceColors].
 		</div>
 
 		<h3>[property:Array vertexNormals]</h3>
 		<div>
-		Array of 3 vertex normals.
+		Array of 3 [page:Vector3 vertex normals].
 		</div>
 
 		<h3>[property:Array vertexColors]</h3>
 		<div>
-		Array of 3 vertex colors.
+		Array of 3 vertex colors - for these to be used a material's [page:Material.vertexColors vertexColors] property
+		must be set to [page:Materials THREE.VertexColors].
 		</div>
 
 
 		<h3>[property:Integer materialIndex]</h3>
 		<div>
-		Material index (points to [page:MultiMaterial MultiMaterial.materials]).
+		Material index (points to [page:MultiMaterial MultiMaterial.materials]). Default is *0*.
 		</div>
 
 		<h2>Methods</h2>
 
 		<h3>[method:Face3 clone]()</h3>
-		<div>
-		Creates a new clone of the Face3 object.
-		</div>
+		<div>Creates a new clone of the Face3 object.</div>
+
+		<h3>[method:Face3 copy]( [page:Face3 face3] )</h3>
+		<div>Copy the paramaters of another Face3 into this.</div>
 
 
 		<h2>Source</h2>

docs/api/core/Geometry.html

@@ -11,13 +11,28 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		Base class for geometries.<br />
-		A geometry holds all data necessary to describe a 3D model.
+		Base class for all geometries (but not for [page:BufferGeometry BufferGeometries]).<br />
+		This can also be used directly for building custom geometries.<br /><br />
+
+		Geometries are easier to work with than [page:BufferGeometry BufferGeometries] as they store
+		attributes such as vertices, faces, colors and so on directly (rather than in [page:BufferAttribute buffers]),
+		however they are generally slower.
 		</div>
 
 
 		<h2>Example</h2>
 
+		<div>[example:webgl_geometry_minecraft WebGL / geometry / minecraft ]</div>
+		<div>[example:webgl_geometry_minecraft_ao WebGL / geometry / minecraft / ao ]</div>
+		<div>[example:webgl_geometry_nurbs WebGL / geometry / nurbs ]</div>
+		<div>[example:webgl_geometry_spline_editor WebGL / geometry / spline / editor ]</div>
+		<div>[example:webgl_interactive_cubes_gpu WebGL / interactive / cubes / gpu ]</div>
+		<div>[example:webgl_interactive_lines WebGL / interactive / lines ]</div>
+		<div>[example:webgl_interactive_raycasting_points WebGL / interactive / raycasting / points ]</div>
+		<div>[example:webgl_interactive_voxelpainter WebGL / interactive / voxelpainter ]</div>
+		<div>[example:webgl_morphnormals WebGL / morphNormals ]</div>
+
+
 		<code>var geometry = new THREE.Geometry();
 
 		geometry.vertices.push(
@@ -42,48 +57,63 @@
 
 		<h2>Properties</h2>
 
-		<h3>[property:Integer id]</h3>
+		<h3>[property:Box3 boundingBox]</h3>
 		<div>
-		Unique number for this geometry instance.
+			Bounding box for the Geometry, which can be calculated with
+			[page:.computeBoundingBox](). Default is *null*.
 		</div>
 
-		<h3>[property:String name]</h3>
+		<h3>[property:Sphere boundingSphere]</h3>
 		<div>
-		Name for this geometry. Default is an empty string.
-		</div>
-
-		<h3>[property:Array vertices]</h3>
-		<div>
-		Array of [page:Vector3 vertices].<br />
-		The array of vertices holds every position of points in the model.<br />
-		To signal an update in this array, [page:Geometry Geometry.verticesNeedUpdate] needs to be set to true.
+			Bounding sphere for the Geometry, which can be calculated with
+			[page:.computeBoundingSphere](). Default is *null*.
 		</div>
 
 		<h3>[property:Array colors]</h3>
 		<div>
-		Array of vertex [page:Color colors], matching number and order of vertices.<br />
-		Used in [page:Points] and [page:Line].<br />
-		[page:Mesh Meshes] use per-face-use-of-vertex colors embedded directly in faces.<br />
+		Array of vertex [page:Color colors], matching number and order of vertices.<br /><br />
+
+		This is used by [page:Points] and [page:Line] and any classes derived from those such as [page:LineSegments] and various helpers.
+		[page:Mesh Meshes] use [page:Face3.vertexColors] instead of this.<br /><br />
+
 		To signal an update in this array, [page:Geometry Geometry.colorsNeedUpdate] needs to be set to true.
 		</div>
 
 		<h3>[property:Array faces]</h3>
 		<div>
-		Array of [page:Face3 triangles].<br />
-		The array of faces describe how each vertex in the model is connected with each other.<br />
+		Array of [page:Face3 faces].<br />
+		The array of faces describe how each vertex in the model is connected to form faces.
+		Additionally it holds information about face and vertex normals and colors.<br /><br />
 		To signal an update in this array, [page:Geometry Geometry.elementsNeedUpdate] needs to be set to true.
 		</div>
 
 		<h3>[property:Array faceVertexUvs]</h3>
 		<div>
-		Array of face [page:UV] layers.<br />
-		Each UV layer is an array of [page:UV]s matching the order and number of vertices in faces.<br />
+		Array of face [link:https://en.wikipedia.org/wiki/UV_mapping UV] layers, used for mapping textures onto the geometry.<br />
+		Each UV layer is an array of [page:UV]s matching the order and number of vertices in faces.<br /><br />
 		To signal an update in this array, [page:Geometry Geometry.uvsNeedUpdate] needs to be set to true.
 		</div>
 
+		<h3>[property:Integer id]</h3>
+		<div>Unique number for this geometry instance.</div>
+
+		<h3>[property:Boolean isGeometry]</h3>
+		<div>
+			Used to check whether this or derived classes are Geometries. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
+
+		<h3>[property:array lineDistances]</h3>
+		<div>
+		An array containing distances between vertices for Line geometries.
+		This is required for [page:LineSegments] / [page:LineDashedMaterial] to render correctly.
+		Line distances can be generated automatically with [page:.computeLineDistances].
+		</div>
+
 		<h3>[property:Array morphTargets]</h3>
 		<div>
-		Array of morph targets. Each morph target is a Javascript object:
+		Array of [link:https://en.wikipedia.org/wiki/Morph_target_animation morph targets]. Each morph target is a Javascript object:
 		<code>{ name: "targetName", vertices: [ new THREE.Vector3(), ... ] }</code>
 		Morph vertices match number and order of primary vertices.
 		</div>
@@ -92,8 +122,13 @@
 		<div>
 		Array of morph normals. Morph normals have similar structure as morph targets, each normal set is a Javascript object:
 		<code>morphNormal = { name: "NormalName", normals: [ new THREE.Vector3(), ... ] }</code>
+
+		See the [example:webgl_morphnormals WebGL / morphNormals] example.
 		</div>
 
+		<h3>[property:String name]</h3>
+		<div>Optional name for this geometry. Default is an empty string.</div>
+
 		<h3>[property:Array skinWeights]</h3>
 		<div>
 		When working with a [page:SkinnedMesh], each vertex can have up to 4 [page:Bone bones] affecting it.
@@ -138,151 +173,118 @@
 		</code>
 		</div>
 
-		<h3>[property:Object boundingBox]</h3>
+		<h3>[property:String uuid]</h3>
 		<div>
-		Bounding box.
-		<code>{ min: new THREE.Vector3(), max: new THREE.Vector3() }</code>
+		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
+		This gets automatically assigned and shouldn't be edited.
 		</div>
 
-		<h3>[property:Object boundingSphere]</h3>
+		<h3>[property:Array vertices]</h3>
 		<div>
-		Bounding sphere.
-		<code>{ radius: float }</code>
+		Array of [page:Vector3 vertices].<br />
+		The array of vertices holds the position of every vertex in the model.<br />
+		To signal an update in this array, [page:.verticesNeedUpdate] needs to be set to true.
 		</div>
 
 		<h3>[property:Boolean verticesNeedUpdate]</h3>
-		<div>
-		Set to *true* if the vertices array has been updated.
-		</div>
+		<div>Set to *true* if the vertices array has been updated.</div>
 
 		<h3>[property:Boolean elementsNeedUpdate]</h3>
-		<div>
-		Set to *true* if the faces array has been updated.
-		</div>
+		<div>Set to *true* if the faces array has been updated.</div>
 
 		<h3>[property:Boolean uvsNeedUpdate]</h3>
-		<div>
-		Set to *true* if the uvs array has been updated.
-		</div>
+		<div>Set to *true* if the uvs array has been updated.	</div>
 
 		<h3>[property:Boolean normalsNeedUpdate]</h3>
-		<div>
-		Set to *true* if the normals array has been updated.
-		</div>
+		<div>Set to *true* if the normals array has been updated.</div>
 
 		<h3>[property:Boolean colorsNeedUpdate]</h3>
-		<div>
-		Set to *true* if the colors array or a face3 color has been updated.
-		</div>
+		<div>Set to *true* if the colors array or a face3 color has been updated.</div>
 
 		<h3>[property:Boolean groupsNeedUpdate]</h3>
-		<div>
-		Set to *true* if a face3 materialIndex has been updated.
-		</div>
+		<div>Set to *true* if a face3 materialIndex has been updated.</div>
 
 		<h3>[property:Boolean lineDistancesNeedUpdate]</h3>
-		<div>
-		Set to *true* if the linedistances array has been updated.
-		</div>
+		<div>Set to *true* if the linedistances array has been updated.</div>
 
-		<h3>[property:array lineDistances]</h3>
-		<div>
-		An array containing distances between vertices for Line geometries.
-		This is required for LinePieces/LineDashedMaterial to render correctly.
-		Line distances can also be generated with computeLineDistances.
-		</div>
 
 		<h2>Methods</h2>
 
 		<h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>
 
 		<h3>[method:null applyMatrix]( [page:Matrix4 matrix] )</h3>
-		<div>
-		Bakes matrix transform directly into vertex coordinates.
-		</div>
+		<div>Bakes matrix transform directly into vertex coordinates.</div>
 
 		<h3>[method:null center] ()</h3>
-		<div>
-		Center the geometry based on the bounding box.
-		</div>
-
-		<h3>[method:Geometry rotateX] ( [page:Float radians] )</h3>
-		<div>
-		Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
-		</div>
+		<div>Center the geometry based on the bounding box.</div>
 
-		<h3>[method:Geometry rotateY] ( [page:Float radians] )</h3>
+		<h3>[method:Geometry clone]()</h3>
 		<div>
-		Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
-		</div>
+		Creates a new clone of the Geometry.<br /><br />
 
-		<h3>[method:Geometry rotateZ] ( [page:Float radians] )</h3>
-		<div>
-		Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.rotation] for typical real-time mesh rotation.
+		This method copies only vertices, faces and uvs. It does not copy any other properties of the geometry.
 		</div>
 
-		<h3>[method:Geometry translate] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
-		<div>
-		Translate the geometry. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.position] for typical real-time mesh translation.
-		</div>
+		<h3>[method:null computeBoundingBox]()</h3>
+		<div>Computes bounding box of the geometry, updating [page:Geometry Geometry.boundingBox] attribute.</div>
 
-		<h3>[method:Geometry scale] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
-		<div>
-		Scale the geometry data. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.scale] for typical real-time mesh scaling.
-		</div>
+		<h3>[method:null computeBoundingSphere]()</h3>
+		<div>Computes bounding sphere of the geometry, updating [page:Geometry Geometry.boundingSphere] attribute.</div>
 
-		<h3>[method:Geometry lookAt] ( [page:Vector3 vector] )</h3>
 		<div>
-		vector - A world vector to look at.<br />
-		</div>
-		<div>
-		Rotates the geometry to face point in space. This is typically done as a one time operation, and not during a loop
-    Use [page:Object3D.lookAt] for typical real-time mesh usage.
+			Neither bounding boxes or bounding spheres are computed by default. They need to be explicitly computed,
+			otherwise they are *null*.
 		</div>
 
 		<h3>[method:null computeFaceNormals]()</h3>
-		<div>
-		Computes face normals.
-		</div>
+		<div>Computes [page:Face3.normal face normals].</div>
+
+		<h3>[method:null computeFlatVertexNormals]()</h3>
+		<div>Computes flat [page:Face3.vertexNormals vertex normals]. Sets the vertex normal of each vertex of each face to be the same as the face's normal.</div>
+
+		<h3>[method:null computeLineDistances]()</h3>
+		<div>Compute [page:.lineDistances].</div>
+
+		<h3>[method:null computeMorphNormals]()</h3>
+		<div>Computes [page:.morphNormals].</div>
 
 		<h3>[method:null computeVertexNormals]( [page:Boolean areaWeighted] )</h3>
 		<div>
-		areaWeighted - If true the contribution of each face normal to the vertex normal is weighted by the area of the face. Default is true.
-		</div>
-		<div>
-		Computes vertex normals by averaging face normals.<br />
-		</div>
+		areaWeighted - If true the contribution of each face normal to the vertex normal is
+		weighted by the area of the face. Default is true.<br /><br />
 
-		<h3>[method:null computeFlatVertexNormals]()</h3>
-		<div>
-		Computes flat vertex normals. Sets the vertex normal of each vertex of each face to be the same as the face's normal.<br />
+		Computes vertex normals by averaging face normals.
 		</div>
 
-		<h3>[method:null computeMorphNormals]()</h3>
+		<h3>[method:Geometry copy]( [page:Geometry geometry] )</h3>
 		<div>
-		Computes morph normals.
+			Copies vertices, faces and uvs into this geometry. It does not copy any other properties of the geometry.
 		</div>
 
-		<h3>[method:null computeBoundingBox]()</h3>
+		<h3>[method:null dispose]()</h3>
 		<div>
-		Computes bounding box of the geometry, updating [page:Geometry Geometry.boundingBox] attribute.
+		Removes The object from memory. <br />
+		Don't forget to call this method when you remove a geometry because it can cause memory leaks.
 		</div>
 
-		<h3>[method:null computeBoundingSphere]()</h3>
+		<h3>[method:Geometry fromBufferGeometry]( [page:BufferGeometry geometry] )</h3>
+		<div>Convert a [page:BufferGeometry] to a Geometry.</div>
+
+		<h3>[method:Geometry lookAt] ( [page:Vector3 vector] )</h3>
 		<div>
-		Computes bounding sphere of the geometry, updating [page:Geometry Geometry.boundingSphere] attribute.
-		</div>
+		vector - A world vector to look at.<br /><br />
 
-		<div>Neither bounding boxes or bounding spheres are computed by default. They need to be explicitly computed, otherwise they are *null*.</div>
+		Rotates the geometry to face point in space. This is typically done as a one time operation, and not during a loop
+		Use [page:Object3D.lookAt] for typical real-time mesh usage.
+		</div>
 
 		<h3>[method:null merge]( [page:Geometry geometry], [page:Matrix4 matrix], [page:Integer materialIndexOffset] )</h3>
 		<div>Merge two geometries or geometry and geometry from object (using object's transform)</div>
 
+		<h3>[method:null mergeMesh]( [page:Mesh mesh] )</h3>
+		<div>Merge the mesh's geometry with this, also applying the mesh's transform.</div>
+
+
 		<h3>[method:null mergeVertices]()</h3>
 		<div>
 		Checks for duplicate vertices using hashmap.<br />
@@ -292,25 +294,46 @@
 		<h3>[method:null normalize]()</h3>
 		<div>
 		Normalize the geometry. <br />
-		Make the geometry centered and has a bounding sphere whose radius equals to 1.0.
+		Make the geometry centered and have a bounding sphere of radius *1.0*.
 		</div>
 
-		<h3>[method:Geometry clone]()</h3>
+		<h3>[method:Geometry rotateX] ( [page:Float radians] )</h3>
 		<div>
-		Creates a new clone of the Geometry.
+		Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
 		</div>
-		
-		<div>This method copies only vertices, faces and uvs. It does not copy any other properties of the geometry.</div>
 
-		<h3>[method:null dispose]()</h3>
+		<h3>[method:Geometry rotateY] ( [page:Float radians] )</h3>
 		<div>
-		Removes The object from memory. <br />
-		Don't forget to call this method when you remove a geometry because it can cause memory leaks.
+		Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
 		</div>
 
-		<h3>[method:null computeLineDistances]()</h3>
+		<h3>[method:Geometry rotateZ] ( [page:Float radians] )</h3>
 		<div>
-		Compute distances between vertices for Line geometries.
+		Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop
+    Use [page:Object3D.rotation] for typical real-time mesh rotation.
+		</div>
+
+		<h3>[method:null sortFacesByMaterialIndex] (  )</h3>
+		<div>
+			Sorts the faces array according to material index. For complex geometries with several materials,
+			this can result in reduced draw call and improved performance.
+		</div>
+
+		<h3>[method:Geometry scale] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
+		<div>
+		Scale the geometry data. This is typically done as a one time operation, and not during a loop
+		Use [page:Object3D.scale] for typical real-time mesh scaling.
+		</div>
+
+		<h3>[method:JSON toJSON] ( )</h3>
+		<div>Convert the geometry to JSON format.</div>
+
+		<h3>[method:Geometry translate] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
+		<div>
+		Translate the geometry. This is typically done as a one time operation, and not during a loop
+    Use [page:Object3D.position] for typical real-time mesh translation.
 		</div>
 
 

docs/api/core/InstancedBufferAttribute.html

+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:BufferAttribute] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+		An instanced version of [page:BufferAttribute].
+		</div>
+
+		<h2>Constructor</h2>
+		<h3>[name]( [page:TypedArray array], [page:Integer itemSize], [page:Number meshPerAttribute] )</h3>
+		<div>
+		</div>
+
+		<h2>Properties</h2>
+		See [page:BufferAttribute] for inherited properties.
+
+		<h3>[property:Number meshPerAttribute]</h3>
+		<div>
+			Default is *1*.
+		</div>
+
+		<h3>[property:Boolean isInstancedBufferAttribute]</h3>
+		<div>
+			Default is *true*.
+		</div>
+
+		<h2>Methods</h2>
+		See [page:BufferAttribute] for inherited methods.
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/api/core/InstancedBufferGeometry.html

+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:BufferGeometry] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+		An instanced version of [page:BufferGeometry].
+		</div>
+
+		<h2>Constructor</h2>
+		<h3>[name]( )</h3>
+		<div>
+		</div>
+
+		<h2>Properties</h2>
+		See [page:BufferGeometry] for inherited properties.
+
+		<h3>[property:Number maxInstancedCount]</h3>
+		<div>
+			Default is *undefined*.
+		</div>
+
+		<h3>[property:Boolean isInstancedBufferGeometry]</h3>
+		<div>
+			Default is *true*.
+		</div>
+
+		<h2>Methods</h2>
+		See [page:BufferAttribute] for inherited methods.
+
+		<h3>[property:Number addGroup]( start, count, materialIndex )</h3>
+		<div>
+
+		</div>
+
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/api/core/InstancedInterleavedBuffer.html

+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:InterleavedBuffer] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+		An instanced version of [page:InterleavedBuffer].
+		</div>
+
+		<h2>Constructor</h2>
+		<h3>[name]( [page:TypedArray array], [page:Integer itemSize], [page:Number meshPerAttribute] )</h3>
+		<div>
+		</div>
+
+		<h2>Properties</h2>
+		See [page:InterleavedBuffer] for inherited properties.
+
+		<h3>[property:Number meshPerAttribute]</h3>
+		<div>
+			Default is *1*.
+		</div>
+
+		<h3>[property:Boolean isInstancedInterleavedBuffer]</h3>
+		<div>
+			Default is *true*.
+		</div>
+
+		<h2>Methods</h2>
+		See [page:InterleavedBuffer] for inherited methods.
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

docs/api/core/Uniform.html

@@ -27,7 +27,14 @@
 		<h3>Uniform types</h3>
 
 		<p>
-		Each uniform must have a *value* property. The type of the value must correspond to the type of the uniform variable in the GLSL code as specified for the primitive GLSL types in the table below. Uniform structures and arrays are also supported. GLSL arrays of primitive type must either be specified as an array of the corresponding THREE objects or as a flat array containing the data of all the objects. In other words; GLSL primitives in arrays must not be represented by arrays. This rule does not apply transitively.  An array of *vec2* arrays, each with a length of five vectors, must be an array of arrays, of either five *THREE.Vector2* objects or ten *number*s.
+		Each uniform must have a *value* property. The type of the value must correspond to the
+		type of the uniform variable in the GLSL code as specified for the primitive GLSL types
+		in the table below. Uniform structures and arrays are also supported. GLSL arrays of primitive
+		type must either be specified as an array of the corresponding THREE objects or as a flat
+		array containing the data of all the objects. In other words; GLSL primitives in arrays
+		must not be represented by arrays. This rule does not apply transitively.
+		An array of *vec2* arrays, each with a length of five vectors, must be an array of arrays,
+		of either five [page:Vector2] objects or ten *number*s.
 		</p>
 		<table>
 			<caption><a id="uniform-types">Uniform types</a></caption>
@@ -189,6 +196,16 @@
 		Current value of the uniform.
 		</div>
 
+		<h2>Methods</h2>
+
+		<h3>[method:Uniform clone]()</h3>
+		<div>
+		Returns a clone of this uniform.<br />
+		If the uniform's value property is an [page:Object] with a clone() method, this is used, otherwise the value is copied by assigment.
+		Array values are shared between cloned [page:Uniform]s.<br /><br />
+		See [example:webgldeferred_animation WebGL deferred animation] for an example of this method in use.
+		</div>
+
 		<h2>Source</h2>
 
 		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]

docs/api/deprecated/DeprecatedList.html

@@ -194,6 +194,9 @@
 
 		<h2>Helpers</h2>
 
+		<h3>[page:BoundingBoxHelper]</h3>
+		<div>BoundingBoxHelper has been deprecated. Use [page:BoxHelper] instead.</div>
+
 		<h3>[page:EdgesHelper]</h3>
 		<div>EdgesHelper has been removed. Use [page:EdgesGeometry] instead.</div>
 
@@ -300,7 +303,7 @@
 		<h3>[page:Matrix4]</h3>
 		<div>
 			Matrix4.flattenToArrayOffset is deprecated. Use [page:Matrix4.toArray]() instead.<br /><br />
-			
+
 			Matrix4.extractPosition() has been renamed to [page:Matrix4.copyPosition]( matrix ).<br /><br />
 
 			Matrix4.getPosition() has been removed. Use [page:Vector3.setFromMatrixPosition]( matrix ) instead.<br /><br />

docs/api/extras/helpers/SkeletonHelper.html

@@ -46,7 +46,7 @@ scene.add( helper );
 
 		<h3>[property:Array bones]</h3>
 		<div>
-		The list of bones that the helper renders as [page:Line Line]s.
+		The list of bones that the helper renders as [page:Line Lines].
 		</div>
 
 		<h3>[property:Object root]</h3>

docs/examples/loaders/PDBLoader.html

@@ -63,7 +63,7 @@
 		<h3>[method:null load]( [page:String url], [page:Function onLoad], [page:Function onProgress], [page:Function onError] )</h3>
 		<div>
 		[page:String url] — required. URL to the <em>.pdb</em> file<br />
-		[page:Function onLoad] — Will be called when load completes. The arguments will be an [page:Geometry geometryAtoms], [page:Geometry geometryBonds] and the [page:Object JSON] structure.<br />
+		[page:Function onLoad] — Will be called when load completes. The arguments will be an [page:BufferGeometry geometryAtoms], [page:BufferGeometry geometryBonds] and the [page:Object JSON] structure.<br />
 		[page:Function onProgress] — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br />
 		[page:Function onError] — Will be called when load errors.<br />
 		</div>
@@ -82,10 +82,10 @@
 		<h3>[method:null createModel]( [page:Object json], [page:Function callback] )</h3>
 		<div>
 		[page:Object json] — The <em>(JSON) pdb</em> structure to parse.<br />
-		[page:Function callback] — Will be called when parse completes, with three arguments: [page:Geometry geometryAtoms], [page:Geometry geometryBonds] and the original [page:Object json].<br />
+		[page:Function callback] — Will be called when parse completes, with three arguments: [page:BufferGeometry geometryAtoms], [page:BufferGeometry geometryBonds] and the original [page:Object json].<br />
 		</div>
 		<div>
-		Parse a <em>(JSON) pdb</em> structure and return two [page:Geometry]: one for atoms, one for bonds.<br />
+		Parse a <em>(JSON) pdb</em> structure and return two [page:BufferGeometry]: one for atoms, one for bonds.<br />
 		</div>