Attaches the effects to a map. Nothing is visible until a knob turns an effect on.
The map to render effects over.
Optionalconfig: MapEffectsConfig
Effect knob values to apply right away.
Draws a 2D canvas layer of your own between the overlay effects, and in capture in the same place. Layers in one placement stack in the order they were added.
A layer redraws with the map. If it changes on its own, as film grain does, ask for frames with
map.mapLibreMap.triggerRepaint(). A layer needs no WebGL2 context and reads no canvas.
// A paper texture under the tint and the vignette, which then work on the paper too.
effects.addLayer({
id: 'paper',
placement: 'after-edgeBlur',
draw: (context, { width, height }) => {
context.globalAlpha = 0.25;
context.fillStyle = context.createPattern(paper, 'repeat') ?? 'transparent';
context.fillRect(0, 0, width, height);
},
});
Runs a GPU pass of your own in the effects chain, ahead of every overlay effect, and in capture as on screen. Passes run in the order they were added, within their placement.
A pass redraws with the map. If its uniforms change on their own, as in a time-driven animation,
ask for frames with map.mapLibreMap.triggerRepaint(). A pass that shifts hues runs before
the bloom's and the glare's colour keys too, so a bloom.only or glare.only scope may need a
wider bloom.onlyTolerance or glare.onlyTolerance.
Error when the pass has no id or its shader does not compile, with the compiler's log;
RangeError for an unknown placement, or for more than 15 textures or one named uSource. A
shader is checked only while there is a WebGL2 context: without one no pass runs and the plugin
warns once, and after a lost one it is checked on restore.
Replaces the whole configuration. An empty object turns everything off.
Use it, and updateConfig, for a look your code writes, such as a use case swapped in
whole: as on a map module, the type is the check, and the values are not checked again. For
values held as data, the SDK's setKnobs checks each against the catalogue and sets them by id.
Renders the current view, with its effects, into a canvas, optionally at a higher pixel ratio for print. The map is re-rendered at that ratio (never resampled), read back once every tile is drawn, and then set back to the ratio it had.
Optionaloptions: CaptureOptionsReturns the configuration, as a plain serializable copy.
Detaches the effects from the map, removes their elements and releases the WebGL context the chain holds. A page with several maps needs this, since a browser caps how many contexts it may keep alive.
Takes a layer added with addLayer off the map. An id with no layer is ignored.
Takes a pass added with addPass out of the chain. An id with no pass is ignored.
Resets every knob to its default, off for most effects.
Changes the given effects and keeps the others, one level deep as a map module's
updateConfig does: an effect you pass replaces that effect's values.
Practical post-processing for a TomTomMap, with effects computed from the rendered map's own pixels rather than its style. They therefore work on every style, survive every style release, and cannot be reproduced by editing the style at all.
Remarks
Public Preview until the plugin's 1.0.0 release.
Every effect is named by the problem it solves, and off by default:
fog.color, which follows the map's light/dark theme while unset.Effects render live as layers over the map canvas, and are composited the same way into capture, so what is captured is what was on screen. From the bottom, the layers are a WebGL2 chain that also runs your own passes from addPass, the glare and a bloom scoped with
bloom.only, an unscoped bloom as a small canvas blended inscreenmode, and the CSS overlays. Your own 2D layers from addLayer take a place among the overlays. HTML markers, popups and the map's controls sit above every effect.The effects draw on the map's
renderevent, in the same frame as the map, so the map needs nopreserveDrawingBuffer. Adding a pass, or setting a knob of bloom, the glare or the depth of field, asks the map for one frame to draw in. The CSS overlays need none.effectKnobCatalogue lists every knob as static data, the way
stylingFoundationsKnobCataloguelists the SDK's styling knobs. Each id is its path into MapEffectsConfig. The SDK'ssetKnob,setKnobs,getKnobandresetKnobset, read and unset knobs by id, as on a map module.Example