Added BufferGeometry section

docs/manual/introduction/How-to-update-things.html

@@ -34,24 +34,106 @@ object.updateMatrix();
 
 		<h2>Geometries</h2>
 		<div>
-			<p>
-				You can only update the content of buffers, you cannot resize buffers (this is very costly,
-				basically equivalent to creating new geometry).
-			</p>
-
-			<p>
-				You can emulate resizing by pre-allocating a larger buffer and then keeping unneeded vertices
-				collapsed / hidden.
-			</p>
-
-			<p>
-				The following flag control updating of various geometry attributes. Set flags only
-				for attributes that you need to update, updates are costly. Once buffers
-				change, these flags reset automatically back to false. You need to keep setting them to
-				true if you wanna keep updating buffers. Note that this applies only to [page:Geometry]
-				and not to [page:BufferGeometry].
-			</p>
-			<code>
+			<h3>[page:BufferGeometry]</h3>
+			<div>
+				<p>
+					BufferGeometries store information (such as vertex positions, face indices, normals, colors,
+					UVs, and any custom attributes) in [page:BufferAttribute buffers] - that is,
+					[link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays typed arrays].
+					This makes them generally faster than standard Geometries, at the cost of being somewhat harder to
+					work with.
+				</p>
+				<p>
+					With regards to updating BufferGeometries, the most important thing to understand is that you
+					you cannot resize buffers (this is very costly,	basically the equivalent to creating new a geometry).
+					You can however update the content of buffers.
+				</p>
+				<p>
+					This means that if you know an attribute of you BufferGeometry will grow, say the number of vertices,
+					you must pre-allocate a buffer large enough to hold any new vertices that may be created. Of
+					course, this also means that there will be a maximum size for your BufferGeometry - there is
+					no way to create a BufferGeometry that can efficiently be extended indefinitely.
+				</p>
+				<p>
+					We'll use the example of a line that gets extended at render time. We'll allocate space
+					in the buffer for 500 vertices but draw only two at first, using [page:BufferGeometry.drawRange].
+				</p>
+				<code>
+var MAX_POINTS = 500;
+
+// geometry
+var geometry = new THREE.BufferGeometry();
+
+// attributes
+var positions = new Float32Array( MAX_POINTS * 3 ); // 3 vertices per point
+geometry.addAttribute( 'position', new THREE.BufferAttribute( positions, 3 ) );
+
+// draw range
+drawCount = 2; // draw the first 2 points, only
+geometry.setDrawRange( 0, drawCount );
+
+// material
+var material = new THREE.LineBasicMaterial( { color: 0xff0000, linewidth: 2 } );
+
+// line
+line = new THREE.Line( geometry,  material );
+scene.add( line );
+				</code>
+			 	<p>
+					Next we'll randomly add points to the line using a pattern like:
+				</p>
+				<code>
+var positions = line.geometry.attributes.position.array;
+
+var x = y = z = index = 0;
+
+for ( var i = 0, l = MAX_POINTS; i < l; i ++ ) {
+
+    positions[ index ++ ] = x;
+    positions[ index ++ ] = y;
+    positions[ index ++ ] = z;
+
+    x += ( Math.random() - 0.5 ) * 30;
+    y += ( Math.random() - 0.5 ) * 30;
+    z += ( Math.random() - 0.5 ) * 30;
+
+}
+				</code>
+				<p>
+					If you want to change the <em>number of points</em> rendered after the first render, do this:
+				</p>
+				<code>
+line.geometry.setDrawRange( 0, newValue );
+				</code>
+				<p>
+					If you want to change the position data values after the first render, you need to
+					set the needsUpdate flag like so:
+				</p>
+				<code>
+line.geometry.attributes.position.needsUpdate = true; // required after the first render
+				</code>
+
+				<p>
+					[link:http://jsfiddle.net/w67tzfhx/ Here is a fiddle] showing an animated line which you can adapt to your use case.
+				</p>
+
+				<h4>Examples:</h4>
+					[example:webgl_custom_attributes WebGL / custom / attributes]<br />
+					[example:webgl_buffergeometry_custom_attributes_particles WebGL / buffergeometry / custom / attributes / particles]
+
+
+			</div>
+
+			<h3>[page:Geometry]</h3>
+			<div>
+				<p>
+					The following flag control updating of various geometry attributes. Set flags only
+					for attributes that you need to update, updates are costly. Once buffers
+					change, these flags reset automatically back to false. You need to keep setting them to
+					true if you wanna keep updating buffers. Note that this applies only to [page:Geometry]
+					and not to [page:BufferGeometry].
+				</p>
+				<code>
 var geometry = new THREE.Geometry();
 geometry.verticesNeedUpdate = true;
 geometry.elementsNeedUpdate = true;
@@ -60,22 +142,22 @@ geometry.uvsNeedUpdate = true;
 geometry.normalsNeedUpdate = true;
 geometry.colorsNeedUpdate = true;
 geometry.tangentsNeedUpdate = true;
-			</code>
+				</code>
 
-			<p>
-				In versions prior to [link:https://github.com/mrdoob/three.js/releases/tag/r66 r66] meshes
-				additionally need the <em>dynamic</em> flag enabled (to keep internal typed arrays):
-			</p>
+				<p>
+					In versions prior to [link:https://github.com/mrdoob/three.js/releases/tag/r66 r66] meshes
+					additionally need the <em>dynamic</em> flag enabled (to keep internal typed arrays):
+				</p>
 
-			<code>
-	//removed after r66
-	geometry.dynamic = true;
-			</code>
+				<code>
+		//removed after r66
+		geometry.dynamic = true;
+				</code>
+
+				<h4>Example:</h4>
+					[example:webgl_geometry_dynamic WebGL / geometry / dynamic]<br />
+			</div>
 
-			<h3>Examples:</h3>
-				[example:webgl_geometry_dynamic WebGL / geometry / dynamic]<br />
-				[example:webgl_custom_attributes WebGL / custom / attributes]<br />
-				[example:webgl_custom_attributes_particles WebGL / custom / attributes / particles]
 		</div>