mapbox / mapbox/mapbox-gl-js

CustomLayerInterface to expose projection matrix parameters

Open
#12,888 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

## Motivation

For our [custom layer implementation](https://deck.gl/docs/api-reference/mapbox/overview) to properly match the base map in an interleaved 3D context, we need access to the projection matrix parameters.

`CustomLayerInterface.render` currently exposes a single `matrix` argument that is the combined view projection matrix. In our implementation, coordinate transforms are done on the GPU for better performance, but shader uniforms only support up to 32-bit floats. To compensate for lost precision, we calculate the view matrix and projection matrix separately.

Historically we poke into the source code of the `Transform` class to try match our calculation with the base map. This has become increasingly problematic as the base map could change its near/far plane calculation between versions. It would be much easier if `CustomLayerInterface.render` could expose the view and projection matrices separately, or even the individual projection matrix parameters (fov, near, far).

## Design Alternatives

A non-breaking API change could be adding a third parameter to `CustomLayerInterface.render`:

```js
render(gl: WebGLRenderingContext, matrix: number[], transform: {
pixelMatrix: number[];
projMatrix: number[];
...
})
```

### Implementation

The separate matrices and nearZ/farZ etc. are already stored in `map.transform` as private properties. Making them visible to a custom layer has minimal overhead but will help create much more robust third-party renderers.

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 locating CustomLayerInterface.render and the map.transform data mentioned in the issue, then trace how the existing combined matrix is supplied. Define the non-breaking API shape, expose the needed separate matrices or projection parameters, and verify that existing custom layers remain compatible.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, computer-graphics
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.