cleaned up shape.lua

shape.lua

@@ -4,28 +4,38 @@ require("kara3d.quaternion")
 require("kara3d.transform")
 require("utils")
 
+-- ********** DEFINITION AND GENERIC FUNCTIONS **********
+
 shape = {class = "shape"}
 shape.__index = shape
 
 face = {class = "face"}
 face.__index = face
 
-function face.new(v, n, t)
-  local f = {vertices = v or {}, normal = n or -vector.cardinal(3, 3), tags = t}
-  setmetatable(f, face)
-  return f
-end
-
+-- Creates a new shape with transform t and faces f
 function shape.new(t, f)
   local s = {transform = t, faces = f or {}}
   setmetatable(s, shape)
   return s
 end
 
+-- Creates a new face with vertices c, normal n and tags t
+function face.new(v, n, t)
+  local f = {vertices = v or {}, normal = n or -vector.cardinal(3, 3), tags = t}
+  setmetatable(f, face)
+  return f
+end
+
+-- Clones this shape
 function shape:clone()
   return shape.new(self.transform, table.copy(self.faces))
 end
 
+-- ********** INSTANCE FUNCTIONS **********
+
+-- Generates a line for each face of this shape, with the indicated tags
+-- The boolean cull determines if the faces facing away from the screen are
+-- drawn or not
 function shape:draw(subs, line, tags, cull)
   local l = table.copy(line)
   local p = self.transform:position(true)
@@ -38,7 +48,7 @@ function shape:draw(subs, line, tags, cull)
     local face = self.faces[i]
     local n = quaternion.mul_vector(r, face.normal)
 
-    if not (cull and n:z() <= 0) then
+    if not (cull and n:z() > 0) then
       local vs = face.vertices
 
       local v = matrix.mul_vector(m, vs[#vs] + c) - p
@@ -65,14 +75,16 @@ function shape:draw(subs, line, tags, cull)
   return ""
 end
 
---[[
-     1________5
-    /|      /|
- 2/__|____/6 |     Y
- |  3|_ _|_ _|7    |__ X
- |  /    |  /     /
-4|/______|/8    Z
-]]--
+-- ********** BASIC SHAPE FUNCTIONS **********
+
+-- Returns a cube shape of side length size, that follows the transform t
+-- Schematic of the vertices:
+--      1________5
+--     /|      /|
+--  2/__|____/6 |
+--  |  3|_ _|_ _|7     __ X
+--  |  /    |  /     /|
+-- 4|/______|/8    Z  Y
 function shape.cube(t, size)
   local hs = size / 2
   local vs = {vector.new(3, {-hs, -hs, -hs}), vector.new(3, {-hs, -hs,  hs}),