Graphics presets

The feature is available for MapGL JS API version 1.55.0 or later.

Immersive features of the MapGL JS API require high performance of user devices. To control the level of graphics and immersion on the map, configure the map graphics presets in the Style editor. You can set an active preset for all users or allow users to select a preset and disable irrelevant features.

For graphics presets, you can specify graphics settings – a set of flags that enable or disable immersive features of the map: immersive roads, shadows, fog, and sky. The map uses graphics settings defined by the current value of the global style variable graphicsPreset (it is a field of the StyleState object). Three values are available: light, normal, and immersive.

Usage example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Graphics Preset Example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            select {
                position: absolute;
                z-index: 1;
                top: 16px;
                left: 16px;
            }
        </style>
    </head>
    <body>
        <select>
            <option value="light">light</option>
            <option value="normal">normal</option>
            <option value="immersive">immersive</option>
        </select>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 18.5,
                pitch: 35,
                key: 'Your API access key',
                graphicsPreset: 'immersive',
                style: '8780eed4-0428-4982-b615-aa6cf04d8f5f',
                styleState: {
                    immersiveRoadsOn: true,
                },
            });
            const select = document.querySelector('select');
            select.value = 'immersive';
            select.addEventListener('change', () => {
                map.patchStyleState({ graphicsPreset: select.value });
            });
        </script>
    </body>
</html>

Configuring presets

Open the Style editor.
Open the required style.
In the Other tab, select Graphics presets:
To set the graphicsPreset value, go to the Settings section and select a preset in the Graphics presets field:
Specify graphics settings for each preset. For example, turn off shadows for the normal preset:

In this case, selecting graphicsPreset = immersive turns shadows on:

Selecting graphicsPreset = normal turns shadows off:

Turning on and switching a preset

To set a graphics preset for the map and apply its style settings, set the global style variable graphicsPreset when initializing the map:

const map = new mapgl.Map('map-container', {
    graphicsPreset: 'immersive', // 'light', 'normal', or 'immersive'
});

To allow users to change the active preset while working with the map, use the map.patchStyleState() method:

const map = new mapgl.Map('map-container', {
    graphicsPreset: 'immersive',
});

// ...

// Switching the preset
map.patchStyleState({ graphicsPreset: 'normal' });