## 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