Skip to content

Commit

Permalink
docs: v9 updates (#8455)
Browse files Browse the repository at this point in the history 
Co-authored-by: felixpalmer <felixpalmer@gmail.com>
Co-authored-by: Xiaoji Chen <Pessimistress@users.noreply.github.com>
  • Loading branch information
@ibgreen @felixpalmer @Pessimistress
3 people committed Mar 16, 2024
1 parent 04fc4ad commit aa49b23
Showing 1 changed file with 101 additions and 64 deletions.
165 changes: 101 additions & 64 deletions docs/upgrade-guide.md
View file
Expand Up @@ -2,23 +2,59 @@

## Upgrading to v9.0

### Custom Layers
### General changes

Create models with device instead of gl.
- `Deck.pickObjects()` - minor breaking change: if the same `data` is used by multiple top-level layers (e.g. a `ScatterplotLayer` and a `TextLayer`) that are visible in the picking bounds, `pickObjects` will yield one result for each picked object+layer combination, instead of one result for each picked object in previous versions.

```typescript
// luma.gl v9
new Model(this.context.device, {opts});
// luma.gl v8
new Model(this.context.gl, {opts});
```
### Typescript

Typescript is now enabled on all modules. The `'@deck.gl/xxx/typed'` packages are removed.

### luma.gl v9 Updates

The biggest changes in deck.gl v9 are due to the upgrade to the luma.gl v9 API. Fortunately, deck.gl encapsulates most of the luma.gl API so the changes to deck.gl applications should be limited, in particular if the application does not define its own custom layers.

Quick summary:

- All direct references to `gl: WebGLRenderingContext` should be replaced with `device: Device` references. `import {Device} from '@luma.gl/core'`.
- GPU resource classes should no longer be created directly. Use `device.createBuffer()`, `device.createTexture()` etc.
- luma.gl no longer uses `GL` constants for GPU parameters, but instead uses (WebGPU style) string constants. Applications should no longer import `@luma.gl/constants`.

For details, refer to the [luma.gl v9 Upgrade Guide](https://luma.gl/docs/upgrade-guide)

**Deck**

| v8 API | v9 API | Description |
| ------------------------------- | ----------------------------- | ----------- |
| `props.onWebGLInitialized(...)` | `props.onDeviceInitialized()` | |


**Layer**

| v8 API | v9 API | Description |
| ---------------------------------- | -------------------------------------- | ------------------------- |
| `props.parameters: {GL constants}` | `props.parameters({string constants})` | Use new string constants. |


**Custom Layers**

Model creation needs to adapt to the [luma.gl v9 API](https://luma.gl/docs/upgrade-guide).

| v8 API | v9 API | Description |
| ------------------------------------ | ---------------------------------------- | --------------------------------------------- |
| `new Model(this.context.gl, {opts})` | `new Model(this.context.device, {opts})` | Create models with `device`` instead of `gl`. |

**Custom Shaders**

- deck.gl no longer supports GLSL 1.00 shaders. All shaders must be updated to GLSL 3.00.

- drawModes `GL.TRIANGLE_FAN` and `GL.LINE_LOOP` are not supported on WebGPU. Select different topology when creating geometries.
**WebGPU preparation**

### Deck
While the 9.0 release of deck.gl does not yet support WebGPU, our goal is to enable WebGPU soon in a 9.x release. A number of changes will be required to deck.gl applications beyond the upgrades listed above. Again, these changes mostly affect customer layers.

- `Deck.pickObjects` minor breaking change: if the same `data` is used by multiple top-level layers (e.g. a `ScatterplotLayer` and a `TextLayer`) that are visible in the picking bounds, `pickObjects` will yield one result for each picked object+layer combination, instead of one result for each picked object in previous versions.
- deck.gl now uses uniform buffers instead of global uniforms. It is not yet required to use uniform buffers but it will be necessary if you would like to run deck.gl on WebGPU in future releases.
- drawModes `GL.TRIANGLE_FAN` and `GL.LINE_LOOP` are not supported on WebGPU. Select a different topology when creating geometries.
- The luma picking module now [uses uniform buffers](https://github.com/visgl/luma.gl/blob/master/modules/shadertools/src/modules/engine/picking/picking.ts#L34-L50). To access picking state in shaders use `picking.isActive` rather than `picking_isActive`

### @deck.gl/mapbox

Expand Down Expand Up @@ -70,6 +106,7 @@ const layer = new CartoLayer({
- `GoogleMapsOverlays` now also triggers `onClick` for rightclick events. To filter out these events check for `event.srcEvent.domEvent.button === 2` in `onClick`.
- Some dependencies are upgraded to their next major version, including `@mapbox/tiny-sdf` and `d3-*`. This upgrade is necessary because certain security vulnerabilities in these packages are only fixed in the latest versions. Unfortunately, they became [ES modules](https://nodejs.org/api/packages.html) and no longer support `require()` from the commonjs entry point. This will break Server Side Rendering in frameworks such as Next.js. To mitigate this, you must exclude deck.gl from SSR either by framework config or by using dynamic import. See [here](./get-started/using-with-react.md#using-deckgl-with-ssr) for details.

---

## Upgrading from deck.gl v8.7 to v8.8

Expand Down Expand Up @@ -438,17 +475,17 @@ See [View class](./api-reference/core/view.md) documentation for details.
- `ScreenGridLayer`: support is now limited to browsers that implement either WebGL2 or the `OES_texture_float` extension. [coverage stats](https://webglstats.com/webgl/extension/OES_texture_float)
- Some shader attributes are renamed for consistency:

| Layer | Old | New |
| ----- | --- | --- |
| `LineLayer` | `instanceSourceTargetPositions64xyLow.xy` | `instanceSourcePositions64xyLow` |
| | `instanceSourceTargetPositions64xyLow.zw` | `instanceTargetPositions64xyLow` |
| `PathLayer` | `instanceLeftStartPositions64xyLow.xy` | `instanceLeftPositions64xyLow` |
| | `instanceLeftStartPositions64xyLow.zw` | `instanceStartPositions64xyLow` |
| | `instanceEndRightPositions64xyLow.xy` | `instanceEndPositions64xyLow` |
| | `instanceEndRightPositions64xyLow.zw` | `instanceRightPositions64xyLow` |
| `ArcLayer` | `instancePositions64Low` | `instancePositions64xyLow` |
| `ScenegraphLayer` | `instancePositions64xy` | `instancePositions64xyLow` |
| `SimpleMeshLayer` | `instancePositions64xy` | `instancePositions64xyLow` |
| Layer | Old | New |
| ----------------- | ----------------------------------------- | -------------------------------- |
| `LineLayer` | `instanceSourceTargetPositions64xyLow.xy` | `instanceSourcePositions64xyLow` |
| | `instanceSourceTargetPositions64xyLow.zw` | `instanceTargetPositions64xyLow` |
| `PathLayer` | `instanceLeftStartPositions64xyLow.xy` | `instanceLeftPositions64xyLow` |
| | `instanceLeftStartPositions64xyLow.zw` | `instanceStartPositions64xyLow` |
| | `instanceEndRightPositions64xyLow.xy` | `instanceEndPositions64xyLow` |
| | `instanceEndRightPositions64xyLow.zw` | `instanceRightPositions64xyLow` |
| `ArcLayer` | `instancePositions64Low` | `instancePositions64xyLow` |
| `ScenegraphLayer` | `instancePositions64xy` | `instancePositions64xyLow` |
| `SimpleMeshLayer` | `instancePositions64xy` | `instancePositions64xyLow` |


#### @deck.gl/json
Expand All @@ -467,11 +504,11 @@ See [View class](./api-reference/core/view.md) documentation for details.

Following `Layer` class methods have been removed :

| Removed | Alternate | Comment |
| --- | --- | --- |
| `use64bitProjection` | use `Fp64Extension` | details in `fp64 prop` section below |
| `is64bitEnabled` | use `Fp64Extension` | details in `fp64 prop` section below |
| `updateAttributes` | `_updateAttributes` | method is renamed |
| Removed | Alternate | Comment |
| -------------------- | ------------------- | ------------------------------------ |
| `use64bitProjection` | use `Fp64Extension` | details in `fp64 prop` section below |
| `is64bitEnabled` | use `Fp64Extension` | details in `fp64 prop` section below |
| `updateAttributes` | `_updateAttributes` | method is renamed |


##### fp64 prop
Expand Down Expand Up @@ -762,10 +799,10 @@ new MapView().makeViewport({width, height, viewState: {longitude, latitude, zoom

### Layer properties

| Layer | Removed Prop | New Prop | Comment |
| --- | --- | --- | --- |
| `ArcLayer` | `strokeWidth` | `getStrokeWidth` | Can be set to constant value |
| `LineLayer` | `strokeWidth` | `getStrokeWidth` | Can be set to constant value |
| Layer | Removed Prop | New Prop | Comment |
| ----------- | ------------- | ---------------- | ---------------------------- |
| `ArcLayer` | `strokeWidth` | `getStrokeWidth` | Can be set to constant value |
| `LineLayer` | `strokeWidth` | `getStrokeWidth` | Can be set to constant value |


### Pure JS applications
Expand Down Expand Up @@ -817,29 +854,29 @@ deck.gl 4.1 requires luma.gl as peer dependency, but 5.0 specifies it as a norma

Coordinate system related props have been renamed for clarity. The old props are no longer supported and will generate errors when used.

| Layer | Removed Prop | New Prop | Comment |
| --- | --- | --- | --- |
| Layer | `projectionMode` | `coordinateSystem` | Any constant from `COORDINATE_SYSTEM` |
| Layer | `projectionOrigin` | `coordinateOrigin` | [lng, lat] |
| Layer | Removed Prop | New Prop | Comment |
| ----- | ------------------ | ------------------ | ------------------------------------- |
| Layer | `projectionMode` | `coordinateSystem` | Any constant from `COORDINATE_SYSTEM` |
| Layer | `projectionOrigin` | `coordinateOrigin` | [lng, lat] |

Note; There is also an important semantical change in that using `coordinateSystem` instead of `projectionMode` causes the superimposed `METER_OFFSET` system's y-axis to point north instead of south. This was always the intention so in some sense this was regarded as a bug fix.

### DeckGL component

Following methods and props have been renamed for clarity. The semantics are unchanged. The old props are still available but will generate a deprecation warning.

| Old Method | New Method | Comment |
| --- | --- | --- |
| `queryObject` | `pickObject` | These names were previously aligned with react-map-gl, but ended up confusing users. Since rest of the deck.gl documentation talks extensively about "picking" it made sense to stay with that terminology. |
| `queryVisibleObjects` | `pickObjects` | The word "visible" was intended to remind the user that this function only selects the objects that are actually visible in at least one pixel, but again it confused more than it helped. |
| Old Method | New Method | Comment |
| --------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryObject` | `pickObject` | These names were previously aligned with react-map-gl, but ended up confusing users. Since rest of the deck.gl documentation talks extensively about "picking" it made sense to stay with that terminology. |
| `queryVisibleObjects` | `pickObjects` | The word "visible" was intended to remind the user that this function only selects the objects that are actually visible in at least one pixel, but again it confused more than it helped. |

### Removed picking Uniforms

| Removed uniform | Comment |
| --- | --- |
| renderPickingBuffer |[picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking)|
| pickingEnabled |[picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking)|
| selectedPickingColor |[picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking)|
| Removed uniform | Comment |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| renderPickingBuffer | [picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking) |
| pickingEnabled | [picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking) |
| selectedPickingColor | [picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking) |


The shader uniforms are used for implementing picking in custom shaders, these uniforms are no longer set by the deck.gl. Custom shaders can now use luma.gl [picking shader module](https://github.com/visgl/luma.gl/tree/5.0-release/src/shadertools/modules/picking).
Expand All @@ -849,10 +886,10 @@ The shader uniforms are used for implementing picking in custom shaders, these u

Following WebGL parameters are set during DeckGL component initialization.

| WebGL State | Value |
|---- |---- |
| depthTest | true |
| depthFunc | gl.LEQUAL |
| WebGL State | Value |
| ----------------- | ---------------------------------------------------------------------- |
| depthTest | true |
| depthFunc | gl.LEQUAL |
| blendFuncSeparate | [gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA] |

All our layers enable depth test so we are going set this state during initialization. We are also changing blend function for more appropriate rendering when multiple elements are blended.
Expand Down Expand Up @@ -937,11 +974,11 @@ const model = new Model({

### Removed Layers

| Layer | Status | Replacement |
| --- | --- | --- |
| `ChoroplethLayer` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ChoroplethLayer64` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ExtrudedChoroplethLayer` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| Layer | Status | Replacement |
| ------------------------- | ------- | ---------------------------------------------- |
| `ChoroplethLayer` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ChoroplethLayer64` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ExtrudedChoroplethLayer` | Removed | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |

* ChoroplethLayer, ChoroplethLayer64, ExtrudedChoroplethLayer

Expand All @@ -966,12 +1003,12 @@ While it would have been preferable to avoid this change, a significant moderniz

### Deprecated/Removed Layers

| Layer | Status | Replacement |
| --- | --- | --- |
| `ChoroplethLayer` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ChoroplethLayer64` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ExtrudedChoroplethLayer` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `EnhancedChoroplethLayer` | Moved to examples | `PathLayer` |
| Layer | Status | Replacement |
| ------------------------- | ----------------- | ---------------------------------------------- |
| `ChoroplethLayer` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ChoroplethLayer64` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `ExtrudedChoroplethLayer` | Deprecated | `GeoJsonLayer`, `PolygonLayer` and `PathLayer` |
| `EnhancedChoroplethLayer` | Moved to examples | `PathLayer` |

* ChoroplethLayer, ChoroplethLayer64, ExtrudedChoroplethLayer

Expand All @@ -989,13 +1026,13 @@ Developers can either copy this layer from the example folder into their applica

### Removed, Changed and Deprecated Layer Properties

| Layer | Old Prop | New Prop | Comment |
| --- | --- | --- | --- |
| Layer | Old Prop | New Prop | Comment |
| ---------------- | -------------- | ---------------- | -------------------------------- |
| Layer | `dataIterator` | N/A | Prop was not functional in v3 |
| ScatterplotLayer | `radius` | `radiusScale` | Default has changed from 30 to 1 |
| ScatterplotLayer | `drawOutline` | `outline` | |
| ScreenGridLayer | `unitWidth` | `cellSizePixels` | |
| ScreenGridLayer | `unitHeight` | `cellSizePixels` | | |
| ScatterplotLayer | `drawOutline` | `outline` | |
| ScreenGridLayer | `unitWidth` | `cellSizePixels` | |
| ScreenGridLayer | `unitHeight` | `cellSizePixels` | | |


#### Note about `strokeWidth` props
Expand Down

0 comments on commit aa49b23

Please sign in to comment.