libchamplain Reference Manual: ChamplainMapSource

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

## Functions

const gchar * | champlain_map_source_get_id ()
const gchar * | champlain_map_source_get_name ()
const gchar * | champlain_map_source_get_license ()
const gchar * | champlain_map_source_get_license_uri ()
guint | champlain_map_source_get_min_zoom_level ()
guint | champlain_map_source_get_max_zoom_level ()
guint | champlain_map_source_get_tile_size ()
ChamplainMapProjection | champlain_map_source_get_projection ()
gdouble | champlain_map_source_get_x ()
gdouble | champlain_map_source_get_y ()
gdouble | champlain_map_source_get_longitude ()
gdouble | champlain_map_source_get_latitude ()
guint | champlain_map_source_get_row_count ()
guint | champlain_map_source_get_column_count ()
gdouble | champlain_map_source_get_meters_per_pixel ()
void | champlain_map_source_fill_tile ()
ChamplainMapSource * | champlain_map_source_get_next_source ()
void | champlain_map_source_set_next_source ()
ChamplainRenderer * | champlain_map_source_get_renderer ()
void | champlain_map_source_set_renderer ()

## Properties

ChamplainMapSource * | next-source | Read / Write
ChamplainRenderer * | renderer | Read / Write

## Types and Values

struct | ChamplainMapSource
enum | ChamplainMapProjection

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ChamplainMapSource
                ├── ChamplainTileCache
                ├── ChamplainTileSource
                ╰── ChamplainMapSourceChain

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

## Functions

### champlain_map_source_get_id ()

    const gchar *
    champlain_map_source_get_id (ChamplainMapSource *map_source);

Gets map source's id.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

map_source | a ChamplainMapSource |

#### Returns

the map source's projection.

Since 0.4

### champlain_map_source_get_x ()

    gdouble
    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.

#### Parameters

map_source | a ChamplainMapSource |
zoom_level | the zoom level |
longitude | a longitude |

#### Returns

the x position

Since 0.4

### champlain_map_source_get_y ()

    gdouble
    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.

#### Parameters

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,
                                        gdouble x);

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

#### Parameters

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,
                                       gdouble y);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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.

#### Parameters

map_source | a ChamplainMapSource |

#### Returns

the next source in the chain.

[transfer none]

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.

#### Parameters

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.

#### Parameters

map_source | a ChamplainMapSource |

#### Returns

the renderer.

[transfer none]

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.

#### Parameters

map_source | a ChamplainMapSource |
renderer | the renderer |

Since 0.8

## Types and Values

### struct ChamplainMapSource

    struct ChamplainMapSource;

The ChamplainMapSource structure contains only private data and should be accessed using the provided API

Since 0.4

### enum ChamplainMapProjection

Projections supported by the library.

#### Members

CHAMPLAIN_MAP_PROJECTION_MERCATOR | Currently the only supported projection |

## Property Details

### The `“next-source”` property

      “next-source”              ChamplainMapSource *

Next source in the loading chain.

Flags: Read / Write

Since 0.6

### The `“renderer”` property

      “renderer”                 ChamplainRenderer *

Renderer used for tiles rendering.

Flags: Read / Write

Since 0.8