tile-batch/README.md

Data serializers and WebGL renderers for tiled layers in vector maps

# tile-batch

![tests](https://github.com/GlobeletJS/tile-batch/actions/workflows/node.js.yml/badge.svg)

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

### Syntax
```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/

### API
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]

### Syntax
```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

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

[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

### Signature of painter functions
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