]> Pileus Git - grits/blobdiff - src/roam.h
Revert "Test pure distance based errors"
[grits] / src / roam.h
index 361025e4271ab3bdd37ba81461ade4a794a4cb1c..aec4b218719800563293acf5f7dafd270b449a10 100644 (file)
@@ -26,9 +26,28 @@ typedef struct _RoamPoint    RoamPoint;
 typedef struct _RoamTriangle RoamTriangle;
 typedef struct _RoamDiamond  RoamDiamond;
 typedef struct _RoamSphere   RoamSphere;
+/**
+ * RoamHeightFunc:
+ * @lat:       the latitude
+ * @lon:       the longitude
+ * @user_data: user data passed to the function
+ *
+ * See #GisHeightFunc
+ *
+ * Returns: the elevation
+ */
 typedef gdouble (*RoamHeightFunc)(gdouble lat, gdouble lon, gpointer user_data);
 
 /* Misc */
+/**
+ * RoamView:
+ * @model:   model view matrix
+ * @proj:    projection matrix
+ * @view:    viewport matrix
+ * @version: version
+ *
+ * Stores projection matrices
+ */
 struct _RoamView {
        gdouble model[16];
        gdouble proj[16];
@@ -39,6 +58,14 @@ struct _RoamView {
 /*************
  * RoamPoint *
  *************/
+/**
+ * RoamPoint:
+ *
+ * Points are used as vertices for triangles. A single point my be shared among
+ * several triangles in order to conceive space and avoid recalculating
+ * projections. Points also store a lot of cached data. The normal vertex normal
+ * is the averaged surface normal of each associated triangle.
+ */
 struct _RoamPoint {
        /*< private >*/
        gdouble  x, y, z;    /* Model coordinates */
@@ -64,6 +91,18 @@ void roam_point_update_projection(RoamPoint *point, RoamView *view);
 /****************
  * RoamTriangle *
  ****************/
+/**
+ * RoamTriangle:
+ *
+ * Triangles are one of the key datatypes in ROAM. The surface is made up of
+ * triangles. Each triangle has an associated "error". When the surface is being
+ * updated after the view changes, each triangles error is updated. Afterwards
+ * the triangles with the most error are split int to triangles, each with a
+ * lower error than the original.
+ *
+ * Triangles store a lot of data about their location in the mesh so that they
+ * can be split and merged (unsplit) without having to recreate the mesh.
+ */
 struct _RoamTriangle {
        /*< private >*/
        /* Left, middle and right vertices */
@@ -72,17 +111,18 @@ struct _RoamTriangle {
        /* Left, base, and right neighbor triangles */
        struct { RoamTriangle *l,*b,*r; } t;
 
-       RoamPoint *split;     /* Split point */
-       RoamDiamond *parent;  /* Parent diamond */
-       double norm[3];       /* Surface normal */
-       double error;         /* Screen space error */
+       RoamPoint *split;      /* Split point */
+       RoamDiamond *parent;   /* Parent diamond */
+       RoamTriangle *kids[2]; /* Higher-res triangles */
+       double norm[3];        /* Surface normal */
+       double error;          /* Screen space error */
        GPQueueHandle handle;
 
        /* For get_intersect */
        struct { gdouble n,s,e,w; } edge;
-       RoamTriangle *kids[2];
 };
-RoamTriangle *roam_triangle_new(RoamPoint *l, RoamPoint *m, RoamPoint *r);
+RoamTriangle *roam_triangle_new(RoamPoint *l, RoamPoint *m, RoamPoint *r,
+               RoamDiamond *parent);
 void roam_triangle_free(RoamTriangle *triangle);
 void roam_triangle_add(RoamTriangle *triangle,
                RoamTriangle *left, RoamTriangle *base, RoamTriangle *right,
@@ -96,18 +136,25 @@ void roam_triangle_draw_normal(RoamTriangle *triangle);
 /***************
  * RoamDiamond *
  ***************/
+/**
+ * RoamDiamond:
+ *
+ * When two adjacent triangles are split, they, along with the four new child
+ * triangles, are added to a diamond which keeps track of them.
+ *
+ * Like triangles, diamond have an error associated with it. However, when a
+ * diamonds error is small enough it is "merged". That is, the diamond along
+ * with the child triangles is removed and the original two triangles triangles
+ * are added back into the mesh.
+ */
 struct _RoamDiamond {
        /*< private >*/
-       RoamTriangle *kids[4];    /* Child triangles */
        RoamTriangle *parents[2]; /* Parent triangles */
        double error;             /* Screen space error */
        gboolean active;          /* For internal use */
        GPQueueHandle handle;
 };
-RoamDiamond *roam_diamond_new(
-               RoamTriangle *parent0, RoamTriangle *parent1,
-               RoamTriangle *kid0, RoamTriangle *kid1,
-               RoamTriangle *kid2, RoamTriangle *kid3);
+RoamDiamond *roam_diamond_new(RoamTriangle *parent0, RoamTriangle *parent1);
 void roam_diamond_add(RoamDiamond *diamond, RoamSphere *sphere);
 void roam_diamond_remove(RoamDiamond *diamond, RoamSphere *sphere);
 void roam_diamond_merge(RoamDiamond *diamond, RoamSphere *sphere);
@@ -116,6 +163,14 @@ void roam_diamond_update_errors(RoamDiamond *diamond, RoamSphere *sphere);
 /**************
  * RoamSphere *
  **************/
+/**
+ * RoamSphere:
+ *
+ * The sphere keeps track of the triangles and diamonds in the mesh. 
+ *
+ * Originally the sphere consists of only 8 triangles forming a octahedron.
+ * These triangles are quickly split to create a smoother sphere.
+ */
 struct _RoamSphere {
        /*< private >*/
        GPQueue *triangles; /* List of triangles */