Fleshed out more Geometry docs.

docs/api/core/Face3.rst

@@ -35,34 +35,43 @@ Face3 - Triangle face
 
     Face normal
 
-    ``default (0,0,0)``
+    :class:`Vector3` - default ``(0,0,0)``
 
 .. attribute:: Face3.color
 
     Face color
 
-    ``default white``
+    :class:`Color` - default ``white``
 
 .. attribute:: Face3.centroid
 
     Face centroid
 
+    :class:`Vector3` - default ``(0,0,0)``
+
 .. attribute:: Face3.vertexNormals
 
-    Array of vertex normals
+    Array of 3 vertex normals
+
+    default ``[]``
 
 .. attribute:: Face3.vertexColors
 
-    Array of vertex colors
+    Array of 3 vertex colors
+
+    default ``[]``
 
 .. attribute:: Face3.vertexTangents
 
-    Array of vertex tangents
+    Array of 3 vertex tangents
+
+    default ``[]``
 
 .. attribute:: Face3.materialIndex
 
-    Material index (points to ``geometry.materials`` array)
+    Material index (points to :attr:`Geometry.materials` array)
 
+    default ``0``
 
 .. rubric:: Example
 

docs/api/core/Face4.rst

@@ -40,33 +40,41 @@ Face4 - Quad face
 
     Face normal
 
-    ``default (0,0,0)``
+    :class:`Vector3` - default ``(0,0,0)``
 
 .. attribute:: Face4.color
 
     Face color
 
-    ``default white``
+    :class:`Color` - default ``white``
 
 .. attribute:: Face4.centroid
 
-    Face centroid
+    :class:`Vector3` - default ``(0,0,0)``
 
 .. attribute:: Face4.vertexNormals
 
-    Array of vertex normals
+    Array of 4 vertex normals
+
+    default ``[]``
 
 .. attribute:: Face4.vertexColors
 
-    Array of vertex colors
+    Array of 4 vertex colors
+
+    default ``[]``
 
 .. attribute:: Face4.vertexTangents
 
-    Array of vertex tangents
+    Array of 4 vertex tangents
+
+    default ``[]``
 
 .. attribute:: Face4.materialIndex
 
-    Material index (points to ``geometry.materials`` array)
+    Material index (points to :attr:`Geometry.materials` array)
+
+    default ``0``
 
 
 .. rubric:: Example

docs/api/core/Geometry.rst

@@ -1,115 +1,186 @@
-Geometry - Base class for geometry types
+Geometry - Base class for geometries
 ----------------------------------------
 
 .. rubric:: Constructor
 
 .. class:: Geometry()
 
-    Base class for geometry types
+    Base class for geometries
+
+    Encapsulates unique instances of vertex buffer objects in :class:`WebGLRenderer`
+
 
 .. rubric:: Attributes
 
 .. attribute:: Geometry.id
 
-    Unique number of the geometry
+    Unique number of this geometry instance
 
-.. attribute:: Geometry.vertices
+.. attribute:: Geometry.boundingBox
+
+    Bounding box
+
+    ::
 
-    Array of vertices
+        boundingBox = { min: new THREE.Vector3(), max: new THREE.Vector3() }
 
-.. attribute:: Geometry.colors;
+.. attribute:: Geometry.boundingSphere
+
+    Bounding sphere
+
+    ::
 
- 
-   Array of one-to-one vertex colors, used in ParticleSystem, Line and Ribbon
+        boundingSphere = { radius: float }
 
 .. attribute:: Geometry.materials
 
-    //todo:description
+    Array of :class:`materials <Material>`
+
+    Used with models containing multiple materials in a single geometry (with pass-through :class:`MeshFaceMaterial`)
+
+    Face indices index into this array.
+
+
+.. rubric:: Attribute buffers
 
 .. attribute:: Geometry.faces
 
-    //todo:description
+    Array of faces (:class:`Face3`, :class:`Face4`)
+
+.. attribute:: Geometry.vertices
+
+    Array of :class:`vertices <Vertex>`
+
+    Face indices index into this array.
+
+.. attribute:: Geometry.colors
+
+   Array of vertex :class:`colors <Color>`, matching number and order of vertices.
+
+   Used in :class:`ParticleSystem`, :class:`Line` and :class:`Ribbon`.
+
+   :class:`Meshes <Mesh>` use per-face-use-of-vertex colors embedded directly in faces.
 
 .. attribute:: Geometry.faceUvs
 
