Mapbox GL JS

Vector tile rendering in Mapbox GL JS is a multi-stage process that splits heavy computation (parsing and layout) onto WebWorker threads to keep the main thread responsive.

1. Parsing and Layout (Worker Thread)

Vector tiles are fetched and processed in WebWorkers through the following steps:

• Deserialization: Source layers, feature properties, and geometries are extracted from the PBF format (using @mapbox/vector-tile).
• Layout: Data is transformed into render-ready formats used by WebGL shaders. This is managed by WorkerTile, Bucket classes, and ProgramConfiguration.
• Indexing: Geometries are indexed into a FeatureIndex to enable spatial queries like queryRenderedFeatures.
• Bucketing: WorkerTile#parse() creates a Bucket for each 'family' of style layers that share the same underlying features and layout properties.

2. Rendering (Main Thread)

Once layout is complete, data is transferred to the main thread. The Bucket serves as the single point of knowledge for turning vector tiles into WebGL buffers, holding vertex and element array data in ArrayGroup objects.

Rendering follows this flow:

• Pass Management: Painter#renderPass() iterates through style layers.
• Layer Drawing: The painter delegates to layer-specific drawXxxx() methods (e.g., drawLine, drawSymbol).
• WebGL Execution: For each tile, the drawer obtains a shader program from the Painter, sets uniform values based on style properties, binds layout buffer data via BufferGroup, and executes gl.drawElements().

Mapbox GL Shaders use pragmas to abstract over how variables are declared based on their context (e.g., whether they are uniforms, attributes, or varyings). This allows you to write shader code that works regardless of whether a variable is constant for all features or unique to each feature.

Pragma Syntax

Pragmas follow this pattern: #pragma mapbox: (define|initialize) (lowp|mediump|highp) (float|vec2|vec3|vec4) {name}

Usage Requirements

To correctly use pragma-defined variables, you must follow these rules:

1. Dual Declaration: Every variable must have both a define pragma and an initialize pragma.
2. Scope:
   • define pragmas must be placed in the file scope.
   • initialize pragmas must be placed in the function scope (e.g., inside main()).
3. Vertex/Fragment Synchronization: If a variable is defined and initialized in the fragment shader, it must also be defined and initialized in the vertex shader. This is because attributes are not directly accessible from the fragment shader and must be passed through via interpolation.

#pragma mapbox: define highp vec4 color

main() {
    #pragma mapbox: initialize highp vec4 color
    // ... logic to set color ...
    gl_FragColor = color;
}

The project uses a highly customized ESLint configuration designed for TypeScript and browser compatibility. It enforces strict JSDoc requirements for core files, manages specific import restrictions to ensure bundle compatibility (e.g., preventing process.env or import.meta.url in UMD bundles), and includes custom Mapbox rules.

Key configuration aspects include:

• Strict JSDoc: Enforced on core files like src/index.ts and src/ui/** to ensure high-quality documentation.
• Browser Compatibility: Rules are configured to prevent the use of Node.js-specific globals or syntax that would break browser bundles.
• TypeScript Integration: Uses typescript-eslint with type-checked rules.
• Custom Rules: Includes mapbox/devtools-must-use-debug-run and mapbox/no-object-methods-on-collections.
• File-Specific Overrides: Different rules apply to DEV_FILES, STRICT_JSDOC_FILES, and UNTYPED_FILES to balance strictness with developer velocity.