Document GisTile
authorAndy Spencer <andy753421@gmail.com>
Mon, 8 Feb 2010 22:30:11 +0000 (22:30 +0000)
committerAndy Spencer <andy753421@gmail.com>
Mon, 8 Feb 2010 22:30:11 +0000 (22:30 +0000)
src/objects/gis-tile.c
src/objects/gis-tile.h

index 5b4b767..fe3ff6e 100644 (file)
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gis-tile
+ * @short_description: Latitude/longitude overlays
+ *
+ * Each #GisTile corresponds to a latitude/longitude box on the surface of the
+ * earth. When drawn, the #GisTile renders an images associated with it to the
+ * surface of the earth. This is primarily used to draw ground overlays.
+ *
+ * Each GisTile can be split into subtiles in order to draw higher resolution
+ * overlays. Pointers to subtitles are stored in the parent tile and a parent
+ * pointer is stored in each child.
+ *
+ * Each #GisTile has a data filed which must be set by the user in order for
+ * the tile to be drawn. When used with GisOpenGL the data must be an integer
+ * representing the OpenGL texture to use when drawing the tile.
+ */
+
 #include <config.h>
 #include "gis-util.h"
 #include "gis-tile.h"
@@ -24,6 +41,18 @@ gchar *gis_tile_path_table[2][2] = {
        {"10.", "11."},
 };
 
+/**
+ * gis_tile_new:
+ * @parent: the parent for the tile, or NULL
+ * @n:      the northern border of the tile
+ * @s:      the southern border of the tile
+ * @e:      the eastern border of the tile
+ * @w:      the western border of the tile
+ *
+ * Create a tile associated with a particular latitude/longitude box.
+ *
+ * Returns: the new #GisTile
+ */
 GisTile *gis_tile_new(GisTile *parent,
        gdouble n, gdouble s, gdouble e, gdouble w)
 {
@@ -37,6 +66,17 @@ GisTile *gis_tile_new(GisTile *parent,
        return tile;
 }
 
+/**
+ * gis_tile_get_path:
+ * @child: the tile to generate a path for
+ *
+ * Generate a string representation of a tiles location in a group of nested
+ * tiles. The string returned consists of groups of two digits separated by a
+ * delimiter. Each group of digits the tiles location with respect to it's
+ * parent tile.
+ *
+ * Returns: the path representing the tiles's location
+ */
 gchar *gis_tile_get_path(GisTile *child)
 {
        /* This could be easily cached if necessary */
@@ -96,6 +136,24 @@ static gboolean _gis_tile_needs_split(GisTile *tile,
        return view_res < tile_res;
 }
 
+/**
+ * gis_tile_update:
+ * @root:      the root tile to split
+ * @res:       a maximum resolution in meters per pixel to split tiles to
+ * @width:     width in pixels of the image associated with the tile
+ * @height:    height in pixels of the image associated with the tile
+ * @lat:       latitude of the eye point
+ * @lon:       longitude of the eye point
+ * @elev:      elevation of the eye point
+ * @load_func: function used to load the image when a new tile is created
+ * @user_data: user data to past to the load function
+ *
+ * Recursively split a tile into children of appropriate detail. The resolution
+ * of the tile in pixels per meter is compared to the resolution which the tile
+ * is being drawn at on the screen. If the screen resolution is insufficient
+ * the tile is recursively subdivided until a sufficient resolution is
+ * achieved.
+ */
 void gis_tile_update(GisTile *root,
                gdouble res, gint width, gint height,
                gdouble lat, gdouble lon, gdouble elev,
@@ -126,6 +184,17 @@ void gis_tile_update(GisTile *root,
        }
 }
 
+/**
+ * gis_tile_find:
+ * @root: the root tile to search from
+ * @lat:  target latitude
+ * @lon:  target longitude
+ *
+ * Locate the subtile with the highest resolution which contains the given
+ * lat/lon point.
+ * 
+ * Returns: the child tile
+ */
 GisTile *gis_tile_find(GisTile *root, gdouble lat, gdouble lon)
 {
        gint    rows = G_N_ELEMENTS(root->children);
@@ -155,6 +224,18 @@ GisTile *gis_tile_find(GisTile *root, gdouble lat, gdouble lon)
                return root;
 }
 
+/**
+ * gis_tile_gc:
+ * @root:      the root tile to start garbage collection at
+ * @atime:     most recent time at which tiles will be kept
+ * @free_func: function used to free the image when a new tile is collected
+ * @user_data: user data to past to the free function
+ *
+ * Garbage collect old tiles. This removes and deallocate tiles that have not
+ * been used since before @atime.
+ *
+ * Returns: a pointer to the original tile, or NULL if it was garbage collected
+ */
 GisTile *gis_tile_gc(GisTile *root, time_t atime,
                GisTileFreeFunc free_func, gpointer user_data)
 {
@@ -180,6 +261,14 @@ GisTile *gis_tile_gc(GisTile *root, time_t atime,
 }
 
 /* Use GObject for this */
+/**
+ * gis_tile_free:
+ * @root:      the root tile to free
+ * @free_func: function used to free the image when a new tile is collected
+ * @user_data: user data to past to the free function
+ *
+ * Recursively free a tile and all it's children.
+ */
 void gis_tile_free(GisTile *root, GisTileFreeFunc free_func, gpointer user_data)
 {
        if (!root)
index 06ce337..98052c6 100644 (file)
@@ -55,15 +55,46 @@ struct _GisTileClass {
        GisObjectClass parent_class;
 };
 
+/**
+ * GisTileLoadFunc:
+ * @tile:      the tile to load
+ * @user_data: data paseed to the function
+ *
+ * Used to load the image data associated with a tile. For GisOpenGL, this
+ * function should store the OpenGL texture number in the tiles data field.
+ */
 typedef void (*GisTileLoadFunc)(GisTile *tile, gpointer user_data);
+
+/**
+ * GisTileFreeFunc:
+ * @tile:      the tile to free
+ * @user_data: data paseed to the function
+ *
+ * Used to free the image data associated with a tile
+ */
 typedef void (*GisTileFreeFunc)(GisTile *tile, gpointer user_data);
 
 /* Forech functions */
+/**
+ * gis_tile_foreach:
+ * @parent: the #GisTile to iterate over
+ * @child:  a pointer to a #GisTile to store the current subtile 
+ *
+ * Iterate over each imediate subtile of @parent. 
+ */
 #define gis_tile_foreach(parent, child) \
        for (int _x = 0; _x < G_N_ELEMENTS(parent->children); _x++) \
        for (int _y = 0; child = parent->children[_x][_y], \
                _y < G_N_ELEMENTS(parent->children[_x]); _y++)
 
+/**
+ * gis_tile_foreach_index:
+ * @parent: the #GisTile to iterate over
+ * @x:      integer to store the x index of the current subtile
+ * @y:      integer to store the y index of the current subtile
+ *
+ * Iterate over each imediate subtile of @parent. 
+ */
 #define gis_tile_foreach_index(parent, x, y) \
        for (x = 0; x < G_N_ELEMENTS(parent->children); x++) \
        for (y = 0; y < G_N_ELEMENTS(parent->children[x]); y++)