X-Git-Url: http://git.rot13.org/?a=blobdiff_plain;f=examples%2Fboard_reprap%2Fsrc%2Fc3%2Fc3object.h;h=1ee1d9c27821310ee5de2963d1143a2452b8934f;hb=a6fbd08748c1325f221b1f2e4e619df56df65535;hp=dd77975eea70030fe543501d4cb8aa05e780b277;hpb=b73f9b6094e2c9639fded52022ec60556ae8f8de;p=simavr

diff --git a/examples/board_reprap/src/c3/c3object.h b/examples/board_reprap/src/c3/c3object.h
index dd77975..1ee1d9c 100644
--- a/examples/board_reprap/src/c3/c3object.h
+++ b/examples/board_reprap/src/c3/c3object.h
@@ -31,51 +31,87 @@ struct c3object_t;
 
 DECLARE_C_ARRAY(struct c3object_t*, c3object_array, 4);
 
+//! c3object is a container for child object, and geometry
+/*!
+ * a c3object is a node in a c3object tree, it contains sub-objects and/or
+ * geometry. It also contains it's own list of transform matrices, so can
+ * be seen as a "anchor" that can be moved around and where you can
+ * attach other objects or geometry.
+ *
+ * An object has a notion of 'dirty bit' -- something that signals that
+ * something has changed and deserved reprojection. the dirty bit
+ * is propagated upward when 1 (up to the root object) and downward when 0
+ * (to allow clearing the bit on a subtree)
+ */
 typedef struct c3object_t {
-	str_p name;
-	int	dirty : 1, visible : 1 /* TODO: Implement visible */;
-	struct c3context_t * context;
-	struct c3object_t * parent;
-	const struct c3driver_object_t ** driver;
+	str_p 				name;	//! optional name
+	int					dirty : 1, 
+						visible : 1 /* TODO: Implement visible */;
+	struct c3context_t * context; //! context this object is attached to
+	struct c3object_t * parent;		//! Parent object
+	const struct c3driver_object_t ** driver;	//! Driver stack
 	c3transform_array_t	transform;
-	c3object_array_t	objects;
-	c3geometry_array_t	geometry;
+	c3object_array_t	objects;	//! child object list
+	c3geometry_array_t	geometry;	//! Object geometri(es)
 } c3object_t, *c3object_p;
 
+//! Allocates and initialize an emty object, attaches it to parent 'o'
 c3object_p
 c3object_new(
 		c3object_p o /* = NULL */);
+//! Disposes of everything under this object
 void
 c3object_dispose(
 		c3object_p o);
+//! Clears every sub-object, geometry, and transform, but do not dispose of o
 void
 c3object_clear(
 		c3object_p o);
-
+//! Initializes 'o' as a new object, attaches it to parent (optional)
 c3object_p
 c3object_init(
-		c3object_p o /* = NULL */,
-		c3object_p parent);
-
+		c3object_p o,
+		c3object_p parent /* = NULL */);
+//! sets the dirty bit for 'o' and related tree
+/*!
+ * When dirty is 1, sets the dirty bit of this object and all the parent
+ * objects up to the root object.
+ * When dirty is 0, clear the dirty bit of this object, and all the
+ * sub objects.
+ */
 void
 c3object_set_dirty(
 		c3object_p o,
 		bool dirty);
+//! Adds a new geometry g to object o
 void
 c3object_add_geometry(
 		c3object_p o,
 		c3geometry_p g);
+//! Adds a new sub-object sub to object o
 void
 c3object_add_object(
 		c3object_p o,
 		c3object_p sub);
+//! Adds a new transform matrix, initialized as identity
 c3transform_p
 c3object_add_transform(
 		c3object_p o );
+//! Iterates all the sub-objects and collects all the geometries
+/*!
+ * This call iterates the sub-objects and collects all their 'projected'
+ * geometry, and add them to the array
+ */
 void
 c3object_get_geometry(
 		c3object_p o,
 		c3geometry_array_p array );
+//! Project object 'o' using it's own transformations, relative to matrix 'm'
+/*!
+ * Multiply this objects transformation(s) to matrix 'm' and calls
+ * reprojects the geometries using that matrix as an anchor. also call
+ * recursively to sub-objects to follow the projection down.
+ */
 void
 c3object_project(
 		c3object_p o,