FM / doc

/srv/osrm/osrm-backend/third_party/vtzero/doc/

/srv/osrm/osrm-backend/third_party/vtzero/doc

Name	Size	Mode	Actions
advanced.md	5360	0644	edit dl rm
CMakeLists.txt	1270	0644	edit dl rm
doc.md	433	0644	edit dl rm
Doxyfile.in	102981	0644	edit dl rm
reading.md	16212	0644	edit dl rm
tutorial.md	4342	0644	edit dl rm
writing.md	20845	0644	edit dl rm

Edit: /srv/osrm/osrm-backend/third_party/vtzero/doc/tutorial.md (4342B)

# Vtzero Tutorial

The vtzero header-only library is used to read and write vector tile data
as specified in the [Mapbox Vector Tile
Specification](https://github.com/mapbox/vector-tile-spec). This document
assumes that you are familiar with that specification.

## Overview

The library has basically two parts: The part concerned with decoding existing
vector tiles and the part concerned with creating new vector tiles. You can
use either one without knowing much about the other side, but it is, of course
also possible to read parts of a vector tile and stick it into a new one.

Vtzero is trying to do as little work as possible while still giving you a
reasonably easy to use interface. This means that it will, as much as feasible,
decode the different parts of a vector tile only when you ask for them. Most
importantly it will try to avoid memory allocation and it will not copy data
around unnecessarily but work with references instead.

On the writing side it means that you have to call the API in a specific order
when adding more data to a vector tile. This allows vtzero to avoid multiple
copies of the data.

## Basic types

Vtzero contains several basic small (value) types such as `GeomType`,
`property_value_type`, `index_value`, `index_value_pair`, and `point` which
hold basic values in a type-safe way. Most of them are defined in `types.hpp`
(`point` is in `geometry.hpp`).

Sometimes it is useful to be able to print the values of those types, for
instance when debugging. For this overloads of `operator<<` on `basic_ostream`
are available in `vtzero/output.hpp`. Include this file and you can use the
usual `std::cout << some_value;` to print those values.

## Use of asserts and exceptions

The vtzero library uses a lot of asserts to help you use it correctly. It is
recommended you use debug builds while developing your code, because you'll
get asserts from vtzero telling you when you use it in a wrong way. This is
especially important when writing tiles using the builder classes, because
their methods have to be called in a certain order that might not always be
obvious but is checked by the asserts.

Exceptions, on the other hand, are used when errors occur during the normal run
of vtzero. This is especially important on the reading side when vtzero makes
every effort to handle any kind of input, even if the input data is corrupt
in some way. (Vtzero can't detect all problems though, your code still has to
do its own checking, see the [advanced topics](advanced.md) for some more
information.)

Many vtzero functions can throw exceptions. Most of them fall into these
categories:

* If the underlying protocol buffers data has some kind of problem, you'll
  get an exception from the [protozero
  library](https://github.com/mapbox/protozero/blob/master/doc/tutorial.md#asserts-and-exceptions-in-the-protozero-library).
  They are all derived from `protozero::exception`.
* If the protocol buffers data is okay, but the vector tile data is invalid
  in some way, you'll get an exception from the vtzero library.
* If any memory allocation failed, you'll get a `std::bad_alloc` exception.

All the exceptions thrown directly by the vtzero library are derived from
`vtzero::exception`. These exceptions are:

* A `format_exception` is thrown when vector tile encoding isn't valid
  according to the vector tile specification.
* A `geometry_exception` is thrown when a geometry encoding isn't valid
  according to the vector tile specification.
* A `type_exception` is thrown when a property value is accessed using the
  wrong type.
* A `version_exception` is thrown when an unknown version number is found in
  the layer. Currently vtzero only supports version 1 and 2.
* An `out_of_range_exception` is thrown when an index into the key or value
  table in a layer is out of range. This can only happen if the tile data is
  invalid.

## Include files

Usually you only directly include the following files:

* When reading: `<vtzero/vector_tile.hpp>`
* When writing: `<vtzero/builder.hpp>`
* If you need any of the special indexes: `<vtzero/index.hpp>`
* If you want overloads of `operator<<` for basic types: `<vtzero/output.hpp>`
* If you need the version: `<vtzero/version.hpp>`

## Reading and writing vector tiles

* [Reading vector tiles](reading.md)
* [Writing vector tiles](writing.md)

cmd: