GL surfaces

GLSurfaces, part of the Landmarks 3D plugin, textures the water, land cover, built-up ground and roads of a TomTomMap with WebGL materials, and grows 3D trees on its woods, parks and meadows. Water ripples in the wind, mirrors the sky and rolls in onto open shores, forests show sunlit tree crowns, fields break into parcels and roads take on asphalt. Everything is drawn in the style’s own colours, for the season you pick. The playground below puts the surface, season, tree, sky and wind knobs on one panel, beside the map’s light:

What it textures

surfaceKinds lists them. The materials vary the style’s colour rather than replace it, so a restyle or map colours carry through to the textures.

3D trees

Trees stand on woods, parks, gardens, meadows, scrub, heaths, orchards, cemeteries and playgrounds, each as densely as that kind of ground grows them. Wild woods are the densest, parks and meadows open, and orchards stand in rows. They grow in from zoom 15, sway in the wind and cast shadows away from the sun. Their foliage takes the style’s woodland and park colours. On satellite, it takes the colours of the crowns the imagery shows under them.

• Five kinds: round-crowned broadleaf trees, conifers, bushes, slender columnar trees such as poplars and cypresses, and flat-topped umbrella trees such as stone pines. Each kind of ground and where it lies decide the mix: few conifers in the tropics and more towards the poles, umbrella trees only where it’s warm, south of about 46°, and columnar trees most in cemeteries and gardens. Each kind’s shareFactor knob makes it more or less common.
• Up a mountain: on 3D terrain, conifers take over the woods as the ground climbs, and the trees thin and shrink towards the treeline, some 1,900 m high in the Alps and lower towards the poles.
• Roads, paths, railways and streams through a wood keep the crowns off them, so they show between the trees from above. Seen tilted, the trees in front of a path still stand before it, so the map draws the path over their crowns too, as strongly as trees.tracks.intensity.

Get started

Install the plugin as the overview shows. GLSurfaces draws with Three.js, so install three for the surfaces alone too. To texture the map, create the class. It starts drawing once the map is ready:

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2
import { GLSurfaces } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
3

4
const map = new TomTomMap({ mapLibre: { container: 'map', center: [6.6323, 46.507], zoom: 14.5, pitch: 70 } });
5
const surfaces = new GLSurfaces(map);

• It draws inside the style, right after the layers it textures. Labels, bridges, buildings and every layer your app adds above them stay on top. The trees go under the labels, and under the routes, places and geometries drawn there, whichever came first. See Place the trees.
• It comes back after setStyle, in the new style’s colours. On streetSatellite, it textures the water and the roads and grows the trees, in the imagery’s colours.
• Every texture is anchored to the ground and fades its details out before they shrink below a few pixels, so it stays calm while you pan and zoom. Waves seen from afar smooth into a glitter of the sun.
• Over 3D terrain, the textures follow the raised ground and the trees stand on it.
• It needs WebGL2.
• surfaces.setVisible(false) hides it, and the map draws as it would without the plugin.
• surfaces.remove() takes the surfaces and the trees off the map for good, with the WebGL resources they hold. Call it when your app drops the surfaces but keeps the map. To show them again, create a new GLSurfaces.

Tune the surfaces

The look of the surfaces is a set of knobs, listed in glSurfacesKnobCatalogue. They follow the rules every part of the plugin follows (Set the look with knobs):

1
import { setKnob } from '@tomtom-org/maps-sdk/map';
2
import { glSurfacesKnobCatalogue } from '@tomtom-org/maps-sdk-plugin-landmarks-3d/knobs';
3

4
surfaces.updateConfig({ wind: { direction: 270, speedFactor: 2 } });         // a brisk westerly
5
setKnob(surfaces, glSurfacesKnobCatalogue, 'surfaces.roads.intensity', 0);  // flat roads, as the style draws them
6
surfaces.updateConfig({ light: { direction: 260, altitude: 12 } });          // a low evening sun
7
surfaces.resetConfig();                                                       // every knob back to its default

• Every surface sits in one part, surfaces. So updateConfig({ surfaces: { roads: { intensity: 0 } } }) also unsets the knobs you set for the water, the forest and the other surfaces. To change one surface and keep the others, use setKnob or setKnobs, as above.
• The sky the water mirrors is the map’s own sky where the style sets one. Otherwise, it’s a day sky on light styles and on streetSatellite, and a night sky on other dark ones, where the water glints in the moonlight. getKnob reports the colour in force.
• While the water, the grass or the trees from zoom 16 show and the wind blows, the map draws every display frame. To let it rest, set wind.speedFactor to 0, which holds them still. Do that too for readers who ask for less motion, with matchMedia('(prefers-reduced-motion: reduce)').

Colour them for a season

Each surface and the trees are coloured for a season, from the style’s own colours: spring, summer, autumn, winter or snow, as surfaceSeasons lists them. The season knob sets it for everything, and a part’s own, such as surfaces.farmland.season, overrides it for that part. Each shade within a surface, such as the cereal fields or the foam, has a colour knob of its own:

1
surfaces.updateConfig({ season: 'winter' });                                                 // bare fields, pale grass
2
setKnob(surfaces, glSurfacesKnobCatalogue, 'trees.season', 'autumn');                       // the trees alone turn
3
setKnob(surfaces, glSurfacesKnobCatalogue, 'surfaces.farmland.colors.rapeseed', '#f2d43a');  // brighter rapeseed

• The seasons shade the style’s colours, so the map colours you set, such as colors.vegetation, carry through every season.
• getKnob reports an unset colour knob as the style’s colour, shaded for the season in force. On satellite, the surfaces have no style colour to shade, so it reports none.
• snow covers the land and the trees in snow and hides the patterns under it. The water stays open, in a colder blue.

Share the map’s light

The surfaces take their sun from the map’s light, as every part of the plugin does (Share the map’s light). With Buildings3D beside them, the tree crowns, the dunes and the glint on the water line up with the buildings’ shadows. To light them both with a low sun from the west, set the map’s light:

1
import { StylingFoundationsModule } from '@tomtom-org/maps-sdk/map';
2
import { Buildings3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
3

4
const buildings = new Buildings3D(map);
5
await StylingFoundationsModule.get(map, { view: { light: { direction: 260, altitude: 20, alignment: 'map' } } });

• With Buildings3D on the map, the trees also stand in the buildings’ shadows: a crown in a tower’s shade loses its sunlit side.
• On streetSatellite, the water mirrors a day sky under the day sun.

The knobs belong to GLSurfaces. It adds its own layers to the loaded style and reads the map’s sky and light, which it never writes:

Place the trees

The textures always draw right after the layers they texture. The trees go under the style’s lowest label by default. Set beforeLayerConfig to put them elsewhere, as the map modules take beforeLayerConfig:

1
const surfaces = new GLSurfaces(map, { beforeLayerConfig: 'lowest3D' }); // under the 3D buildings
2
surfaces.updateConfig({ beforeLayerConfig: 'top' });                     // over everything

• It takes 'top' or a key of mapStyleLayerIDs. On a style without that layer, the trees go on top, or under the POIs for a missing lowest3D, as a module’s layers do.
• The trees also go under every layer a module or your app put right under the one it names. So a route, a place or a geometry drawn there stays over the trees, whichever you added first.
• It isn’t a knob: it moves the trees’ layers rather than restyling them, so glSurfacesKnobCatalogue doesn’t list it. resetConfig() puts the trees back under the labels.

Knobs

How it renders

For each run of style layers it textures, the plugin adds three things right after the run:

• A copy of what the map has drawn so far.
• Keys: copies of the run’s layers paint each surface in a key colour of its own.
• The materials: a last layer shades each surface’s material where its key shows, from the style’s colour there, then mixes it over the copy.

The materials draw on a grid over each tile, projected as the map projects its tiles:

• Dense screens: on 1.5 or more pixels per CSS pixel, they shade one pixel for each 2 by 2. Their details fade out by CSS pixels, so shading every pixel would cost 4 times as much for what no one sees, while the edges between surfaces keep the screen’s resolution.
• 3D terrain: the grid is the terrain’s own mesh, raised as the terrain raises it, so a ridge hides what lies behind it.
• Shores: before drawing the water, from zoom 12.5, it measures how far each pixel of water lies from the nearest shore, at a quarter of the screen’s resolution, so the waves know where to roll in.
• Roads: before drawing them, from zoom 15, it finds which way each road runs and how wide it is, at the same resolution, so the asphalt follows it.

The trees are placed on the GPU from the keyed ground, then drawn as instanced 3D shapes before the labels.

Limits

• It textures the standard TomTom styles. A style of your own needs the same layer ids and properties to be textured.
• While water, grass or trees move, the map redraws every frame, which costs battery on a phone. Set wind.speedFactor to 0 where that matters.

API reference

GLSurfaces · glSurfacesKnobCatalogue · surfaceKinds · surfaceSeasons

Related guides and examples

Related guides

• Map modules - setKnob, getKnob and the rules every knob follows
• Globe and sky - The map’s light, which the surfaces share with the 3D buildings
• Landmarks 3D plugin - The plugin’s three parts, its installation and the light they share
• 3D buildings - Buildings3D, lit by the same light, whose shadows the trees stand in
• Map effects plugin - Bloom, fog, depth of field and more over the textured map

Related examples

• GL Surfaces playground - Lake Geneva’s surfaces, trees and seasons, tuned live on one panel
• 3D city: landmarks, buildings and surfaces - The surfaces and trees with the buildings and a landmark, under one sun
• 3D city on satellite - The harbour and the trees over satellite imagery, in its colours
• 3D city at night - The river under the moon on a dark style, with bloom and glare
• 3D terrain playground - The textures and trees on the terrain, at Hallstatt
• Route fly-over playground - The textures and trees under a flight over the Alps
• Cinematic city fly-by - The textured ground in each look’s season, over cities and five landscapes