reprap: c3 documentation

[simavr] / examples / board_reprap / src / c3 / c3geometry.h

diff --git a/examples/board_reprap/src/c3/c3geometry.h b/examples/board_reprap/src/c3/c3geometry.h
index 09b47cc..5a7beb1 100644 (file)
--- a/examples/board_reprap/src/c3/c3geometry.h
+++ b/examples/board_reprap/src/c3/c3geometry.h
@@ -19,6 +19,12 @@
        along with simavr.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/*
+ * c3geometry is a structure containing one set of vertices and various
+ * bits related to it. Ultimately it contains a pre-cached projected
+ * version of the vertices that the drawing code can use directly.
+ * c3geometry is aways attached to a c3object as a parent.
+ */
 
 #ifndef __C3GEOMETRY_H___
 #define __C3GEOMETRY_H___
@@ -36,28 +42,43 @@ DECLARE_C_ARRAY(c3vertex, c3vertex_array, 16);
 DECLARE_C_ARRAY(c3tex, c3tex_array, 16);
 DECLARE_C_ARRAY(c3colorf, c3colorf_array, 16);
 
+//! Geometry material. TODO: Beef up. Add vertex/fragment programs..
 typedef struct c3material_t {
        c3colorf        color;
        uint32_t        texture;
 } c3material_t;
 
+//! Bounding box. TODO: Move to a separate file?
 typedef struct c3bbox_t {
        c3vec3  min, max;
 } c3bbox_t;
 
+//! Generic geometry type
 enum {
        C3_RAW_TYPE = 0,
        C3_TRIANGLE_TYPE,
        C3_TEXTURE_TYPE,
 };
 
+/*!
+ * geometry type.
+ * The type is used as non-opengl description of what the geometry
+ * contains, like "texture", and the subtype can be used to store the
+ * real format of the vertices. like GL_LINES etc
+ */
 typedef union {
        struct  { uint32_t type : 16, subtype : 16; };
        uint32_t value;
 } c3geometry_type_t;
 
+/*!
+ * Geometry object. Describes a set of vertices, texture coordinates,
+ * normals, colors and material
+ * The projection is not set here, a geometry is always attached to a
+ * c3object that has the projection
+ */
 typedef struct c3geometry_t {
-       c3geometry_type_t       type;   // GL_LINES etc
+       c3geometry_type_t       type;   // C3_TRIANGLE_TYPE, GL_LINES etc
        int                                     dirty : 1,
                                                texture : 1,    // has a valid material.texture
                                                custom : 1;             // has a custom driver
@@ -78,27 +99,53 @@ typedef struct c3geometry_t {
 
 DECLARE_C_ARRAY(c3geometry_p, c3geometry_array, 4);
 
+//! Allocates a new geometry, init it, and attached it to parent 'o' (optional)
 c3geometry_p
 c3geometry_new(
                c3geometry_type_t type,
                struct c3object_t * o /* = NULL */);
+//! Init an existing new geometry, and attached it to parent 'o' (optional)
 c3geometry_p
 c3geometry_init(
                c3geometry_p g,
                c3geometry_type_t type,
                struct c3object_t * o /* = NULL */);
+//! Disposes (via the driver interface) the geometry
 void
 c3geometry_dispose(
                c3geometry_p g);
 
+//! Prepares a geometry. 
+/*!
+ * The prepare phase is called only when the container object is 'dirty'
+ * for example if it's projection has changed.
+ * The prepare call is responsible for reprojecting the geometry and that
+ * sort of things
+ */
 void
 c3geometry_prepare(
                c3geometry_p g );
+
+//! Draw the geometry
+/*
+ * Called when drawing the context. Typicaly this calls the geometry 
+ * driver, which in turn will call the 'context' draw method, and the 
+ * application to draw this particular geometry
+ */
 void
 c3geometry_draw(
                c3geometry_p g );
 
+
 //! allocate (if not there) and return a custom driver for this geometry
+/*!
+ * Geometries come with a default, read only driver stack.. It is a constant
+ * global to save memory for each of the 'generic' object.
+ * This call will duplicate that stack and allocate (if not there) a read/write
+ * empty driver that the application can use to put their own, per object,
+ * callback. For example you can add your own prepare() or draw() function
+ * and have it called first
+ */
 struct c3driver_geometry_t *
 c3geometry_get_custom(
                c3geometry_p g );