tile-batch

!tests

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][MapLibre]

[tile-gl]: https://github.com/GlobeletJS/tile-gl/
[d3-tile]: https://github.com/d3/d3-tile
[MapLibre]: https://maplibre.org/maplibre-gl-js-docs/style-spec/layers/

initSerializer

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

$3

``javascript
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][MapLibre] from
the style document that use data from a given [source][]

[glyphs]: https://maplibre.org/maplibre-gl-js-docs/style-spec/glyphs/
[sprite]: https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/
[tile-stencil]: https://github.com/GlobeletJS/tile-stencil/
[source]: https://maplibre.org/maplibre-gl-js-docs/style-spec/sources/

$3


Initialization returns a function with the following signature:
`javascript
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][MapLibre]

$3

`javascript
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

[yawgl]: https://github.com/GlobeletJS/yawgl

$3


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][].

[WebGLTexture object]: https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture
[sprite property]: https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/
[HTMLImageElement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement

$3

The painter functions returned by the .initPainter method have the following
signature:
`javascript
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

[tile-mixer]: https://github.com/GlobeletJS/tile-mixer
[d3-tile]: https://github.com/d3/d3-tile
[window.devicePixelRatio]: https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio