mapbox / mapbox/mapbox-gl-js

Callback-based canvas source (or layer) API

Open
#5,557 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

api :memo: feature :green_apple:
Dominant language
TypeScript
Stars
12.4k
Forks
2.4k
PR merge metrics
No merged PRs in 30d

Description

[CanvasSource](https://www.mapbox.com/mapbox-gl-js/api/#canvassource) allows users to create raster layers that use the contents of an arbitrary HTML Canvas element. However, like [ImageSource](https://www.mapbox.com/mapbox-gl-js/api/#imagesource), this API is currently oriented towards drawing into the fixed geographical area (determined by the `coordinates` option). This works well for drawing (possibly animated) graphics in a specific place, but it's not well suited to drawing graphics that "follow" the map, responding in realtime to camera movement.

To that end, I tentatively propose that we provide an API that allows users to provide a `render: (CameraState) => void` callback in addition to an HTML Canvas element. Our rendering pipeline would call the callback on every frame before reading data from the canvas. The canvas data would be assumed to be coincident with the map's viewport.

We could expose such an API by:

1. _Extending the `CanvasSource` API:_ Allow users to specify _either_ `coordinates:` _or_ `render: (CameraState) => void`.
2. _Adding a new source type:_ Like 1, but make it a separate source type.
3. _Adding a new layer type:_ Options 1 and 2 treat the canvas as a _source_ that can be targeted by `raster` layers. Instead, we could expose a `CanvasLayer` that provides the canvas element and `render` callback.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the CanvasSource and ImageSource APIs, raster layers, and the rendering pipeline described in the issue. Compare the proposed CanvasSource, new source type, and CanvasLayer approaches, then define which API should support a CameraState render callback before canvas data is read on each frame.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
computer-graphics, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.