GritsTile

GritsTile — Latitude/longitude overlays

Synopsis

struct              GritsTile;
struct              GritsTileClass;
void                (*GritsTileFreeFunc)                (GritsTile *tile,
                                                         gpointer user_data);
void                (*GritsTileLoadFunc)                (GritsTile *tile,
                                                         gpointer user_data);
GritsTile *         grits_tile_find                     (GritsTile *root,
                                                         gdouble lat,
                                                         gdouble lon);
#define             grits_tile_foreach                  (parent,
                                                         child)
#define             grits_tile_foreach_index            (parent,
                                                         x,
                                                         y)
void                grits_tile_free                     (GritsTile *root,
                                                         GritsTileFreeFunc free_func,
                                                         gpointer user_data);
GritsTile *         grits_tile_gc                       (GritsTile *root,
                                                         time_t atime,
                                                         GritsTileFreeFunc free_func,
                                                         gpointer user_data);
gchar *             grits_tile_get_path                 (GritsTile *child);
gboolean            grits_tile_load_file                (GritsTile *tile,
                                                         const gchar *file);
gboolean            grits_tile_load_pixbuf              (GritsTile *tile,
                                                         GdkPixbuf *pixbuf);
gboolean            grits_tile_load_pixels              (GritsTile *tile,
                                                         guchar *pixels,
                                                         gint width,
                                                         gint height,
                                                         gint channels);
GritsTile *         grits_tile_new                      (GritsTile *parent,
                                                         gdouble n,
                                                         gdouble s,
                                                         gdouble e,
                                                         gdouble w);
void                grits_tile_update                   (GritsTile *root,
                                                         GritsPoint *eye,
                                                         gdouble res,
                                                         gint width,
                                                         gint height,
                                                         GritsTileLoadFunc load_func,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----GritsObject
         +----GritsTile

Description

Each GritsTile corresponds to a latitude/longitude box on the surface of the earth. When drawn, the GritsTile renders an images associated with it to the surface of the earth. This is primarily used to draw ground overlays.

Each GritsTile 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 GritsTile has a data filed which must be set by the user in order for the tile to be drawn. When used with GritsOpenGL the data must be an integer representing the OpenGL texture to use when drawing the tile.

Details

struct GritsTile

struct GritsTile;


struct GritsTileClass

struct GritsTileClass {
	GritsObjectClass parent_class;
};


GritsTileFreeFunc ()

void                (*GritsTileFreeFunc)                (GritsTile *tile,
                                                         gpointer user_data);

Used to free the image data associated with a tile

tile :

the tile to free

user_data :

data paseed to the function

GritsTileLoadFunc ()

void                (*GritsTileLoadFunc)                (GritsTile *tile,
                                                         gpointer user_data);

Used to load the image data associated with a tile. For GritsOpenGL, this function should store the OpenGL texture number in the tiles data field.

tile :

the tile to load

user_data :

data paseed to the function

grits_tile_find ()

GritsTile *         grits_tile_find                     (GritsTile *root,
                                                         gdouble lat,
                                                         gdouble lon);

Locate the subtile with the highest resolution which contains the given lat/lon point.

root :

the root tile to search from

lat :

target latitude

lon :

target longitude

Returns :

the child tile

grits_tile_foreach()

#define             grits_tile_foreach(parent, child)

Iterate over each imediate subtile of parent.

parent :

the GritsTile to iterate over

child :

a pointer to a GritsTile to store the current subtile

grits_tile_foreach_index()

#define             grits_tile_foreach_index(parent, x, y)

Iterate over each imediate subtile of parent.

parent :

the GritsTile 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

grits_tile_free ()

void                grits_tile_free                     (GritsTile *root,
                                                         GritsTileFreeFunc free_func,
                                                         gpointer user_data);

Recursively free a tile and all it's children.

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

grits_tile_gc ()

GritsTile *         grits_tile_gc                       (GritsTile *root,
                                                         time_t atime,
                                                         GritsTileFreeFunc free_func,
                                                         gpointer user_data);

Garbage collect old tiles. This removes and deallocate tiles that have not been used since before atime.

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

Returns :

a pointer to the original tile, or NULL if it was garbage collected

grits_tile_get_path ()

gchar *             grits_tile_get_path                 (GritsTile *child);

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.

child :

the tile to generate a path for

Returns :

the path representing the tiles's location

grits_tile_load_file ()

gboolean            grits_tile_load_file                (GritsTile *tile,
                                                         const gchar *file);

Load tile data from an image file This function is thread safe and my be called from outside the main thread.

tile :

the tile to load data into

file :

path to an image file to load

Returns :

TRUE if the image was loaded successfully

grits_tile_load_pixbuf ()

gboolean            grits_tile_load_pixbuf              (GritsTile *tile,
                                                         GdkPixbuf *pixbuf);


grits_tile_load_pixels ()

gboolean            grits_tile_load_pixels              (GritsTile *tile,
                                                         guchar *pixels,
                                                         gint width,
                                                         gint height,
                                                         gint channels);

Load tile data from an in memory pixel buffer.

This function is thread safe and my be called from outside the main thread.

Ownership of the pixel buffer is passed to the tile, it should not be freed or modified after calling this function.

tile :

the tile to load data into

pixels :

buffered pixel data

width :

width of the pixel buffer (in pixels)

height :

height of the pixel buffer (in pixels)

Returns :

TRUE if the image was loaded successfully

grits_tile_new ()

GritsTile *         grits_tile_new                      (GritsTile *parent,
                                                         gdouble n,
                                                         gdouble s,
                                                         gdouble e,
                                                         gdouble w);

Create a tile associated with a particular latitude/longitude box.

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

Returns :

the new GritsTile

grits_tile_update ()

void                grits_tile_update                   (GritsTile *root,
                                                         GritsPoint *eye,
                                                         gdouble res,
                                                         gint width,
                                                         gint height,
                                                         GritsTileLoadFunc load_func,
                                                         gpointer user_data);

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.

root :

the root tile to split

eye :

the point the tile is viewed from, for calculating distances

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

load_func :

function used to load the image when a new tile is created

user_data :

user data to past to the load function