-    //todo:description
+    Array of face UV layers.
+    Each UV layer is an array of :class:`UV` matching order and number of faces.
 
 .. attribute:: Geometry.faceVertexUvs
 
-    //todo:description
+    Array of vertex UV layers.
+    Each UV layer is an array of :class:`UV` matching order and number of vertices in faces.
 
 .. attribute:: Geometry.morphTargets
 
-    //todo:description
+    Array of morph targets.
+    Each morph target is JS object:
+
+    ::
+
+        morphTarget = { name: "targetName", vertices: [ new THREE.Vertex(), ... ] }
+
+    Morph vertices match number and order of primary vertices.
 
 .. attribute:: Geometry.morphColors
 
-    //todo:description
+    Array of morph colors.
+    Morph colors have similar structure as morph targets, each color set is JS object:
 
-.. attribute:: Geometry.skinWeights
+    ::
 
-    //todo:description
+        morphColor = { name: "colorName", colors: [ new THREE.Color(), ... ] }
 
-.. attribute:: Geometry.skinIndices
+    Morph colors can match either number and order of faces (face colors) or number of vertices (vertex colors).
 
-    //todo:description
+.. attribute:: Geometry.skinWeights
 
-.. attribute:: Geometry.boundingBox
+    Array of skinning weights (:class:`Vector4`), matching number and order of vertices.
 
-    //todo:description
+.. attribute:: Geometry.skinIndices
+
+    Array of skinning indices (:class:`Vector4`), matching number and order of vertices.
 
-.. attribute:: Geometry.boundingSphere
 
-    //todo:description
+.. rubric:: Flags
 
 .. attribute:: Geometry.hasTangents
 
-    //todo:description
+    True if geometry has tangents. Set in :func:`Geometry.computeTangents`
+
+    ``default false``
 
 .. attribute:: Geometry.dynamic
 
-    //todo:description
-    
-    Unless set to true the *Arrays* will be deleted once sent to a buffer.
-    
+    Set to `true` if attribute buffers will need to change in runtime (using ``dirty`` flags).
+
+    Unless set to true internal typed arrays corresponding to buffers will be deleted once sent to GPU.
+
+    ``default false``
+
+
 .. rubric:: Methods
 
-.. function:: Geometry.applyMatrix(matrix)
+.. function:: Geometry.applyMatrix( matrix )
+
+    Bake matrix transform directly into vertex coordinates
 
-    //todo:description
-    
-    :param Matrix4 matrix: //todo
+    :param Matrix4 matrix: matrix transform
 
 .. function:: Geometry.computeCentroids()
 
-    //todo:description
+    Compute centroids for all faces
 
 .. function:: Geometry.computeFaceNormals()
 
-    //todo:description
+    Compute face normals
 
 .. function:: Geometry.computeVertexNormals()
 
-    //todo:description
+    Compute vertex normals by averaging face normals.
+
+    Face normals must be existing / computed beforehand.
 
 .. function:: Geometry.computeTangents()
 
-    //todo:description
+    Compute vertex tangents
+
+    Based on http://www.terathon.com/code/tangent.html
+
+    Geometry must have vertex UVs (layer 0 will be used).
 
 .. function:: Geometry.computeBoundingBox()
 
-    //todo:description
+    Compute bounding box of the geometry, updating :attr:`Geometry.boundingBox` attribute.
 
 .. function:: Geometry.computeBoundingSphere()
 
-    //todo:description
+    Compute bounding sphere of the geometry, updating :attr:`Geometry.boundingSphere` attribute.
 
 .. function:: Geometry.mergeVertices()
 
-    //todo:description
+    Checks for duplicate vertices using hashmap.
+    Duplicated vertices are removed and faces' vertices are updated.
 
-.. rubric:: Example(s)
+.. rubric:: Example
 
 ::
 
-//todo::example
+    // geometry with random points
+    // (useful for example with ParticleSystem)
+
+    var n = 10000;
+    var geometry = new THREE.Geometry()
+    for ( var i = 0; i < n; i ++ ) {
+
+        var x = THREE.MathUtils.randFloatSpread( 1000 );
+        var y = THREE.MathUtils.randFloatSpread( 1000 );
+        var z = THREE.MathUtils.randFloatSpread( 1000 );
+        var position = new THREE.Vector3( x, y, z );
+        var vertex = new THREE.Vertex( position );
+
+        geometry.vertices.push( vertex );
+
+    }
+
+    geometry.computeBoundingSphere();