From: Andy Spencer Date: Mon, 8 Feb 2010 22:30:11 +0000 (+0000) Subject: Document GisTile X-Git-Tag: v0.4~54 X-Git-Url: http://pileus.org/git/?p=grits;a=commitdiff_plain;h=9bdbbfd22cc893880cd5f7671917acf15f5e82e5 Document GisTile --- diff --git a/src/objects/gis-tile.c b/src/objects/gis-tile.c index 5b4b767..fe3ff6e 100644 --- a/src/objects/gis-tile.c +++ b/src/objects/gis-tile.c @@ -15,6 +15,23 @@ * along with this program. If not, see . */ +/** + * 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 #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) diff --git a/src/objects/gis-tile.h b/src/objects/gis-tile.h index 06ce337..98052c6 100644 --- a/src/objects/gis-tile.h +++ b/src/objects/gis-tile.h @@ -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++)