Enable client-side fontstack compositing by default

GitOrigin-RevId: d6990296a168dba501e4a79b50d98f6a9bd1002e

Author: stepankuzmin

debug/render-test.html

@@ -47,6 +47,7 @@
         const {
             fadeDuration = 0,
             localIdeographFontFamily = false,
+            fontstackCompositing,
             operations,
             scaleFactor = 1,
             ...options
@@ -107,6 +108,7 @@
             transformRequest,
             fadeDuration,
             localIdeographFontFamily,
+            fontstackCompositing,
             interactive: false,
             attributionControl: false,
             performanceMetricsCollection: false,

src/index.ts

@@ -65,6 +65,7 @@ export type {NavigationControlOptions} from './ui/control/navigation_control';
 export type {FullscreenControlOptions} from './ui/control/fullscreen_control';
 export type {AttributionControlOptions} from './ui/control/attribution_control';
 export type {MapOptions, IControl, ControlPosition} from './ui/map';
+export type {FontstackCompositing} from './style/glyph_loader';
 export type {AnimationOptions, CameraOptions, EasingOptions} from './ui/camera';
 
 export type {

src/render/glyph_manager.ts

@@ -5,6 +5,7 @@ import config from '../util/config';
 import {asyncAll, warnOnce} from '../util/util';
 import {AlphaImage} from '../util/image';
 
+import type {FontstackCompositing} from '../style/glyph_loader';
 import type {Class} from '../types/class';
 import type {GlyphRange} from '../style/load_glyph_range';
 import type {StyleGlyph, StyleGlyphs} from '../style/style_glyph';
@@ -77,7 +78,7 @@ class GlyphManager {
 
     static TinySDF: Class<TinySDF>;
 
-    constructor(requestManager: RequestManager, localGlyphMode: number, localFontFamily?: string, useServerFontComposition?: boolean) {
+    constructor(requestManager: RequestManager, localGlyphMode: number, localFontFamily?: string, fontstackCompositing?: FontstackCompositing) {
         this.requestManager = requestManager;
         this.localGlyphMode = localGlyphMode;
         this.localFontFamily = localFontFamily;
@@ -89,7 +90,7 @@ class GlyphManager {
             '500': {},
             '900': {}
         };
-        this.glyphLoader = new GlyphLoader({useServerFontComposition});
+        this.glyphLoader = new GlyphLoader({fontstackCompositing});
     }
 
     setURL(url: string) {

src/style/glyph_loader.ts

@@ -6,8 +6,18 @@ import type {StyleGlyphs} from './style_glyph';
 import type {RequestManager} from '../util/mapbox';
 import type {Callback} from '../types/callback';
 
+/**
+ * Controls how multi-font fontstacks are composited.
+ *
+ * - `'client'` (default): Each font in a comma-separated fontstack is loaded individually
+ *   and missing glyphs are filled from subsequent fallback fonts on the client.
+ * - `'server'`: The full fontstack string is passed as-is to the glyph server, which must
+ *   support server-side fontstack composition.
+ */
+export type FontstackCompositing = 'client' | 'server';
+
 type GlyphLoaderOptions = {
-    useServerFontComposition?: boolean;
+    fontstackCompositing?: FontstackCompositing;
 };
 
 /*
@@ -24,15 +34,15 @@ class GlyphLoader {
 
     private cachedRanges: Map<string, GlyphRange | null>;
 
-    private useServerFontComposition: boolean;
+    private fontstackCompositing: FontstackCompositing;
 
     // Exposed as static to enable stubbing in unit tests
     static loadGlyphRange: typeof loadGlyphRange;
 
     constructor(options?: GlyphLoaderOptions) {
         this.pendingRequests = new Map();
         this.cachedRanges = new Map();
-        this.useServerFontComposition = options && options.useServerFontComposition !== undefined ? options.useServerFontComposition : true;
+        this.fontstackCompositing = (options && options.fontstackCompositing) || 'client';
     }
 
     loadGlyphRange(
@@ -42,7 +52,7 @@ class GlyphLoader {
         requestManager: RequestManager,
         callback: Callback<GlyphRange>
     ): void {
-        if (this.useServerFontComposition) {
+        if (this.fontstackCompositing === 'server') {
             GlyphLoader.loadGlyphRange(fontstack, range, urlTemplate, requestManager, callback);
             return;
         }

src/style/style.ts

@@ -73,6 +73,7 @@ import {ImageProvider} from '../render/image_provider';
 import IndoorManager from './indoor_manager';
 import {StyleBOMUtils} from './style_bom_utils';
 
+import type {FontstackCompositing} from './glyph_loader';
 import type {PropertyValidatorOptions} from '../style-spec/validate/validate_property';
 import type Tile from '../source/tile';
 import type GeoJSONSource from '../source/geojson_source';
@@ -228,7 +229,7 @@ export type StyleOptions = {
     validate?: boolean;
     localFontFamily?: string | null | undefined;
     localIdeographFontFamily?: string;
-    useServerFontComposition?: boolean;
+    fontstackCompositing?: FontstackCompositing;
     dispatcher?: Dispatcher;
     imageManager?: ImageManager;
     glyphManager?: GlyphManager;
@@ -465,7 +466,7 @@ class Style extends Evented<MapEvents> {
                     LocalGlyphMode.all :
                     (options.localIdeographFontFamily ? LocalGlyphMode.ideographs : LocalGlyphMode.none),
                 options.localFontFamily || options.localIdeographFontFamily,
-                options.useServerFontComposition);
+                options.fontstackCompositing);
         }
 
         if (options.modelManager) {

src/ui/map.ts

@@ -60,6 +60,7 @@ import type {LngLatLike, LngLatBoundsLike} from '../geo/lng_lat';
 import type {CustomLayerInterface} from '../style/style_layer/custom_style_layer';
 import type {StyleImageInterface, StyleImageMetadata} from '../style/style_image';
 import type {StyleOptions, StyleSetterOptions, AnyLayer, FeatureSelector, SourceSelector, QueryRenderedFeaturesParams, QueryRenderedFeaturesetParams} from '../style/style';
+import type {FontstackCompositing} from '../style/glyph_loader';
 import type ScrollZoomHandler from './handler/scroll_zoom';
 import type {ScrollZoomHandlerOptions} from './handler/scroll_zoom';
 import type BoxZoomHandler from './handler/box_zoom';
@@ -126,7 +127,7 @@ export type SetStyleOptions = {
     };
     localFontFamily: StyleOptions['localFontFamily'];
     localIdeographFontFamily: StyleOptions['localIdeographFontFamily'];
-    useServerFontComposition?: StyleOptions['useServerFontComposition'];
+    fontstackCompositing?: FontstackCompositing;
 };
 
 type Listener<T extends MapEventType> = (event: MapEventOf<T>) => void;
@@ -212,7 +213,7 @@ export type MapOptions = {
     fadeDuration?: number;
     localFontFamily?: string;
     localIdeographFontFamily?: string;
-    useServerFontComposition?: boolean;
+    fontstackCompositing?: FontstackCompositing;
     performanceMetricsCollection?: boolean;
     tessellationStep?: number;
     scaleFactor?: number;
@@ -267,7 +268,7 @@ const defaultOptions = {
     maxTileCacheSize: null,
     localIdeographFontFamily: 'sans-serif',
     localFontFamily: null,
-    useServerFontComposition: true,
+    fontstackCompositing: 'client',
     transformRequest: null,
     accessToken: null,
     fadeDuration: 300,
@@ -392,6 +393,9 @@ const defaultOptions = {
  * @param {string} [options.localFontFamily=null] Defines a CSS
  * font-family for locally overriding generation of all glyphs. Font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold).
  * If set, this option overrides the setting in localIdeographFontFamily.
+ * @param {'client' | 'server'} [options.fontstackCompositing='client'] Controls how multi-font fontstacks are composited.
+ * When `'client'` (the default), each font in a comma-separated fontstack is loaded individually and missing glyphs are filled from subsequent fallback fonts on the client.
+ * When `'server'`, the full fontstack string is passed as-is to the glyph server, which must support server-side fontstack composition.
  * @param {RequestTransformFunction} [options.transformRequest=null] A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests.
  * Expected to return a {@link RequestParameters} object with a `url` property and optionally `headers` and `credentials` properties.
  * @param {boolean} [options.collectResourceTiming=false] If `true`, Resource Timing API information will be collected for requests made by GeoJSON and Vector Tile web workers (this information is normally inaccessible from the main Javascript thread). Information will be returned in a `resourceTiming` property of relevant `data` events.
@@ -498,7 +502,7 @@ export class Map extends Camera {
     _mapId: number;
     _localIdeographFontFamily: string;
     _localFontFamily?: string;
-    _useServerFontComposition?: boolean;
+    _fontstackCompositing: FontstackCompositing;
     _requestManager: RequestManager;
     _locale: Partial<typeof defaultLocale>;
     _removed: boolean;
@@ -728,15 +732,15 @@ export class Map extends Camera {
 
         this._localFontFamily = options.localFontFamily;
         this._localIdeographFontFamily = options.localIdeographFontFamily;
-        this._useServerFontComposition = options.useServerFontComposition;
+        this._fontstackCompositing = options.fontstackCompositing;
 
         if (options.style || !options.testMode) {
             const style = options.style || config.DEFAULT_STYLE;
             this.setStyle(style, {
                 config: options.config,
                 localFontFamily: this._localFontFamily,
                 localIdeographFontFamily: this._localIdeographFontFamily,
-                useServerFontComposition: this._useServerFontComposition
+                fontstackCompositing: this._fontstackCompositing
             });
         }
 
@@ -2334,12 +2338,13 @@ export class Map extends Camera {
      * });
      */
     setStyle(style: StyleSpecification | string | null, options?: SetStyleOptions): this {
-        options = Object.assign({}, {localIdeographFontFamily: this._localIdeographFontFamily, localFontFamily: this._localFontFamily, useServerFontComposition: this._useServerFontComposition}, options);
+        options = Object.assign({}, {localIdeographFontFamily: this._localIdeographFontFamily, localFontFamily: this._localFontFamily, fontstackCompositing: this._fontstackCompositing}, options);
 
         const diffNeeded =
             options.diff !== false &&
             options.localFontFamily === this._localFontFamily &&
             options.localIdeographFontFamily === this._localIdeographFontFamily &&
+            options.fontstackCompositing === this._fontstackCompositing &&
             !options.config; // Rebuild the style from scratch if config is set
 
         if (this.style && style && diffNeeded) {
@@ -2363,6 +2368,7 @@ export class Map extends Camera {
         } else {
             this._localIdeographFontFamily = options.localIdeographFontFamily;
             this._localFontFamily = options.localFontFamily;
+            this._fontstackCompositing = options.fontstackCompositing;
             return this._updateStyle(style, options);
         }
     }

test/integration/render-tests/front-cutoff/nyc-buildings/style.json

@@ -5,6 +5,7 @@
       "width": 1024,
       "height": 768,
       "allowed": 0.005,
+      "fontstackCompositing": "server",
       "operations": [
         [
           "setStyle",

test/integration/render-tests/regressions/mapbox-gl-native#11729/style.json

@@ -3,7 +3,8 @@
     "metadata": {
         "test": {
             "width": 256,
-            "height": 256
+            "height": 256,
+            "fontstackCompositing": "server"
         }
     },
     "sources": {

test/integration/render-tests/utils.ts

@@ -150,6 +150,7 @@ export async function renderMap(style, options, currentTestName) {
         scaleFactor: options.scaleFactor || 1,
         fadeDuration: options.fadeDuration || 0,
         localIdeographFontFamily: options.localIdeographFontFamily || false,
+        fontstackCompositing: options.fontstackCompositing,
         projection: options.projection,
         precompilePrograms: false,
         crossSourceCollisions: typeof options.crossSourceCollisions === "undefined" ? true : options.crossSourceCollisions,

test/unit/style/glyph_loader.test.ts

@@ -30,6 +30,33 @@ const createLoadGlyphRangeStub = (impl: typeof GlyphLoader.loadGlyphRange) => {
     return vi.spyOn(GlyphLoader, 'loadGlyphRange').mockImplementation(impl);
 };
 
+test('GlyphLoader defaults to client-side composition when constructed without options', async () => {
+    const primaryData = createMockGlyphRange([65, 66]);
+    const fallbackData = createMockGlyphRange([67]);
+    const stub = createLoadGlyphRangeStub(
+        (font: string, _range: number, _url: string, _rm: RequestManager, cb: Callback<GlyphRange>) => {
+            setTimeout(() => {
+                if (font === 'Primary') cb(null, primaryData);
+                else cb(null, fallbackData);
+            }, 0);
+        }
+    );
+
+    const loader = new GlyphLoader();
+
+    await new Promise<void>(resolve => {
+        loader.loadGlyphRange('Primary,Fallback', 0, urlTemplate, mockRequestManager, (err, result) => {
+            expect(err).toBeFalsy();
+            expect(result).toBeTruthy();
+            // Two per-font requests prove client-side composition was chosen, not a single server-side request.
+            expect(stub).toHaveBeenCalledTimes(2);
+            expect(stub).toHaveBeenCalledWith('Primary', 0, urlTemplate, mockRequestManager, expect.any(Function));
+            expect(stub).toHaveBeenCalledWith('Fallback', 0, urlTemplate, mockRequestManager, expect.any(Function));
+            resolve();
+        });
+    });
+});
+
 test('GlyphLoader loads single font directly', async () => {
     const mockData = createMockGlyphRange([65, 66, 67]);
     const stub = createLoadGlyphRangeStub(
@@ -39,7 +66,7 @@ test('GlyphLoader loads single font directly', async () => {
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {
@@ -77,7 +104,7 @@ test('GlyphLoader performs client-side composition with multiple fonts', async (
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {
@@ -109,7 +136,7 @@ test('GlyphLoader deduplicates concurrent requests for same font/range', async (
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
     const results: Array<GlyphRange | null | undefined> = [];
 
@@ -157,7 +184,7 @@ test('GlyphLoader deduplicates shared fallback fonts across different fontstacks
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {
@@ -202,7 +229,7 @@ test('GlyphLoader caches completed requests', async () => {
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     // First request
@@ -244,7 +271,7 @@ test('GlyphLoader handles partial results when one font fails', async () => {
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {
@@ -267,7 +294,7 @@ test('GlyphLoader returns error when all fonts fail', async () => {
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {
@@ -279,15 +306,15 @@ test('GlyphLoader returns error when all fonts fail', async () => {
     });
 });
 
-test('GlyphLoader uses server composition when useServerFontComposition is true', async () => {
+test('GlyphLoader uses server composition when fontstackCompositing is \'server\'', async () => {
     const mockData = createMockGlyphRange([65, 66]);
     const stub = createLoadGlyphRangeStub(
         (_font: string, _range: number, _url: string, _rm: RequestManager, cb: Callback<GlyphRange>) => {
             setTimeout(() => cb(null, mockData), 0);
         }
     );
 
-    const loader = new GlyphLoader({useServerFontComposition: true});
+    const loader = new GlyphLoader({fontstackCompositing: 'server'});
 
     await new Promise<void>(resolve => {
         loader.loadGlyphRange('Primary,Fallback', 0, urlTemplate, mockRequestManager, (err, result) => {
@@ -311,7 +338,7 @@ test('GlyphLoader trims whitespace from font names', async () => {
         }
     );
 
-    const loader = new GlyphLoader({useServerFontComposition: false});
+    const loader = new GlyphLoader({fontstackCompositing: 'client'});
 
     await new Promise<void>(resolve => {
         loader.loadGlyphRange('  Arial  ,  Fallback  ', 0, urlTemplate, mockRequestManager, (err, result) => {
@@ -344,7 +371,7 @@ test('GlyphLoader uses ascender/descender from first font that provides them', a
     );
 
     const loader = new GlyphLoader({
-        useServerFontComposition: false
+        fontstackCompositing: 'client'
     });
 
     await new Promise<void>(resolve => {