maplibre-gl 2.0.3 → 2.1.1

package/src/symbol/placement.ts

@@ -1,4 +1,5 @@
 import CollisionIndex from './collision_index';
+import type {FeatureKey} from './collision_index';
 import EXTENT from '../data/extent';
 import * as symbolSize from './symbol_size';
 import * as projection from './projection';
@@ -12,6 +13,7 @@ import type Transform from '../geo/transform';
 import type StyleLayer from '../style/style_layer';
 import {PossiblyEvaluated} from '../style/properties';
 import type {SymbolLayoutProps, SymbolLayoutPropsPossiblyEvaluated} from '../style/style_layer/symbol_style_layer_properties';
+import {getOverlapMode, OverlapMode} from '../style/style_layer/symbol_style_layer';
 
 import type Tile from '../source/tile';
 import SymbolBucket, {CollisionArrays, SingleCollisionBox} from '../data/bucket/symbol_bucket';
@@ -99,7 +101,7 @@ export class RetainedQueryData {
 
 type CollisionGroup = {
   ID: number;
-  predicate?: any;
+  predicate?: (key: FeatureKey) => boolean;
 };
 
 class CollisionGroups {
@@ -181,20 +183,20 @@ export type VariableOffset = {
 };
 
 type TileLayerParameters = {
-    bucket: SymbolBucket;
-    layout: PossiblyEvaluated<SymbolLayoutProps, SymbolLayoutPropsPossiblyEvaluated>;
-    posMatrix: mat4;
-    textLabelPlaneMatrix: mat4;
-    labelToScreenMatrix: mat4;
-    scale: number;
-    textPixelRatio: number;
-    holdingForFade: boolean;
-    collisionBoxArray: CollisionBoxArray;
-    partiallyEvaluatedTextSize: {
-        uSize: number;
-        uSizeT: number;
-    };
-    collisionGroup: CollisionGroup;
+  bucket: SymbolBucket;
+  layout: PossiblyEvaluated<SymbolLayoutProps, SymbolLayoutPropsPossiblyEvaluated>;
+  posMatrix: mat4;
+  textLabelPlaneMatrix: mat4;
+  labelToScreenMatrix: mat4;
+  scale: number;
+  textPixelRatio: number;
+  holdingForFade: boolean;
+  collisionBoxArray: CollisionBoxArray;
+  partiallyEvaluatedTextSize: {
+    uSize: number;
+    uSizeT: number;
+  };
+  collisionGroup: CollisionGroup;
 };
 
 export type BucketPart = {
@@ -344,7 +346,7 @@ export class Placement {
       textPixelRatio: number,
       posMatrix: mat4,
       collisionGroup: CollisionGroup,
-      textAllowOverlap: boolean,
+      textOverlapMode: OverlapMode,
       symbolInstance: SymbolInstance,
       bucket: SymbolBucket,
       orientation: number,
@@ -364,14 +366,14 @@ export class Placement {
             shiftVariableCollisionBox(
                 textBox, shift.x, shift.y,
                 rotateWithMap, pitchWithMap, this.transform.angle),
-            textAllowOverlap, textPixelRatio, posMatrix, collisionGroup.predicate);
+            textOverlapMode, textPixelRatio, posMatrix, collisionGroup.predicate);
 
         if (iconBox) {
             const placedIconBoxes = this.collisionIndex.placeCollisionBox(
                 shiftVariableCollisionBox(
                     iconBox, shift.x, shift.y,
                     rotateWithMap, pitchWithMap, this.transform.angle),
-                textAllowOverlap, textPixelRatio, posMatrix, collisionGroup.predicate);
+                textOverlapMode, textPixelRatio, posMatrix, collisionGroup.predicate);
             if (placedIconBoxes.box.length === 0) return;
         }
 
@@ -424,8 +426,10 @@ export class Placement {
 
         const textOptional = layout.get('text-optional');
         const iconOptional = layout.get('icon-optional');
-        const textAllowOverlap = layout.get('text-allow-overlap');
-        const iconAllowOverlap = layout.get('icon-allow-overlap');
+        const textOverlapMode = getOverlapMode(layout, 'text-overlap', 'text-allow-overlap');
+        const textAlwaysOverlap = textOverlapMode === 'always';
+        const iconOverlapMode = getOverlapMode(layout, 'icon-overlap', 'icon-allow-overlap');
+        const iconAlwaysOverlap = iconOverlapMode === 'always';
         const rotateWithMap = layout.get('text-rotation-alignment') === 'map';
         const pitchWithMap = layout.get('text-pitch-alignment') === 'map';
         const hasIconTextFit = layout.get('icon-text-fit') !== 'none';
@@ -445,8 +449,8 @@ export class Placement {
         //  This is the reverse of our normal policy of "fade in on pan", but should look like any other
         //  collision and hopefully not be too noticeable.
         // See https://github.com/mapbox/mapbox-gl-js/issues/7172
-        const alwaysShowText = textAllowOverlap && (iconAllowOverlap || !bucket.hasIconData() || iconOptional);
-        const alwaysShowIcon = iconAllowOverlap && (textAllowOverlap || !bucket.hasTextData() || textOptional);
+        const alwaysShowText = textAlwaysOverlap && (iconAlwaysOverlap || !bucket.hasIconData() || iconOptional);
+        const alwaysShowIcon = iconAlwaysOverlap && (textAlwaysOverlap || !bucket.hasTextData() || textOptional);
 
         if (!bucket.collisionArrays && collisionBoxArray) {
             bucket.deserializeCollisionBoxes(collisionBoxArray);
@@ -519,8 +523,12 @@ export class Placement {
 
                 if (!layout.get('text-variable-anchor')) {
                     const placeBox = (collisionTextBox, orientation) => {
-                        const placedFeature = this.collisionIndex.placeCollisionBox(collisionTextBox, textAllowOverlap,
-                                                                                  textPixelRatio, posMatrix, collisionGroup.predicate);
+                        const placedFeature = this.collisionIndex.placeCollisionBox(
+                            collisionTextBox,
+                            textOverlapMode,
+                            textPixelRatio,
+                            posMatrix,
+                            collisionGroup.predicate);
                         if (placedFeature && placedFeature.box && placedFeature.box.length) {
                             this.markUsedOrientation(bucket, orientation, symbolInstance);
                             this.placedOrientations[symbolInstance.crossTileID] = orientation;
@@ -562,20 +570,20 @@ export class Placement {
                         const height = collisionTextBox.y2 - collisionTextBox.y1;
                         const textBoxScale = symbolInstance.textBoxScale;
 
-                        const variableIconBox = hasIconTextFit && !iconAllowOverlap ? collisionIconBox : null;
+                        const variableIconBox = hasIconTextFit && (iconOverlapMode === 'never') ? collisionIconBox : null;
 
                         let placedBox: {
                           box: Array<number>;
                           offscreen: boolean;
                         } = {box: [], offscreen: false};
-                        const placementAttempts = textAllowOverlap ? anchors.length * 2 : anchors.length;
+                        const placementAttempts = (textOverlapMode !== 'never') ? anchors.length * 2 : anchors.length;
                         for (let i = 0; i < placementAttempts; ++i) {
                             const anchor = anchors[i % anchors.length];
-                            const allowOverlap = (i >= anchors.length);
+                            const overlapMode = (i >= anchors.length) ? textOverlapMode : 'never';
                             const result = this.attemptAnchorPlacement(
                                 anchor, collisionTextBox, width, height,
                                 textBoxScale, rotateWithMap, pitchWithMap, textPixelRatio, posMatrix,
-                                collisionGroup, allowOverlap, symbolInstance, bucket, orientation, variableIconBox);
+                                collisionGroup, overlapMode, symbolInstance, bucket, orientation, variableIconBox);
 
                             if (result) {
                                 placedBox = result.placedGlyphBoxes;
@@ -637,26 +645,27 @@ export class Placement {
                 const textPixelPadding = layout.get('text-padding');
                 const circlePixelDiameter = symbolInstance.collisionCircleDiameter;
 
-                placedGlyphCircles = this.collisionIndex.placeCollisionCircles(textAllowOverlap,
-                        placedSymbol,
-                        bucket.lineVertexArray,
-                        bucket.glyphOffsetArray,
-                        fontSize,
-                        posMatrix,
-                        textLabelPlaneMatrix,
-                        labelToScreenMatrix,
-                        showCollisionBoxes,
-                        pitchWithMap,
-                        collisionGroup.predicate,
-                        circlePixelDiameter,
-                        textPixelPadding);
+                placedGlyphCircles = this.collisionIndex.placeCollisionCircles(
+                    textOverlapMode,
+                    placedSymbol,
+                    bucket.lineVertexArray,
+                    bucket.glyphOffsetArray,
+                    fontSize,
+                    posMatrix,
+                    textLabelPlaneMatrix,
+                    labelToScreenMatrix,
+                    showCollisionBoxes,
+                    pitchWithMap,
+                    collisionGroup.predicate,
+                    circlePixelDiameter,
+                    textPixelPadding);
 
                 assert(!placedGlyphCircles.circles.length || (!placedGlyphCircles.collisionDetected || showCollisionBoxes));
-                // If text-allow-overlap is set, force "placedCircles" to true
+                // If text-overlap is set to 'always', force "placedCircles" to true
                 // In theory there should always be at least one circle placed
                 // in this case, but for now quirks in text-anchor
                 // and text-offset may prevent that from being true.
-                placeText = textAllowOverlap || (placedGlyphCircles.circles.length > 0 && !placedGlyphCircles.collisionDetected);
+                placeText = textAlwaysOverlap || (placedGlyphCircles.circles.length > 0 && !placedGlyphCircles.collisionDetected);
                 offscreen = offscreen && placedGlyphCircles.offscreen;
             }
 
@@ -673,7 +682,7 @@ export class Placement {
                             rotateWithMap, pitchWithMap, this.transform.angle) :
                         iconBox;
                     return this.collisionIndex.placeCollisionBox(shiftedIconBox,
-                        iconAllowOverlap, textPixelRatio, posMatrix, collisionGroup.predicate);
+                        iconOverlapMode, textPixelRatio, posMatrix, collisionGroup.predicate);
                 };
 
                 if (placedVerticalText && placedVerticalText.box && placedVerticalText.box.length && collisionArrays.verticalIconBox) {
@@ -701,22 +710,42 @@ export class Placement {
 
             if (placeText && placedGlyphBoxes && placedGlyphBoxes.box) {
                 if (placedVerticalText && placedVerticalText.box && verticalTextFeatureIndex) {
-                    this.collisionIndex.insertCollisionBox(placedGlyphBoxes.box, layout.get('text-ignore-placement'),
-                        bucket.bucketInstanceId, verticalTextFeatureIndex, collisionGroup.ID);
+                    this.collisionIndex.insertCollisionBox(
+                        placedGlyphBoxes.box,
+                        textOverlapMode,
+                        layout.get('text-ignore-placement'),
+                        bucket.bucketInstanceId,
+                        verticalTextFeatureIndex,
+                        collisionGroup.ID);
                 } else {
-                    this.collisionIndex.insertCollisionBox(placedGlyphBoxes.box, layout.get('text-ignore-placement'),
-                        bucket.bucketInstanceId, textFeatureIndex, collisionGroup.ID);
+                    this.collisionIndex.insertCollisionBox(
+                        placedGlyphBoxes.box,
+                        textOverlapMode,
+                        layout.get('text-ignore-placement'),
+                        bucket.bucketInstanceId,
+                        textFeatureIndex,
+                        collisionGroup.ID);
                 }
 
             }
             if (placeIcon && placedIconBoxes) {
-                this.collisionIndex.insertCollisionBox(placedIconBoxes.box, layout.get('icon-ignore-placement'),
-                        bucket.bucketInstanceId, iconFeatureIndex, collisionGroup.ID);
+                this.collisionIndex.insertCollisionBox(
+                    placedIconBoxes.box,
+                    iconOverlapMode,
+                    layout.get('icon-ignore-placement'),
+                    bucket.bucketInstanceId,
+                    iconFeatureIndex,
+                    collisionGroup.ID);
             }
             if (placedGlyphCircles) {
                 if (placeText) {
-                    this.collisionIndex.insertCollisionCircles(placedGlyphCircles.circles, layout.get('text-ignore-placement'),
-                        bucket.bucketInstanceId, textFeatureIndex, collisionGroup.ID);
+                    this.collisionIndex.insertCollisionCircles(
+                        placedGlyphCircles.circles,
+                        textOverlapMode,
+                        layout.get('text-ignore-placement'),
+                        bucket.bucketInstanceId,
+                        textFeatureIndex,
+                        collisionGroup.ID);
                 }
 
                 if (showCollisionBoxes) {
@@ -887,7 +916,7 @@ export class Placement {
     updateLayerOpacities(styleLayer: StyleLayer, tiles: Array<Tile>) {
         const seenCrossTileIDs = {};
         for (const tile of tiles) {
-            const symbolBucket = (tile.getBucket(styleLayer) as SymbolBucket);
+            const symbolBucket = tile.getBucket(styleLayer) as SymbolBucket;
             if (symbolBucket && tile.latestFeatureIndex && styleLayer.id === symbolBucket.layerIds[0]) {
                 this.updateBucketOpacities(symbolBucket, seenCrossTileIDs, tile.collisionBoxArray);
             }

package/src/symbol/symbol_style_layer.test.ts

@@ -1,4 +1,4 @@
-import SymbolStyleLayer from '../style/style_layer/symbol_style_layer';
+import SymbolStyleLayer, {getOverlapMode} from '../style/style_layer/symbol_style_layer';
 import FormatSectionOverride from '../style/format_section_override';
 import properties, {SymbolPaintPropsPossiblyEvaluated} from '../style/style_layer/symbol_style_layer_properties';
 import ZoomHistory from '../style/zoom_history';
@@ -101,3 +101,50 @@ describe('hasPaintOverrides', () => {
     });
 
 });
+
+describe('getOverlapMode', () => {
+    test('defaults - no props set', () => {
+        const props = {};
+        const layer = createSymbolLayer(props);
+
+        expect(getOverlapMode(layer.layout, 'icon-overlap', 'icon-allow-overlap')).toBe('never');
+        expect(getOverlapMode(layer.layout, 'text-overlap', 'text-allow-overlap')).toBe('never');
+    });
+
+    test('-allow-overlap set', () => {
+        const props = {layout: {'icon-allow-overlap': false, 'text-allow-overlap': true}};
+        const layer = createSymbolLayer(props);
+
+        expect(getOverlapMode(layer.layout, 'icon-overlap', 'icon-allow-overlap')).toBe('never');
+        expect(getOverlapMode(layer.layout, 'text-overlap', 'text-allow-overlap')).toBe('always');
+    });
+
+    test('-overlap set', () => {
+        let props = {layout: {'icon-overlap': 'never', 'text-overlap': 'always'}};
+        let layer = createSymbolLayer(props);
+
+        expect(getOverlapMode(layer.layout, 'icon-overlap', 'icon-allow-overlap')).toBe('never');
+        expect(getOverlapMode(layer.layout, 'text-overlap', 'text-allow-overlap')).toBe('always');
+
+        props = {layout: {'icon-overlap': 'always', 'text-overlap': 'cooperative'}};
+        layer = createSymbolLayer(props);
+
+        expect(getOverlapMode(layer.layout, 'icon-overlap', 'icon-allow-overlap')).toBe('always');
+        expect(getOverlapMode(layer.layout, 'text-overlap', 'text-allow-overlap')).toBe('cooperative');
+    });
+
+    test('-overlap beats -allow-overlap', () => {
+        const props = {
+            layout: {
+                'icon-overlap': 'never',
+                'icon-allow-overlap': true,
+                'text-overlap': 'cooperative',
+                'text-allow-overlap': false
+            }
+        };
+        const layer = createSymbolLayer(props);
+
+        expect(getOverlapMode(layer.layout, 'icon-overlap', 'icon-allow-overlap')).toBe('never');
+        expect(getOverlapMode(layer.layout, 'text-overlap', 'text-allow-overlap')).toBe('cooperative');
+    });
+});

package/src/ui/camera.test.ts

@@ -756,9 +756,9 @@ describe('#easeTo', () => {
         const camera = createCamera();
 
         camera
-            .on('zoomstart', () => { fail(); })
-            .on('zoom', () => { fail(); })
-            .on('zoomend', () => { fail(); })
+            .on('zoomstart', () => { done('zoomstart failed'); })
+            .on('zoom', () => { done('zoom failed'); })
+            .on('zoomend', () => { done('zoomend failed'); })
             .on('moveend', () => { done(); });
 
         camera.easeTo({center: [100, 0], duration: 0});
@@ -1545,7 +1545,7 @@ describe('#flyTo', () => {
             .on('moveend', () => {
                 endTime = new Date();
                 timeDiff = endTime - startTime;
-                expect(timeDiff).toBeLessThan(10);
+                expect(timeDiff).toBeLessThan(30);
                 done();
             });
 

package/src/ui/camera.ts

@@ -14,6 +14,14 @@ import type {LngLatBoundsLike} from '../geo/lng_lat_bounds';
 import type {TaskID} from '../util/task_queue';
 import type {PaddingOptions} from '../geo/edge_insets';
 
+/**
+ * A [Point](https://github.com/mapbox/point-geometry) or an array of two numbers representing `x` and `y` screen coordinates in pixels.
+ *
+ * @typedef {(Point | [number, number])} PointLike
+ * @example
+ * var p1 = new Point(-77, 38); // a PointLike which is a Point
+ * var p2 = [-77, 38]; // a PointLike which is an array of two numbers
+ */
 export type PointLike = Point | [number, number];
 
 export type RequireAtLeastOne<T> = { [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>; }[keyof T];

package/src/ui/control/logo_control.test.ts

@@ -34,6 +34,7 @@ function createSource(options, logoRequired) {
             _skuToken: '1234567890123',
             canonicalizeTileset: tileJSON => tileJSON.tiles
         },
+        style: {sourceCaches: {id: {clearTiles() {}}}},
         transform: {angle: 0, pitch: 0, showCollisionBoxes: false},
         _getMapId: () => 1
     }as any as Map);

package/src/ui/handler/scroll_zoom.test.ts

@@ -46,7 +46,7 @@ describe('ScrollZoomHandler', () => {
         map.remove();
     });
 
-    test('Zooms for single mouse wheel tick with non-magical deltaY', () => {
+    test('Zooms for single mouse wheel tick with non-magical deltaY', done => {
         const browserNow = jest.spyOn(browser, 'now');
         const now = 1555555555555;
         browserNow.mockReturnValue(now);
@@ -60,6 +60,7 @@ describe('ScrollZoomHandler', () => {
         simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -20});
         map.on('zoomstart', () => {
             map.remove();
+            done();
         });
     });
 

package/src/ui/map.test.ts

@@ -134,15 +134,17 @@ describe('Map', () => {
     test('emits load event after a style is set', done => {
         const map = new Map({container: window.document.createElement('div')} as any as MapOptions);
 
-        map.on('load', done.fail);
+        const fail = () => done('test failed');
+        const pass = () => done();
+
+        map.on('load', fail);
 
         setTimeout(() => {
-            map.off('load', done.fail);
-            map.on('load', () => {
-                done();
-            });
+            map.off('load', fail);
+            map.on('load', pass);
             map.setStyle(createStyle());
         }, 1);
+
     });
 
     describe('#setStyle', () => {
@@ -918,7 +920,7 @@ describe('Map', () => {
     test('does not fire "webglcontextlost" after #remove has been called', done => {
         const map = createMap();
         const canvas = map.getCanvas();
-        map.once('webglcontextlost', () => done.fail('"webglcontextlost" fired after #remove has been called'));
+        map.once('webglcontextlost', () => done('"webglcontextlost" fired after #remove has been called'));
         map.remove();
         // Dispatch the event manually because at the time of this writing, gl does not support
         // the WEBGL_lose_context extension.
@@ -931,7 +933,7 @@ describe('Map', () => {
         const canvas = map.getCanvas();
 
         map.once('webglcontextlost', () => {
-            map.once('webglcontextrestored', () => done.fail('"webglcontextrestored" fired after #remove has been called'));
+            map.once('webglcontextrestored', () => done('"webglcontextrestored" fired after #remove has been called'));
             map.remove();
             canvas.dispatchEvent(new window.Event('webglcontextrestored'));
             done();
@@ -1885,7 +1887,9 @@ describe('Map', () => {
             if (timer) clearTimeout(timer);
             timer = setTimeout(() => {
                 map.off('render', undefined);
-                map.on('render', done.fail);
+                map.on('render', () => {
+                    done('test failed');
+                });
                 expect((map as any)._frameId).toBeFalsy();
                 done();
             }, 100);
@@ -1896,7 +1900,9 @@ describe('Map', () => {
         const style = createStyle();
         const map = createMap({style});
         map.on('idle', () => {
-            map.on('render', done.fail);
+            map.on('render', () => {
+                done('test failed');
+            });
             setTimeout(() => {
                 done();
             }, 100);
@@ -2043,11 +2049,72 @@ describe('Map', () => {
             });
 
             map.on('styleimagemissing', ({id}) => {
-                done.fail(`styleimagemissing fired for value ${id}`);
+                done(`styleimagemissing fired for value ${id}`);
             });
         });
     });
 
+    describe('setPixelRatio', () => {
+        test('resizes canvas', () => {
+            const container = window.document.createElement('div');
+            Object.defineProperty(container, 'clientWidth', {value: 512});
+            Object.defineProperty(container, 'clientHeight', {value: 512});
+            const map = createMap({container, pixelRatio: 1});
+            expect(map.getCanvas().width).toBe(512);
+            expect(map.getCanvas().height).toBe(512);
+            map.setPixelRatio(2);
+            expect(map.getCanvas().width).toBe(1024);
+            expect(map.getCanvas().height).toBe(1024);
+        });
+
+        test('resizes painter', () => {
+            const container = window.document.createElement('div');
+            Object.defineProperty(container, 'clientWidth', {value: 512});
+            Object.defineProperty(container, 'clientHeight', {value: 512});
+            const map = createMap({container, pixelRatio: 1});
+            expect(map.painter.pixelRatio).toBe(1);
+            expect(map.painter.width).toBe(512);
+            expect(map.painter.height).toBe(512);
+            map.setPixelRatio(2);
+            expect(map.painter.pixelRatio).toBe(2);
+            expect(map.painter.width).toBe(1024);
+            expect(map.painter.height).toBe(1024);
+        });
+    });
+
+    describe('getPixelRatio', () => {
+        test('returns the pixel ratio', () => {
+            const map = createMap({pixelRatio: 1});
+            expect(map.getPixelRatio()).toBe(1);
+            map.setPixelRatio(2);
+            expect(map.getPixelRatio()).toBe(2);
+        });
+    });
+
+    test('pixel ratio defaults to devicePixelRatio', () => {
+        const map = createMap();
+        expect(map.getPixelRatio()).toBe(devicePixelRatio);
+    });
+
+    test('canvas has the expected size', () => {
+        const container = window.document.createElement('div');
+        Object.defineProperty(container, 'clientWidth', {value: 512});
+        Object.defineProperty(container, 'clientHeight', {value: 512});
+        const map = createMap({container, pixelRatio: 2});
+        expect(map.getCanvas().width).toBe(1024);
+        expect(map.getCanvas().height).toBe(1024);
+    });
+
+    test('painter has the expected size and pixel ratio', () => {
+        const container = window.document.createElement('div');
+        Object.defineProperty(container, 'clientWidth', {value: 512});
+        Object.defineProperty(container, 'clientHeight', {value: 512});
+        const map = createMap({container, pixelRatio: 2});
+        expect(map.painter.pixelRatio).toBe(2);
+        expect(map.painter.width).toBe(1024);
+        expect(map.painter.height).toBe(1024);
+    });
+
 });
 
 function createStyle() {

package/src/ui/map.ts

@@ -101,6 +101,7 @@ export type MapOptions = {
   localIdeographFontFamily?: string;
   style: StyleSpecification | string;
   pitchWithRotate?: boolean;
+  pixelRatio?: number;
 };
 
 // See article here: https://medium.com/terria/typescript-transforming-optional-properties-to-required-properties-that-may-be-undefined-7482cb4e1585
@@ -235,6 +236,7 @@ const defaultOptions = {
  * @param {number} [options.fadeDuration=300] Controls the duration of the fade-in/fade-out animation for label collisions, in milliseconds. This setting affects all symbol layers. This setting does not affect the duration of runtime styling transitions or raster tile cross-fading.
  * @param {boolean} [options.crossSourceCollisions=true] If `true`, symbols from multiple sources can collide with each other during collision detection. If `false`, collision detection is run separately for the symbols in each source.
  * @param {Object} [options.locale=null] A patch to apply to the default localization table for UI strings, e.g. control tooltips. The `locale` object maps namespaced UI string IDs to translated strings in the target language; see `src/ui/default_locale.js` for an example with all supported string IDs. The object may specify all UI strings (thereby adding support for a new translation) or only a subset of strings (thereby patching the default translation table).
+ * @param {number} [options.pixelRatio] The pixel ratio. The canvas' `width` attribute will be `container.clientWidth * pixelRatio` and its `height` attribute will be `container.clientHeight * pixelRatio`. Defaults to `devicePixelRatio` if not specified.
  * @example
  * var map = new maplibregl.Map({
  *   container: 'map',
@@ -298,6 +300,7 @@ class Map extends Camera {
     _locale: any;
     _removed: boolean;
     _clickTolerance: number;
+    _pixelRatio: number;
 
     /**
      * The map's {@link ScrollZoomHandler}, which implements zooming in and out with a scroll wheel or trackpad.
@@ -389,6 +392,7 @@ class Map extends Camera {
         this._mapId = uniqueId();
         this._locale = extend({}, defaultLocale, options.locale);
         this._clickTolerance = options.clickTolerance;
+        this._pixelRatio = options.pixelRatio ?? devicePixelRatio;
 
         this._requestManager = new RequestManager(options.transformRequest);
 
@@ -584,9 +588,9 @@ class Map extends Camera {
         const width = dimensions[0];
         const height = dimensions[1];
 
-        this._resizeCanvas(width, height);
+        this._resizeCanvas(width, height, this.getPixelRatio());
         this.transform.resize(width, height);
-        this.painter.resize(width, height);
+        this.painter.resize(width, height, this.getPixelRatio());
 
         const fireMoving = !this._moving;
         if (fireMoving) {
@@ -602,6 +606,29 @@ class Map extends Camera {
         return this;
     }
 
+    /**
+     * Returns the map's pixel ratio.
+     * @returns {number} The pixel ratio.
+     */
+    getPixelRatio() {
+        return this._pixelRatio;
+    }
+
+    /**
+     * Sets the map's pixel ratio. This allows to override `devicePixelRatio`.
+     * After this call, the canvas' `width` attribute will be `container.clientWidth * pixelRatio`
+     * and its height attribute will be `container.clientHeight * pixelRatio`.
+     * @param {number} pixelRatio The pixel ratio.
+     */
+    setPixelRatio(pixelRatio: number) {
+        const [width, height] = this._containerDimensions();
+
+        this._pixelRatio = pixelRatio;
+
+        this._resizeCanvas(width, height, pixelRatio);
+        this.painter.resize(width, height, pixelRatio);
+    }
+
     /**
      * Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not
      * an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.
@@ -828,11 +855,11 @@ class Map extends Camera {
     }
 
     /**
-     * Returns a {@link Point} representing pixel coordinates, relative to the map's `container`,
+     * Returns a [Point](https://github.com/mapbox/point-geometry) representing pixel coordinates, relative to the map's `container`,
      * that correspond to the specified geographical location.
      *
      * @param {LngLatLike} lnglat The geographical location to project.
-     * @returns {Point} The {@link Point} corresponding to `lnglat`, relative to the map's `container`.
+     * @returns {Point} The [Point](https://github.com/mapbox/point-geometry) corresponding to `lnglat`, relative to the map's `container`.
      * @example
      * var coordinate = [-122.420679, 37.772537];
      * var point = map.project(coordinate);
@@ -2349,7 +2376,7 @@ class Map extends Camera {
         this._canvas.setAttribute('role', 'region');
 
         const dimensions = this._containerDimensions();
-        this._resizeCanvas(dimensions[0], dimensions[1]);
+        this._resizeCanvas(dimensions[0], dimensions[1], this.getPixelRatio());
 
         const controlContainer = this._controlContainer = DOM.create('div', 'maplibregl-control-container mapboxgl-control-container', container);
         const positions = this._controlPositions = {};
@@ -2360,9 +2387,7 @@ class Map extends Camera {
         this._container.addEventListener('scroll', this._onMapScroll, false);
     }
 
-    _resizeCanvas(width: number, height: number) {
-        const pixelRatio = devicePixelRatio || 1;
-
+    _resizeCanvas(width: number, height: number, pixelRatio: number) {
         // Request the required canvas size taking the pixelratio into account.
         this._canvas.width = pixelRatio * width;
         this._canvas.height = pixelRatio * height;