1// Copyright (C) 2017 The Qt Company Ltd.
2// Copyright (C) 2017 Mapbox, Inc.
3// Copyright (C) 2014 Canonical Ltd.
4// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
8\page location-plugin-mapboxgl.html
9\title Qt Location Mapbox GL Plugin
10\ingroup QtLocation-plugins
12\brief Uses Mapbox GL for location services.
16This geo services plugin allows applications to access
17\l {http://mapbox.com}{Mapbox} mapping services using the Qt Location API.
18The use of these services is governed by the \l {https://www.mapbox.com/tos}{Mapbox terms of service}.
20This plugin differs from the \l {http://doc.qt.io/qt-5/location-plugin-mapbox.html}{Mapbox} plugin because it uses
21the \l {https://github.com/mapbox/mapbox-gl-native/} {Mapbox GL map engine} for rendering both raster tiles and \l
22{https://www.mapbox.com/vector-tiles} {vector tiles} in real-time. The benefits are: text staying upright, font
23antialiasing, labels flowing between zoom levels, smooth pan, tilt, rotation and continuous zoom.
25The appearance and behavior of vector maps can be customized by creating custom map styles. This can be
26done with tools like \l {https://www.mapbox.com/studio} {Mapbox Studio}.
28The Mapbox GL geo services plugin can be loaded by using the plugin key "mapboxgl".
30Both Mapbox geo services plugins require an access token to access map styles
31and tiles hosted by Mapbox. To create a Mapbox account visit \l{https://www.mapbox.com/pricing}.
33\b {Note:} the API for this plugin is introduced in Qt 5.9 as \e {technology preview}.
35\section1 Platform Support
37Qt Location Mapbox GL Plugin has the following support for platforms:
40 \li Microsoft Windows (win32) - Supported, requires MinGW 5.0+
41 \li Linux X11 - Supported, requires GCC 4.9+
43 \li Android - Supported
44 \li Embedded Linux - Supported, requires GCC 4.9+
46 \li WinRT - Not supported
51\section2 Optional plugin parameters
53The following table lists optional parameters that can be passed to the Mapbox plugin.
60 \li mapboxgl.access_token
61 \li \l{https://www.mapbox.com/help/define-access-token}{Access token} provided by Mapbox.
62 The token can also be specified using the environment variable \c{MAPBOX_ACCESS_TOKEN}, but if also
63 set using a plugin parameter, then this last one will have the precedence over the environment variable.
64 When not set, a development token will be used by default. The development token is subject to the Mapbox
65 \l{https://www.mapbox.com/tos}{Terms of Services} and must not be used in production. This property has
66 no effect on styles hosted outside the Mapbox servers.
68 \li mapboxgl.api_base_url
69 \li Set a custom API base URL. When not set, the URL defaults to \l{https://api.mapbox.com}.
70 This parameter is ignored if the the \b mapboxgl.china property is set.
73 \li Use Mapbox China API base URLs and styles.
74 Please notice that Mapbox China requires a specific access token. Contact \l
75 {https://www.mapbox.com/contact/sales/} {Mapbox sales} for more information.
77 \li mapboxgl.mapping.additional_style_urls
78 \li Additional, comma separated, Mapbox \l{https://www.mapbox.com/help/define-style-url}
79 {style URLs} to be added to the available style URLs. Additional styles will be prepended to
80 the \l[QML]{QtLocation::Map::}{supportedMapTypes} property of the \l{QtLocation::Map}{Map} item.
82 \li mapboxgl.mapping.cache.directory
83 \li Absolute path to map tile cache directory used as network disk cache.
85 The default place for the cache is the \c{QtLocation/mapboxgl} subdirectory in the location returned by
86 QStandardPaths::writableLocation(), called with QStandardPaths::GenericCacheLocation as a parameter.
87 On systems that have no concept of a shared cache, the application-specific \l{QStandardPaths::CacheLocation}
90 This is an \l {https://www.mapbox.com/help/mobile-offline/#ambient-caching} {ambient cache}, meaning it will
91 get populated on the fly until it reaches the size limit, and when that happens, it will evict the least used
94 This cache can also be used for storing \l {https://www.mapbox.com/help/mobile-offline}{offline tiles},
95 but the offline database must be populated using the \l {https://github.com/mapbox/mapbox-gl-native/blob/master/bin/offline.cpp}
96 {offline tool}. The offline database will work alongside with the ambient cache in the same file.
97 Make sure to comply with Mapbox Terms of Service before creating an offline database.
99 \b {Note:} The map tile cache file name must be "mapboxgl.db". When using the offline tool, the default
100 output is "offline.db". For using the generated output from the offline tool, you must move that to the
101 proper directory, and rename it as "mapboxgl.db". The offline tool also provides the "--output"
102 parameter for specifying the name of the generated output.
105 \li mapboxgl.mapping.cache.memory
106 \li Whether or not the cache should be in-memory only. Valid values are \b true and \b false. The default
107 value is \b false. When set to \b true, the disk cache is never created. The ambient cache will work in-memory,
108 but the offline database cannot be used with this option enabled.
110 \li mapboxgl.mapping.cache.size
111 \li Cache size for map resources in bytes.
112 The default size of this cache is 50 MiB.
113 Make sure to comply with Mapbox Terms of Service before increasing this value.
115 \li mapboxgl.mapping.use_fbo
116 \li Sets whether to use a framebuffer object to render Mapbox GL Native.
117 Valid values are \b true and \b false. The default value is \b true. When
118 set to \b false, the map is rendered issuing OpenGL commands directly,
119 through a QSGRenderNode, to improve the rendering performance. This mode is
120 experimental, and it does not support QQuickItem transformations nor stencil
121 clipping. It might be also produce rendering artifacts e.g. when adding it
122 inside a \l{QtQuick::Flipable}{Flipable} item.
124 \li mapboxgl.mapping.items.insert_before
125 \li Some map items such as \l{QtLocation::MapPolyline}{MapPolyline},
126 \l{QtLocation::MapPolygon}{MapPolygon} and \l{QtLocation::MapRectangle}{MapRectangle}
127 will be rendered after the topmost \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#layers}{layer}
128 of the style. With this parameter set, the map items will be rendered \b before the layer ID
129 specified, unless the layer is not present on the current style, which will fallback
130 to the default behavior. This parameter can be used to display route lines under labels.
133\section2 Optional map parameters
135The \l{QtLocation::Map}{Map} item using this plugin, can also be customized using \l{QtLocation::DynamicParameter}{DynamicParameters},
136allowing runtime changes to the map style and data.
138Examples of what can be currently controlled using \l{QtLocation::DynamicParameter}{DynamicParameter} are:
141 \li Hide and show parts of the map, like roads and buildings.
142 \li Change paint properties like color and opacity of various parts of the map.
143 \li Change layout properties like thickness and line joints.
144 \li Add data to the map.
145 \li Add sprites to the map.
148With the exception of extrusion and data driven style properties, every property described at the
149\l {https://www.mapbox.com/mapbox-gl-js/style-spec/}{Mapbox Style Specification} can be changed at runtime.
151The \l{QtLocation::DynamicParameter}{DynamicParameters}, used to control the style of the map at runtime, always
152have a \b type property, followed by user defined properties that try to match the
153\l {https://www.mapbox.com/mapbox-gl-js/style-spec/}{Mapbox Style Specification} naming as much as possible,
154replacing the dash with camel case for technical reasons (i.e. \b line-cap will be translated to \b lineCap).
162 \li A style data \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#sources}{source}. When using a source
163 of \b sourceType \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-geojson}{geojson}, the
164 \b data property can be both inlined or sourced from qrc. Supported source types are: \b vector, \b raster,
165 \b raster-dem, \b image and \b geojson.
169 \li Adds a new \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#layers}{style layer} to the map. On a Mapbox GL map,
170 layers are used in styles for adding styling rules to specific subsets of data. A layer will contain a reference to the
171 data for which they are defining a style. Use the \b before attribute to insert a layer before an existing layer.
174 \li Defines how a layer will be painted. \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#layer-paint}{Paint} properties
175 can be used for changing the color and opacity of roads in the map or the land color, among other things.
178 \li Defines how a layer will be layouted. \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#layer-layout}{Layout} properties
179 can be used for setting a layer's visibility, and for defining the spacing between dashes in a dashed line, among other things.
182 \li Adds a \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#root-sprite}{sprite} to the map to be used by a style layer.
183 This property is required if any style layer uses the properties such as \b backgroundPattern, \b fillPattern, \b linePattern,
187 \li A \l {https://www.mapbox.com/mapbox-gl-js/style-spec/#types-filter}{filter} selects specific features from a layer. This can
188 be used for adding a layer from a GeoJSON source based on specific parts of the data source, like by using only the points
192\section1 Example usage
194This example adds inline GeoJSON data to the map. Simply adding a \b source is not enough to get the data
195visible. It is also necessary to create a \b layer based on this source. After the layer is added, we also need
196to style its \b paint and \b layout properties. In this case we are changing the line color to blue, and the line
197width to 8 pixels, as well as also setting round line joints and caps.
201 plugin: Plugin { name: "mapboxgl" }
203 center: QtPositioning.coordinate(60.170448, 24.942046) // Helsinki
209 property var name: "routeSource"
210 property var sourceType: "geojson"
211 property var data: '{ "type": "FeatureCollection", "features": \
212 [{ "type": "Feature", "properties": {}, "geometry": { \
213 "type": "LineString", "coordinates": [[ 24.934938848018646, \
214 60.16830257086771 ], [ 24.943315386772156, 60.16227776476442 ]]}}]}'
220 property var name: "route"
221 property var layerType: "line"
222 property var source: "routeSource"
224 // Draw under the first road label layer
225 // of the mapbox-streets style.
226 property var before: "road-label-small"
232 property var layer: "route"
233 property var lineColor: "blue"
234 property var lineWidth: 8.0
240 property var layer: "route"
241 property var lineJoin: "round"
242 property var lineCap: "round"
247Note that the order we add the parameters is important, because there is dependency between the
248parameters. Adding a layer before adding a source will create an invalid layer, same goes for
249adding a paint property for a layer that doesn't exist.
251Paint and layout properties can also be used for styling existing layers of the current style, and
252not only layers created at runtime. \l {https://www.mapbox.com/studio/}{Mapbox Studio} can be used
253for inspecting layers of a given style.