ChamplainMapSource

## ChamplainMapSource ChamplainMapSource — A base class for map sources |

## Synopsis

    struct              ChamplainMapSource;
    enum                ChamplainMapProjection;
    const gchar *       champlain_map_source_get_id         (ChamplainMapSource *map_source);
    const gchar *       champlain_map_source_get_name       (ChamplainMapSource *map_source);
    const gchar *       champlain_map_source_get_license    (ChamplainMapSource *map_source);
    const gchar *       champlain_map_source_get_license_uri
                                                            (ChamplainMapSource *map_source);
    guint               champlain_map_source_get_min_zoom_level
                                                            (ChamplainMapSource *map_source);
    guint               champlain_map_source_get_max_zoom_level
                                                            (ChamplainMapSource *map_source);
    guint               champlain_map_source_get_tile_size  (ChamplainMapSource *map_source);
    ChamplainMapProjection  champlain_map_source_get_projection
                                                            (ChamplainMapSource *map_source);
    guint               champlain_map_source_get_x          (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble longitude);
    guint               champlain_map_source_get_y          (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble latitude);
    gdouble             champlain_map_source_get_longitude  (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             guint x);
    gdouble             champlain_map_source_get_latitude   (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             guint y);
    guint               champlain_map_source_get_row_count  (ChamplainMapSource *map_source,
                                                             guint zoom_level);
    guint               champlain_map_source_get_column_count
                                                            (ChamplainMapSource *map_source,
                                                             guint zoom_level);
    gdouble             champlain_map_source_get_meters_per_pixel
                                                            (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble latitude,
                                                             gdouble longitude);
    void                champlain_map_source_fill_tile      (ChamplainMapSource *map_source,
                                                             ChamplainTile *tile);
    ChamplainMapSource * champlain_map_source_get_next_source
                                                            (ChamplainMapSource *map_source);
    void                champlain_map_source_set_next_source
                                                            (ChamplainMapSource *map_source,
                                                             ChamplainMapSource *next_source);
    ChamplainRenderer * champlain_map_source_get_renderer   (ChamplainMapSource *map_source);
    void                champlain_map_source_set_renderer   (ChamplainMapSource *map_source,
                                                             ChamplainRenderer *renderer);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ChamplainMapSource
                   +----ChamplainTileCache
                   +----ChamplainTileSource
                   +----ChamplainMapSourceChain

## Properties

      "next-source"              ChamplainMapSource*   : Read / Write
      "renderer"                 ChamplainRenderer*    : Read / Write

## Description

ChamplainTile objects come from map sources which are represented by ChamplainMapSource. This is should be considered an abstract type as it does nothing of interest.

When loading new tiles, ChamplainView calls `champlain_map_source_fill_tile()` on the current ChamplainMapSource passing it a ChamplainTile to be filled with the image.

Apart from being a base class of all map sources, ChamplainMapSource also supports cooperation of multiple map sources by arranging them into chains. Every map source has the "next-source" property that determines the next map source in the chain. When a function of a ChamplainMapSource object is invoked, the map source may decide to delegate the work to the next map source in the chain by invoking the same function on it.

To undertand the concept of chains, consider for instance a chain consisting of ChamplainFileCache whose next source is ChamplainNetworkTileSource whose next source is an error tile source created with `champlain_map_source_factory_create_error_source()`. When `champlain_map_source_fill_tile()` is called on the first object of the chain, ChamplainFileCache, the cache checks whether it contains the requested tile in its database. If it does, it returns the tile; otherwise, it calls `champlain_map_source_fill_tile()` on the next source in the chain (ChamplainNetworkTileSource). The network tile source loads the tile from the network. When successful, it returns the tile; otherwise it requests the tile from the next source in the chain (error tile source). The error tile source always generates an error tile, no matter what its next source is.

## Details

### struct ChamplainMapSource

    struct ChamplainMapSource;

### enum ChamplainMapProjection

    typedef enum
    {
      CHAMPLAIN_MAP_PROJECTION_MERCATOR
    } ChamplainMapProjection;

Projections supported by the library.

`CHAMPLAIN_MAP_PROJECTION_MERCATOR` | Currently the only supported projection

### champlain_map_source_get_id ()

    const gchar *       champlain_map_source_get_id         (ChamplainMapSource *map_source);

Gets map source's id.

`map_source` : | a ChamplainMapSource
Returns : | the map source's id.

Since 0.4

### champlain_map_source_get_name ()

    const gchar *       champlain_map_source_get_name       (ChamplainMapSource *map_source);

Gets map source's name.

`map_source` : | a ChamplainMapSource
Returns : | the map source's name.

Since 0.4

### champlain_map_source_get_license ()

    const gchar *       champlain_map_source_get_license    (ChamplainMapSource *map_source);

Gets map source's license.

`map_source` : | a ChamplainMapSource
Returns : | the map source's license.

Since 0.4

### champlain_map_source_get_license_uri ()

    const gchar *       champlain_map_source_get_license_uri
                                                            (ChamplainMapSource *map_source);

Gets map source's license URI.

`map_source` : | a ChamplainMapSource
Returns : | the map source's license URI.

Since 0.4

### champlain_map_source_get_min_zoom_level ()

    guint               champlain_map_source_get_min_zoom_level
                                                            (ChamplainMapSource *map_source);

Gets map source's minimum zoom level.

`map_source` : | a ChamplainMapSource
Returns : | the miminum zoom level this map source supports

Since 0.4

### champlain_map_source_get_max_zoom_level ()

    guint               champlain_map_source_get_max_zoom_level
                                                            (ChamplainMapSource *map_source);

Gets map source's maximum zoom level.

`map_source` : | a ChamplainMapSource
Returns : | the maximum zoom level this map source supports

Since 0.4

### champlain_map_source_get_tile_size ()

    guint               champlain_map_source_get_tile_size  (ChamplainMapSource *map_source);

Gets map source's tile size.

`map_source` : | a ChamplainMapSource
Returns : | the tile's size (width and height) in pixels for this map source

Since 0.4

### champlain_map_source_get_projection ()

    ChamplainMapProjection  champlain_map_source_get_projection
                                                            (ChamplainMapSource *map_source);

Gets map source's projection.

`map_source` : | a ChamplainMapSource
Returns : | the map source's projection.

Since 0.4

### champlain_map_source_get_x ()

    guint               champlain_map_source_get_x          (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble longitude);

Gets the x position on the map using this map source's projection. (0, 0) is located at the top left.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
`longitude` : | a longitude
Returns : | the x position

Since 0.4

### champlain_map_source_get_y ()

    guint               champlain_map_source_get_y          (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble latitude);

Gets the y position on the map using this map source's projection. (0, 0) is located at the top left.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
`latitude` : | a latitude
Returns : | the y position

Since 0.4

### champlain_map_source_get_longitude ()

    gdouble             champlain_map_source_get_longitude  (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             guint x);

Gets the longitude corresponding to this x position in the map source's projection.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
`x` : | a x position
Returns : | the longitude

Since 0.4

### champlain_map_source_get_latitude ()

    gdouble             champlain_map_source_get_latitude   (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             guint y);

Gets the latitude corresponding to this y position in the map source's projection.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
`y` : | a y position
Returns : | the latitude

Since 0.4

### champlain_map_source_get_row_count ()

    guint               champlain_map_source_get_row_count  (ChamplainMapSource *map_source,
                                                             guint zoom_level);

Gets the number of tiles in a row at this zoom level for this map source.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
Returns : | the number of tiles in a row

Since 0.4

### champlain_map_source_get_column_count ()

    guint               champlain_map_source_get_column_count
                                                            (ChamplainMapSource *map_source,
                                                             guint zoom_level);

Gets the number of tiles in a column at this zoom level for this map source.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
Returns : | the number of tiles in a column

Since 0.4

### champlain_map_source_get_meters_per_pixel ()

    gdouble             champlain_map_source_get_meters_per_pixel
                                                            (ChamplainMapSource *map_source,
                                                             guint zoom_level,
                                                             gdouble latitude,
                                                             gdouble longitude);

Gets meters per pixel at the position on the map using this map source's projection.

`map_source` : | a ChamplainMapSource
`zoom_level` : | the zoom level
`latitude` : | a latitude
`longitude` : | a longitude
Returns : | the meters per pixel

Since 0.4.3

### champlain_map_source_fill_tile ()

    void                champlain_map_source_fill_tile      (ChamplainMapSource *map_source,
                                                             ChamplainTile *tile);

Fills the tile with image data (either from cache, network or rendered locally).

`map_source` : | a ChamplainMapSource
`tile` : | A ChamplainTile

Since 0.4

### champlain_map_source_get_next_source ()

    ChamplainMapSource * champlain_map_source_get_next_source
                                                            (ChamplainMapSource *map_source);

Get the next source in the chain.

`map_source` : | a ChamplainMapSource
Returns : | the next source in the chain.

Since 0.6

### champlain_map_source_set_next_source ()

    void                champlain_map_source_set_next_source
                                                            (ChamplainMapSource *map_source,
                                                             ChamplainMapSource *next_source);

Sets the next map source in the chain.

`map_source` : | a ChamplainMapSource
`next_source` : | the next ChamplainMapSource in the chain

Since 0.6

### champlain_map_source_get_renderer ()

    ChamplainRenderer * champlain_map_source_get_renderer   (ChamplainMapSource *map_source);

Get the renderer used for tiles rendering.

`map_source` : | a ChamplainMapSource
Returns : | the renderer.

Since 0.8

### champlain_map_source_set_renderer ()

    void                champlain_map_source_set_renderer   (ChamplainMapSource *map_source,
                                                             ChamplainRenderer *renderer);

Sets the renderer used for tiles rendering.

`map_source` : | a ChamplainMapSource
`renderer` : | the renderer

Since 0.8

## Property Details

### The `"next-source"` property

      "next-source"              ChamplainMapSource*   : Read / Write

Next source in the loading chain.

Since 0.6

### The `"renderer"` property

      "renderer"                 ChamplainRenderer*    : Read / Write

Renderer used for tiles rendering.

Since 0.8