GameObject: Document many of its functions.

Also rename `get_dimensions` to `get_local_dimensions`, add
`get_world_dimensions` for consistency, and add `children_recursive_and_self`.

src/objects/gameobject.nim

@@ -92,7 +92,8 @@ proc get_local_Z_vector*(self: GameObject): Vec3
 proc get_world_X_vector*(self: GameObject): Vec3
 proc get_world_Y_vector*(self: GameObject): Vec3
 proc get_world_Z_vector*(self: GameObject): Vec3
-proc get_dimensions*(self: GameObject): Vec3
+proc get_local_dimensions*(self: GameObject): Vec3
+proc get_world_dimensions*(self: GameObject): Vec3
 proc get_world_scale*(self: GameObject): float
 proc get_world_scale_vector*(self: GameObject): Vec3
 proc get_local_size*(self: GameObject): float
@@ -392,6 +393,9 @@ proc clone*(self: GameObject,
         scene: Scene=self.scene,
         instance_body: bool=true
     ): GameObject =
+    ## Makes a clone of the object and its children (unless `recursive` is
+    ## false).
+
     case self.otype:
     of TGameObject:
         var n = new GameObject
@@ -440,9 +444,17 @@ proc clone_impl*(self: GameObject, n: var GameObject, recursive: bool,
     return n
 
 proc set_parent*(self: GameObject, parent: GameObject, keep_transform: bool=true) =
+    ## Sets the parent of the object, while keeping the same transform in world
+    ## space (unless you set `keep_transform` to false).
+    
+    # TODO: there should be no distinction between this and parent_to
     self.scene.make_parent(parent, self, keep_transform=keep_transform)
 
 proc parent_to*(self: GameObject, parent: GameObject, keep_transform: bool=true) =
+    ## Sets the parent of the object, while adding it to the same scene if
+    ## needed, as well as keeping the same transform in world space (unless you
+    ## set `keep_transform` to false).
+    
     # TODO move this to make_parent
     if self.scene == nil:
         parent.scene.add_object(self)
@@ -452,12 +464,17 @@ proc clear_parent*(self: GameObject, keep_transform: bool=true) =
     self.scene.clear_parent(self, keep_transform=keep_transform)
 
 proc get_top_ancestor*(self: GameObject, top_level_parents: seq[GameObject] = @[]): GameObject =
+    ## Find the topmost ancestor (e.g. parent of parent of parent...) or an 
+    ## object contained in `top_level_parents`, whatever happens first.
     var ob = self
     while ob.parent != nil and ob.parent notin top_level_parents:
         ob = ob.parent
     return ob
 
 iterator children_recursive*(self: GameObject, include_self: static[bool] = false): GameObject =
+    ## Iterate all the descendants of the object, i.e. its children, the
+    ## children's children an so on.
+
     # NOTE: This was written before the knowledge of closure iterators
     # (by default iterators are inline and don't allow recursion)
     when include_self:
@@ -483,11 +500,20 @@ iterator children_recursive*(self: GameObject, include_self: static[bool] = fals
         else:
             break
 
+template children_recursive_and_self*(self: GameObject): GameObject =
+    ## Iterate all the descendants of the object, and include itself in the
+    ## iteration.
+    children_recursive(self, include_self = true)
+
 proc remove*(self: GameObject, recursive: bool = true) =
+    ## Remove the object from the scene it is in, without destroying it.
+    ## It will also remove its children unless you set `recursive` to false.
     if self.scene.nonNil:
         self.scene.remove_object(self, recursive)
 
 proc destroy*(self: GameObject, recursive: bool = true) =
+    ## Destroy the object and free all unused resources previously used by it.
+    ## It will also destroy its children unless you set `recursive` to false.
     if self.is_mesh and self.get_mesh.data.nonNil:
         self.get_mesh.data.gpu_buffers_delete()
         self.get_mesh.materials.setLen 0
@@ -518,27 +544,41 @@ proc convert_bone_child_to_bone_parent*(self: GameObject) =
     bone.parent_object = self
 
 proc get_local_X_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the X axis of the object in local space.
     return self.get_local_matrix[0].xyz
 
 proc get_local_Y_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the Y axis of the object in local space.
     return self.get_local_matrix[1].xyz
 
 proc get_local_Z_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the Z axis of the object in local space.
     return self.get_local_matrix[2].xyz
 
 proc get_world_X_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the X axis of the object in world space.
     return self.get_world_matrix[0].xyz
 
 proc get_world_Y_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the Y axis of the object in world space.
     return self.get_world_matrix[1].xyz
 
 proc get_world_Z_vector*(self: GameObject): Vec3 =
+    ## Get the vector of the Z axis of the object in world space.
     return self.get_world_matrix[2].xyz
 
-proc get_dimensions*(self: GameObject): Vec3 =
+proc get_local_dimensions*(self: GameObject): Vec3 =
+    ## Calculate the local dimensions of the object, i.e. the size of the
+    ## bounding box with the scale of the object.
     let (a,b) = self.bound_box
     return (b-a) * self.scale
 
+proc get_world_dimensions*(self: GameObject): Vec3 =
+    ## Calculate the world dimensions of the object, i.e. the size of the
+    ## bounding box in world scale.
+    let (a,b) = self.bound_box
+    return (b-a) * self.get_world_scale_vector
+
 proc get_world_scale*(self: GameObject): float =
     # TODO: use the diagonal of a sphere instead?
     #       i.e. length((wm*vec3(1).normalize,0).xyz)
@@ -550,46 +590,46 @@ proc get_world_scale*(self: GameObject): float =
     return s
 
 proc get_world_scale_vector*(self: GameObject): Vec3 =
+    ## Gets the world scale vector in local coordinates (i.e. relative to the
+    ## current object orientation).
     let rotation = self.get_world_rotation
     let wm = self.world_matrix
     let rot_inv = inverse(rotation)
     var wm3 = wm.to_mat3
     let wm3_b = rot_inv.to_mat3
     wm3 = wm3_b * wm3
-    let scale_x_sign = copy_sign(1.0, wm3[0,0])
-    let scale_y_sign = copy_sign(1.0, wm3[1,1])
-    let scale_z_sign = copy_sign(1.0, wm3[2,2])
     return vec3(
-        wm[0].xyz.length * scale_x_sign, 
+        copy_sign(wm[0].xyz.length, wm3[0,0]), 
-        wm[1].xyz.length * scale_y_sign, 
+        copy_sign(wm[1].xyz.length, wm3[1,1]), 
-        wm[2].xyz.length * scale_z_sign, 
+        copy_sign(wm[2].xyz.length, wm3[2,2]), 
     )
 
 proc get_local_size*(self: GameObject): float =
-    let d = self.get_dimensions()
+    ## Calculates the size of the largest dimension of the object in local
+    ## coordinates.
+    let d = self.get_local_dimensions()
     return max(max(d.x, d.y), d.z)
 
 proc set_local_size*(self: GameObject, size: SomeFloat) =
+    ## Sets the size of the object in local cordinates, given by the desired
+    ## largest dimension of the object. The other two dimensions are scaled
+    ## proportionally. If the object dimensions are zero, no action is taken.
     let current_size = self.get_local_size
     if abs(current_size) > 1e-8:
         self.scale = self.scale * size / current_size
     return
 
 proc get_world_size*(self: GameObject): float =
-    let d = self.get_dimensions()
+    ## Calculates the size of the largest dimension of the object in world
-    let size = max(max(d.x, d.y), d.z)
+    ## coordinates.
-    if self.parent != nil:
+    let d = self.get_world_dimensions()
-        let parent_z_scale = self.parent.get_world_Z_vector.length
+    return max(max(d.x, d.y), d.z)
-        return size * parent_z_scale
-    return size
 
 proc set_world_size*(self: GameObject, size: SomeFloat) =
-    var size = size
+    ## Sets the size of the object in world cordinates, given by the desired
-    if self.parent != nil:
+    ## largest dimension of the object. The other two dimensions are scaled
-        let parent_z_scale = self.parent.get_world_Z_vector.length
+    ## proportionally. If the object dimensions are zero, no action is taken.
-        if abs(parent_z_scale) > 1e-8:
+    let current_size = self.get_world_size
-            size /= parent_z_scale
-    let current_size = self.get_local_size
     if abs(current_size) > 1e-8:
         self.scale = self.scale * size / current_size
     return
@@ -602,11 +642,14 @@ proc set_name*(self: GameObject, name: string) =
     self.scene.set_ob_name(self, name)
 
 proc local_to_world*(self: GameObject, point: Vec3): Vec3 =
+    ## Transforms a point in local coordinates to world coordinates.
     return self.get_world_matrix * point
 
 proc world_to_local*(self: GameObject, point: Vec3): Vec3 =
-    # TODO: check that determinant is not zero?
+    ## Transforms a point in world coordinates to local coordinates. If the
-    # does the compiler optimize multiple calls to .determinant?
+    ## object has a scale of 0, the point is not transformed.
-    let wm = self.get_world_matrix.inverse
+    let wm = self.get_world_matrix
-    return wm * point
+    if wm.determinant != 0.0:
+        return wm.inverse * point
+    return point