tile-batch

Data serializers and WebGL renderers for tiled layers in vector maps

tile-batch adds functionality to tile-gl to handle multi-tile tilesets, such as those constructed by d3-tile.

tile-batch exposes two methods:

• initSerializer: Initialize a geometry serializer, to parse GeoJSON features into buffers that can be read by tile-gl renderers
• initGLpaint: Wrap a WebGL context with methods to load the buffers to the GPU, and to construct renderers for MapLibre style layers

initSerializer

Initializes a geometry serializer, to parse GeoJSON features into buffers that can be read by tile-batch renderers

Syntax

import * as tileBatch from "tile-batch";

const serializer = tileBatch.initSerializer(parameters);

where the supplied parameters object has the following properties:

• glyphs: The glyphs property from the style document. Used for processing text labels in symbol layers
• spriteData: The data referenced in the sprite property from the style document, loaded into an object with properties { image, meta }, as returned by tile-stencil
• layers (REQUIRED): An array containing the layers from the style document that use data from a given source

API

Initialization returns a function with the following signature:

const tilePromise = serializer(source, tileCoords);

The arguments and return of this function are the same as for the corresponding function in tile-gl, except that the .buffers property of each layer has an additional buffer tileCoords, corresponding to the { x, y, z } indices of the tile

initGL

Wraps a WebGL contexts with methods to load buffers to the GPU, and to construct renderers for MapLibre style layers

Syntax

import * as tileBatch from "tile-batch";

const context = tileBatch.initGLpaint(parameters);

where the supplied parameters object has the following properties:

• .context (REQUIRED): A WebGL context wrapper, as created by the yawgl method initContext
• .framebuffer: A framebuffer object, as created by context.initFramebuffer, on which draw calls will be executed. If null, draw calls will render directly to context.gl.canvas
• .projScale: A Boolean flag indicating whether to scale style dimensions by the ratio of the projection scale at the given feature, vs the supplied scalar (e.g., the projection scale at the camera position). Default: false

API

The returned context object exposes the following methods:

• .prep(): Calls context.bindFramebufferAndSetViewport and context.clear, as prep for a draw call
• .loadBuffers(buffers): Loads the supplied buffers
• .loadAtlas(atlas): Loads a supplied atlas image object, as generated by [tile-labeler][]. Returns a link to a WebGLTexture object
• .loadSprite(image): Loads a supplied sprite image. Note: the sprite property from a style document is a URL template. The input image to .loadSprite(image) should be the actual HTMLImageElement, e.g., as loaded from the URL into spriteData.image by tile-stencil Returns a link to a WebGLTexture object
• .initPainter(style): Initializes a painter program for the given style layer. Note: the style layer must have been parsed by tile-stencil.

Signature of painter functions

The painter functions returned by the .initPainter method have the following signature:

const painter = context.initPainter(style);

painter(parameters);

where the parameters object has the following properties: { tileset, zoom, pixRatio, cameraScale }.

• tileset (IF the context was initialized with multiTile: true): An array of tileboxes. The array has global properties { translate, scale }, which can be used to compute the position of each tile within a viewport. See d3-tile for details. Each tilebox element in the array has the following properties:
  • z, x, y: The coordinates of the map tile to be rendered using this tile's data (may be different from the native coordinates of the tile)
  • tile: A tile object with properties { z, x, y, data }, as described above for single-tile rendering
• zoom: The zoom level to be used for setting zoom-dependent styles
• pixRatio: The ratio between Canvas pixel dimensions and map style dimensions. This should usually be set to window.devicePixelRatio. Default: 1.0
• cameraScale: The projection scale at the camera position. Used for scaling style dimensions by relative projection scales, IF the context was initialized with projScale: true. Default: 1.0