InterleavedBuffer: Improve example and docs

docs/api/core/InterleavedBuffer.html

@@ -11,21 +11,34 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
+			"Interleaved" means that multiple types of data (position, color etc.) are packed into a single array buffer.
+			Organizing geometry data in this way improves memory locality. By keeping vertex data close together, it is more likely
+			that also caches (e.g. pre-transform vertex cache) store logically related data together. This leads to more cache hits and a better performance.
+			<br/><br/>
+			An introduction into interleaved arrays can be found here: [link:https://blog.tojicode.com/2011/05/interleaved-array-basics.html Interleaved array basics]
 		</div>
 
+		<h2>Example</h2>
+
+		<div>[example:webgl_buffergeometry_points_interleaved webgl / buffergeometry / points / interleaved]</div>
+
 		<h2>Constructor</h2>
 		<h3>[name]( [page:TypedArray array], [page:Integer stride] )</h3>
 		<div>
+			[page:TypedArray array] -- A typed array with a shared buffer. Stores the geometry data.<br/>
+			[page:Integer stride] -- How far apart is the start of each vertex.
 		</div>
 
 		<h2>Properties</h2>
 
 		<h3>[property:Array array]</h3>
 		<div>
+			 A typed array with a shared buffer. Stores the geometry data.
 		</div>
 
 		<h3>[property:Integer stride]</h3>
 		<div>
+			How far apart is the start of each vertex.
 		</div>
 
 		<h3>[property:Integer count]</h3>
@@ -45,7 +58,7 @@
 
 		<h3>[property:Number updateRange.offset]</h3>
 		<div>
-		DEfault is *0*.
+		Default is *0*.
 		</div>
 
 		<h3>[property:Number updateRange.count]</h3>
@@ -82,19 +95,23 @@
 
 		<h3>[method:InterleavedBuffer copy]( source ) </h3>
 		<div>
-		 Copy the array, count, stride and value of dynamic to this.
+		 Copies another [name] to this [name].
 		</div>
 
 		<h3>[method:InterleavedBuffer copyAt]( index1, attribute, index2 ) </h3>
-		<div>
-		</div>
+		<div>Copies data from attribute[index2] to [page:InterleavedBuffer.array array][index1].</div>
 
 		<h3>[method:InterleavedBuffer set]( value, offset ) </h3>
 		<div>
+			value - The source (typed) array.<br/>
+			offset - The offset into the target array at which to begin writing values from the source array. Default is *0*.<br/><br />
+
+			Stores multiple values in the buffer, reading input values from a specified array.
 		</div>
 
-		<h3>[method:InterleavedBuffer clone]( index, x, y ) </h3>
+		<h3>[method:InterleavedBuffer clone]() </h3>
 		<div>
+			Creates a clone of this [name].
 		</div>
 
 		<h2>Source</h2>

docs/api/core/InterleavedBufferAttribute.html

@@ -36,16 +36,18 @@
 		<div>
 			The value of [page:InterleavedBufferAttribute.data data].count.
 
-			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.
+			If the buffer is storing a 3-component item (such as a position, normal, or color),
+			then this will count the number of such items stored.
 		</div>
 
 		<h3>[property:Integer itemSize]</h3>
 		<div>
+			How many values make up each item.
 		</div>
 
 		<h3>[property:Integer offset]</h3>
 		<div>
+			The offset in the underlying array buffer where an item starts.
 		</div>
 
 		<h3>[property:Boolean normalized]</h3>
@@ -60,55 +62,38 @@
 
 		<h2>Methods</h2>
 
-		<h3>[method:null getX]( index ) </h3>
-		<div>
-
-		</div>
-
-		<h3>[method:null getY]( index ) </h3>
-		<div>
+		<h3>[method:Number getX]( index ) </h3>
+		<div>Returns the x component of the item at the given index.</div>
 
-		</div>
+		<h3>[method:Number getY]( index ) </h3>
+		<div>Returns the y component of the item at the given index.</div>
 
-		<h3>[method:null getZ]( index ) </h3>
-		<div>
+		<h3>[method:Number getZ]( index ) </h3>
+		<div>Returns the z component of the item at the given index.</div>
 
-		</div>
-
-		<h3>[method:null getW]( index ) </h3>
-		<div>
-
-		</div>
+		<h3>[method:Number getW]( index ) </h3>
+		<div>Returns the w component of the item at the given index.</div>
 
 		<h3>[method:null setX]( index, x ) </h3>
-		<div>
-
-		</div>
+		<div>Sets the x component of the item at the given index.</div>
 
 		<h3>[method:null setY]( index, y ) </h3>
-		<div>
-
-		</div>
+		<div>Sets the y component of the item at the given index.</div>
 
 		<h3>[method:null setZ]( index, z ) </h3>
-		<div>
+		<div>Sets the z component of the item at the given index.</div>
 
-		</div>
+		<h3>[method:null setW]( index, w ) </h3>
+		<div>Sets the w component of the item at the given index.</div>
 
 		<h3>[method:null setXY]( index, x, y ) </h3>
-		<div>
-
-		</div>
+		<div>Sets the x and y components of the item at the given index.</div>
 
 		<h3>[method:null setXYZ]( index, x, y, z ) </h3>
-		<div>
-
-		</div>
+		<div>Sets the x, y and z components of the item at the given index.</div>
 
 		<h3>[method:null setXYZW]( index, x, y, z, w ) </h3>
-		<div>
-
-		</div>
+		<div>Sets the x, y, z and w components of the item at the given index.</div>
 
 
 

examples/webgl_buffergeometry_points_interleaved.html

@@ -67,26 +67,34 @@
 
 				var geometry = new THREE.BufferGeometry();
 
-				var interleaved_buffer_float32 = new Float32Array( particles * 4 );
-				var interleaved_buffer_uint8 = new Uint8Array( interleaved_buffer_float32.buffer );
+				// create a generic buffer of binary data (a single particle has 16 bytes of data)
+
+				var arrayBuffer = new ArrayBuffer( particles * 16 );
+
+				// the following typed arrays share the same buffer
+
+				var interleavedFloat32Buffer = new Float32Array( arrayBuffer );
+				var interleavedUint8Buffer = new Uint8Array( arrayBuffer );
+
+				//
 
 				var color = new THREE.Color();
 
 				var n = 1000, n2 = n / 2; // particles spread in the cube
 
-				for ( var i = 0; i < interleaved_buffer_float32.length; i += 4 ) {
+				for ( var i = 0; i < interleavedFloat32Buffer.length; i += 4 ) {
 
-					// positions
+					// position (first 12 bytes)
 
 					var x = Math.random() * n - n2;
 					var y = Math.random() * n - n2;
 					var z = Math.random() * n - n2;
 
-					interleaved_buffer_float32[ i + 0 ] = x;
-					interleaved_buffer_float32[ i + 1 ] = y;
-					interleaved_buffer_float32[ i + 2 ] = z;
+					interleavedFloat32Buffer[ i + 0 ] = x;
+					interleavedFloat32Buffer[ i + 1 ] = y;
+					interleavedFloat32Buffer[ i + 2 ] = z;
 
-					// colors
+					// color (last 4 bytes)
 
 					var vx = ( x / n ) + 0.5;
 					var vy = ( y / n ) + 0.5;
@@ -96,19 +104,18 @@
 
 					var j = ( i + 3 ) * 4;
 
-					interleaved_buffer_uint8[ j + 0 ] = color.r * 255;
-					interleaved_buffer_uint8[ j + 1 ] = color.g * 255;
-					interleaved_buffer_uint8[ j + 2 ] = color.b * 255;
-					interleaved_buffer_uint8[ j + 3 ] = 0;
+					interleavedUint8Buffer[ j + 0 ] = color.r * 255;
+					interleavedUint8Buffer[ j + 1 ] = color.g * 255;
+					interleavedUint8Buffer[ j + 2 ] = color.b * 255;
+					interleavedUint8Buffer[ j + 3 ] = 0; // not needed
 
 				}
 
-				var ibp = new THREE.InterleavedBuffer( interleaved_buffer_float32, 4 );
-				var ibc = new THREE.InterleavedBuffer( interleaved_buffer_uint8, 16 );
+				var interleavedPositionBuffer = new THREE.InterleavedBuffer( interleavedFloat32Buffer, 4 );
+				var interleavedColorBuffer = new THREE.InterleavedBuffer( interleavedUint8Buffer, 16 );
 
-				geometry.addAttribute( 'position', new THREE.InterleavedBufferAttribute( ibp, 3, 0, false ) );
-				geometry.addAttribute( 'color', new THREE.InterleavedBufferAttribute( ibc, 3, 12, true ) );
-				// geometry.computeBoundingSphere();
+				geometry.addAttribute( 'position', new THREE.InterleavedBufferAttribute( interleavedPositionBuffer, 3, 0, false ) );
+				geometry.addAttribute( 'color', new THREE.InterleavedBufferAttribute( interleavedColorBuffer, 3, 12, true ) );
 
 				//