Properties and options
SDK JS's global properties and options that you can access while initializing your map or accessing information about its status.
addProtocol
Adds a custom load resource function that will be called when using a URL that starts with a custom url schema. This will happen in the main thread, and workers might call it if they don't know how to handle the protocol. The example below will be triggered for custom:// urls defined in the sources list in the style definitions. The function passed will receive the request parameters and should return with the resulting resource, for example a pbf vector tile, non-compressed, represented as ArrayBuffer.
Example
Parameters
(AddProtocolAction)the
function to use when trying to fetch a tile specified by the customProtocol
addSourceType
Adds a custom source type, making it available for use with Map.addSource.
Parameters
(string)
The name of the source type; source definition objects use this name in the {type: ...} field.
clearPrewarmedResources
src/util/global_worker_pool.ts
Clears up resources that have previously been created by maptilersdk.prewarm().
Note that this is typically not necessary. You should only call this function
if you expect the user of your app to not return to a Map view at any point
in your application.
Example
getMaxParallelImageRequests
Gets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.
Example
Returns
number:
Number of parallel requests currently configured.
getRTLTextPluginStatus
Gets the map's RTL text plugin
status.
The status can be unavailable (i.e. not requested or removed), loading,
loaded or error.
If the status is loaded and the plugin is requested again, an error will be thrown.
Example
getWorkerCount
Gets the number of web workers instantiated on a page with GL JS maps. By default, workerCount is 1 except for Safari browser where it is set to half the number of CPU cores (capped at 3). Make sure to set this property before creating any map instances for it to have effect.
Example
Returns
number:
Number of workers currently configured.
importScriptInWorkers
Allows loading javascript code in the worker thread. Note that since this is using some very internal classes and flows it is considered experimental and can break at any point.
- Using
self.addProtocolin the worker thread - note that you might need to also register the protocol on the main thread. - Using
self.registerWorkerSource(workerSource: WorkerSource)to register a worker source, which sould come withaddSourceTypeusually - Using
self.actor.registerMessageHandlerto override some internal worker operations
Example
Parameters
Returns
Promise<void[]>
prewarm
src/util/global_worker_pool.ts
Initializes resources like WebWorkers that can be shared across maps to lower load
times in some situations. maptilersdk.workerUrl and maptilersdk.workerCount, if being
used, must be set before prewarm() is called to have an effect.
By default, the lifecycle of these resources is managed automatically, and they are
lazily initialized when a Map is first created. By invoking prewarm(), these
resources will be created ahead of time, and will not be cleared when the last Map
is removed from the page. This allows them to be re-used by new Map instances that
are created later. They can be manually cleared by calling
maptilersdk.clearPrewarmedResources(). This is only necessary if your web page remains
active but stops using maps altogether.
This is primarily useful when using GL-JS maps in a single page app, wherein a user would navigate between various views that can cause Map instances to constantly be created and destroyed.
Example
setMaxParallelImageRequests
Sets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.
Example
Parameters
setRTLTextPlugin
Sets the map's RTL text plugin. Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left.
Example
Parameters
(boolean)If
set to
true
, maplibregl will defer loading the plugin until rtl text is encountered,
rtl text will then be rendered only after the plugin finishes loading.
setWorkerCount
Sets the number of web workers instantiated on a page with GL JS maps. By default, workerCount is 1 except for Safari browser where it is set to half the number of CPU cores (capped at 3). Make sure to set this property before creating any map instances for it to have effect.
Example
Parameters
clearStorage
Clears browser storage used by this library. Using this method flushes the SDK JS tile cache that is managed by this library. Tiles may still be cached by the browser in some cases.
This API is supported on browsers where the Cache API
is supported and enabled. This includes all major browsers when pages are served over
https://, except Internet Explorer and Edge Mobile.
When called in unsupported browsers or environments (private or incognito mode), the callback will be called with an error argument.
Example
Parameters
AnimationOptions
Options common to map movement methods that involve animation, such as Map#panBy and Map#easeTo, controlling the duration and easing function of the animation. All properties are optional.
Properties
(Function):
A function taking a time in the range 0..1 and returning a number where 0 is
the initial state and 1 is the final state. Default is a bezier-curve function with
control points (0.25, 0.1) and (0.25, 1). Example:
(PointLike):
of the target center relative to real map container center at the end of animation.
(boolean):
If
true
, then the animation is considered essential and will not be affected by
prefers-reduced-motion
.
CameraOptions
Options common to Map#jumpTo, Map#easeTo, and Map#flyTo, controlling the desired location, zoom, bearing, and pitch of the camera. All properties are optional, and when a property is omitted, the current camera value for that property will remain unchanged.
Example
Properties
(number):
The desired bearing in degrees. The bearing is the compass direction that
is "up". For example,
bearing: 90
orients the map so that east is up.
(number):
The desired pitch in degrees. The pitch is the angle towards the horizon
measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance
of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon.
Increasing the pitch value is often used to display 3D objects.
(LngLatLike):
If
zoom
is specified,
around
determines the point around which the zoom is centered.
(PaddingOptions):
Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.
Related examples
PaddingOptions
Options for setting padding on calls to methods such as Map#fitBounds, Map#fitScreenCoordinates, and Map#setPadding. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be non-negative integers.
Example
Properties
(number)
(number)
(number)
(number)
Static Members
Related examples
RequestParameters
A RequestParameters object to be returned from Map.options.transformRequest callbacks.
Example
Properties
(string):
'same-origin'|'include'
Use 'include' to send cookies with cross-origin requests.
(boolean):
If true, Resource Timing API information will be collected for these transformed requests and returned in
a resourceTiming property of relevant data events.
StyleImageInterface
Interface for dynamically generated style images. This is a specification for implementers to model: it is not an exported method or class.
Images implementing this interface can be redrawn for every frame. They can be used to animate icons and patterns or make them respond to user input. Style images can implement a StyleImageInterface#render method. The method is called every frame and can be used to update the image.
Example
Methods
Properties
((Uint8Array | Uint8ClampedArray))
Properties
(number)
Optional method called when the layer has been added to the Map with Map#addImage.
Parameters
Optional method called when the icon is removed from the map with Map#removeImage. This gives the image a chance to clean up resources and event listeners.
This method is called once before every frame where the icon will be used.
The method can optionally update the image's data member with a new image.
If the method updates the image it must return true to commit the change.
If the method returns false or nothing the image is assumed to not have changed.
If updates are infrequent it maybe easier to use Map#updateImage to update the image instead of implementing this method.
Returns
boolean:
true
if this method updated the image.
false
if the image was not changed.
Properties
(number)
Related examples
CustomLayerInterface
src/style/style_layer/custom_style_layer.ts
Interface for custom style layers. This is a specification for implementers to model: it is not an exported method or class.
Custom layers allow a user to render directly into the map's GL context using the map's camera. These layers can be added between any regular layers using Map#addLayer.
Custom layers must have a unique id and must have the type of "custom".
They must implement render and may implement prerender, onAdd and
onRemove.
They can trigger rendering using Map#triggerRepaint
and they should appropriately handle Map.event:webglcontextlost and
Map.event:webglcontextrestored.
The renderingMode property controls whether the layer is treated as a "2d" or
"3d" map layer. Use:
"renderingMode": "3d"to use the depth buffer and share it with other layers"renderingMode": "2d"to add a layer with no depth. If you need to use the depth buffer for a"2d"layer you must use an offscreen framebuffer and CustomLayerInterface#prerender
Example
Methods
Optional method called when the layer has been added to the Map with Map#addLayer. This gives the layer a chance to initialize gl resources and register event listeners.
Parameters
Optional method called when the layer has been removed from the Map with Map#removeLayer. This gives the layer a chance to clean up gl resources and event listeners.
Parameters
Optional method called during a render frame to allow a layer to prepare resources or render into a texture.
The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.
Parameters
(mat4)The map's
camera matrix. It projects spherical mercator
coordinates to gl coordinates. The mercator coordinate
[0, 0]
represents the
top left corner of the mercator world and
[1, 1]
represents the bottom right corner. When
the
renderingMode
is
"3d"
, the z coordinate is conformal. A box with identical x, y, and z
lengths in mercator units would be rendered as a cube.
MercatorCoordinate
.fromLngLat
can be used to project a
LngLat
to a mercator coordinate.
Called during a render frame allowing the layer to draw into the GL context.
The layer can assume blending and depth state is set to allow the layer to properly blend and clip other layers. The layer cannot make any other assumptions about the current GL state.
If the layer needs to render to a texture, it should implement the prerender method
to do this and only use the render method for drawing directly into the main framebuffer.
The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects
colors to be provided in premultiplied alpha form where the r, g and
b values are already
multiplied by the a value. If you are unable to provide colors in premultiplied form you
may want to change the blend function to
gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
Parameters
(Array<number>)The
map's camera matrix. It projects spherical mercator
coordinates to gl coordinates. The spherical mercator coordinate
[0, 0]
represents the
top left corner of the mercator world and
[1, 1]
represents the bottom right corner. When
the
renderingMode
is
"3d"
, the z coordinate is conformal. A box with identical x, y, and z
lengths in mercator units would be rendered as a cube.
MercatorCoordinate
.fromLngLat
can be used to project a
LngLat
to a mercator coordinate.
