Added detail to BufferAttribute doc

docs/api/core/BufferAttribute.html

@@ -11,112 +11,200 @@
 		<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: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>
-		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.
+		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:Boolean normalized]</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.
+		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:Integer version]</h3>
+		<h3>[property:Function onUploadCallback]</h3>
 		<div>
-		A version number, incremented every time the needsUpdate property is set to true.
+		A callback function that is executed after the Renderer has transfered the attribute array data to the GPU.
 		</div>
 
-		<h3>[property:Function onUploadCallback]</h3>
+		<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 />
+
+			This can be used to only update some components of stored vectors (for example, just the component
+			related to color).
+		</div>
+
+		<h3>[property:String uuid]</h3>
 		<div>
-		A callback function that is executed after the Renderer has transfered the attribute array data to the GPU.
+		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
+		This gets automatically assigned, so this shouldn't be edited.
 		</div>
 
+		<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: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.
+		<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 set] ( [page:Array value] ) </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 associated array with values from the passed array.
+		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 setX]( index, x ) </h3>
+		<h3>[method:null set] ( [page:Array value], [page:Integer offset] ) </h3>
 		<div>
-		Sets the value of the array at <code>index * itemSize</code> to x
+		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 setY]( index, y ) </h3>
+		<h3>[method:null setArray] ( [page:TypedArray array] ) </h3>
 		<div>
-		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 value of the array at <code>index * itemSize + 2</code> to z
-		</div>
+		<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 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
-		</div>
+		<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>