v8.5 what's new and upgrade guide (visgl#5952)

Author: Pessimistress

docs/api-reference/geo-layers/tile-3d-layer.md

@@ -215,6 +215,10 @@ The Tile3DLayer renders the following sublayers based on tile [format](https://g
 
 Follow [CompositeLayer](/docs/api-reference/core/composite-layer.md#_subLayerProp) and example in this layer doc to see how to override sub layer props.
 
+## Remarks
+
+- The `Tile3DLayer` can be rendered in multiple views. A tile is loaded if it is required by any of the viewports, and shared across all views via a single cache system.
+
 ## Source
 
 [modules/geo-layers/src/tile-3d-layer](https://github.com/visgl/deck.gl/tree/master/modules/geo-layers/src/tile-3d-layer)

docs/developer-guide/views.md

@@ -307,7 +307,7 @@ const deck = new Deck({
 });
 ```
 
-Some layers, including `TileLayer`, `Tile3DLayer`, `HeatmapLayer` and `ScreenGridLayer`, perform expensive operations (data fetching/aggregation) on viewport change. Therefore, it is generally NOT recommended to render them into multiple views. If you do need to show e.g. tiled base map in multiple views, create one layer instance for each view and limit their rendering with `layerFilter`:
+Some layers, including `TileLayer`, `HeatmapLayer` and `ScreenGridLayer`, perform expensive operations (data fetching/aggregation) on viewport change. Therefore, it is generally NOT recommended to render them into multiple views. If you do need to show e.g. tiled base map in multiple views, create one layer instance for each view and limit their rendering with `layerFilter`:
 
 ```js
 const deck = new Deck({
@@ -329,6 +329,8 @@ const deck = new Deck({
 });
 ```
 
+Starting with v8.5, `Tile3DLayer` supports rendering in multiple views with a single tile cache.
+
 
 ### Picking in Multiple Views
 

docs/upgrade-guide.md

@@ -8,47 +8,38 @@ The module entry point is now only lightly transpiled for the most commonly used
 
 ### Layers
 
+#### Breaking changes
+
 - A bug is fixed in projecting sizes in billboard mode. Pixel sizes now match their CSS counterparts. This change affects the following layers when used with a `MapView`:
   + `ArcLayer`, `LineLayer` and `PointCloudLayer`
   + `IconLayer` and `TextLayer` with the default `billboard` prop
   + `PathLayer` with `billboard: true`
   After upgrading to v8.5, in order to maintain the same appearance, you need to multiply `2/3` to the objects' width/size. This can be done by either changing the accessor (`getWidth`/`getSize`) or the scaling prop (`sizeScale`/`widthScale`).
-- `TextLayer`'s `backgroundColor` prop is deprecated. Use `background: true` and `getBackgroundColor` instead.
 - `TextLayer`'s default `fontSettings` have changed. When using `sdf`, the default `buffer` is now `4` and the default `radius` is now `12`.
-- `PathLayer`'s `rounded` prop is deprecated, replaced by two separate flags `jointRounded` and `capRounded`.
 - `GeoJsonLayer`'s `lineJointRounded` prop now only controls line joints. To use rounded line caps, set `lineCapRounded` to `true`.
 - Dashed lines via `PathStyleExtension` now draw rounded dash caps if `capRounded` is `true`.
-- `@deck.gl/geo-layers` now requires `@deck.gl/extensions`, due to `ClipExtension` dependency.
-- `HeatmapLayer`'s `colorDomain` prop has redefined the unit of its values. See updated layer documentation for details.
-- `MVTLayer`'s `binary` prop is now set to `true` by default.
-- `CartoBQTilerLayer` will be deprecated in 8.6. Use `CartoLayer` instead with `type` set to `MAP_TYPES.TILESET`.
-- `CartoSQLLayer` will be deprecated in 8.6. Use `CartoLayer` instead with `type` set to `MAP_TYPES.QUERY`.
-- `GeoJsonLayer`'s `getRadius` props is deprecated, replaced by `getPointRadius`.
-- It is recommended to use `zoomOffset` in the `TileLayer` when trying to affect the `zoom` resolution at which tiles are fetched.
-- `MVTLayer` and `TerrainLayer`'s default loaders no longer support parsing on the main thread. This is the same behavior as before, just dropping unused code from the bundle. Should you need to use the layers in an environment where web worker is not available, or debug the loaders, you can supply the full loader as such:
-
-  ```js
-  import {MVTLoader} from '@loaders.gl/mvt';
-  new MVTLayer({
-    loaders: [MVTLoader],
-    loadOptions: {worker: false}
-  });
-  ```
-
-  ```js
-  import {TerrainLoader} from '@loaders.gl/terrain';
-  new TerrainLayer({
-    loaders: [TerrainLoader],
-    loadOptions: {worker: false}
-  });
-  ```
+- `@deck.gl/geo-layers` now depends on `@deck.gl/extensions`.
+- `HeatmapLayer`'s `colorDomain` prop has redefined the unit of its values. See updated [layer documentation](/docs/api-reference/aggregation-layers/heatmap-layer.md) for details.
+- `MVTLayer`'s `binary` prop is now set to `true` by default to take advantage of the performance boost.
+- `TileLayer` no longer uses `tileSize` to offset zoom in non-geospatial views. It is recommended to use the new `zoomOffset` prop to affect the `zoom` resolution at which tiles are fetched.
+- `MVTLayer` and `TerrainLayer`'s default loaders no longer support parsing on the main thread. This does not change the layers' default behavior, just reduces the bundle size by dropping unused code. Should you need to use the layers in an environment where web worker is not available, or debug the loaders, follow the examples in [loaders and workers](/docs/developer-guide/loading-data.md#loaders-and-web-workers).
 - `TerrainLayer`'s `workerUrl` prop is removed, use `loadOptions.terrain.workerUrl` instead.
 
+#### Deprecations
+
+- `TextLayer`'s `backgroundColor` prop is deprecated. Use `background: true` and `getBackgroundColor` instead.
+- `PathLayer`'s `rounded` prop is deprecated, replaced by two separate flags `jointRounded` and `capRounded`.
+- `GeoJsonLayer`'s `getRadius` props is deprecated, replaced by `getPointRadius`.
+- `CartoBQTilerLayer` is deprecated and will be removed in 8.6. Use `CartoLayer` instead with `type` set to `MAP_TYPES.TILESET`.
+- `CartoSQLLayer` is deprecated and will be removed in 8.6. Use `CartoLayer` instead with `type` set to `MAP_TYPES.QUERY`.
 
 ### onError Callback
 
 `Deck`'s default `onError` callback is changed to `console.error`. Explicitly setting `onError` to `null` now silently ignores all errors, instead of logging them to console.
 
+### loaders.gl v3.0
+
+deck.gl now depends on `@loaders.gl/core@^3.0.0`. It is strongly recommended that you upgrade all loaders.gl dependencies to v3 as v2.x loaders are not tested with the v3.0 core. Visit loaders.gl's [upgrade guide](https://loaders.gl/docs/upgrade-guide) for instructions on each loader module.
 
 ### OrbitView
 

docs/whats-new.md

@@ -2,9 +2,9 @@
 
 This page contains highlights of each deck.gl release. Also check our [vis.gl blog](https://medium.com/vis-gl) for news about new releases and features in deck.gl.
 
-## deck.gl v8.5 (In development)
+## deck.gl v8.5
 
-Release date: TBD
+Release date: July 2021 (beta available)
 
 
 <table style="border: 0;" align="center">
@@ -18,7 +18,9 @@ Release date: TBD
   </tbody>
 </table>
 
-### MVTLayer performance
+### Layer Improvements
+
+#### MVTLayer
 
 Mapbox Vector Tiles parsing throughput is now 2-3x faster, due to MVT tiles being parsed directly into binary attributes rather than GeoJSON, and additional work (including [triangulation](https://github.com/visgl/loaders.gl/blob/master/docs/whats-new.md#v30-in-development)) being performed on worker threads. Speed comparison on some example data sets (MVT tiles parsed per second):
 
@@ -31,7 +33,7 @@ Mapbox Vector Tiles parsing throughput is now 2-3x faster, due to MVT tiles bein
 
 _Benchmarks ran using scripts on a 2012 MacBook Pro, 2.3 GHz Intel Core i7, 8 GB, measuring parsing time of MVTLoader only (network time and rendering is not included)_
 
-### GeoJsonLayer point types
+#### GeoJsonLayer
 
 GeoJSONLayer now supports rendering point features as icons and/or text labels in addition to circles. Use the new `pointType` prop:
 
@@ -46,23 +48,10 @@ new GeoJsonLayer({
 
 For a full list of new props, visit the updated [documentation](/docs/api-reference/layers/geojson-layer.md).
 
-### Default transpilation and bundle size
-
-The NPM distribution has dropped IE 11 support in exchange for an almost 20% reduction in size.
-
-| Entry point | 8.5 Bundle (gzipped) | 8.4 Bundle (gzipped) | Comments |
-| ---  | ---                     | ---                 | ---                 |
-| module (dist/esm)  | 398 KB (115 KB)         | 485 KB (128 KB)     | Transpiled, tree-shaking enabled   |
-| main (dist/es5)    | 686 KB (178 KB)         | 812 KB (197 KB)     | Transpiled, no tree-shaking |
-
-*Measured as the footprint of @deck.gl/core, bundled and minified with Webpack 4*
-
-To support older or less common browsers, make sure that `node_modules` is included in your application's babel settings.
-
-For backward compatibility, the pre-built bundle (`dist.min.js`) is not affected by this change.
 
+#### TextLayer
 
-### TextLayer
+The layer now supports automatically detecting the characters used in the data. Set `characterSet: 'auto'` to enable this feature.
 
 New props are added for more flexible styling of the texts:
 
@@ -74,18 +63,51 @@ New props are added for more flexible styling of the texts:
 * `getBorderWidth`
 * `getBorderColor`
 
-The layer now supports automatically detecting the characters used in the data. Set `characterSet: 'auto'` to enable this feature.
-
 See [documentation](/docs/api-reference/layers/text-layer.md) for details.
 
-### React
 
-The `DeckGL` React component is rewritten using functional component and hooks.
+#### Tile3DLayer
+
+Tile3DLayer can now be rendered in multiple views. Previously if you use multiple views it was required to create one Tile3DLayer for each view. Using a single layer is more efficient by sharing the tile cache.
 
-### Other layer improvements
+The layer now takes full advantage of new features in I3S 1.7 tile sets, including:
+  + Picking individual objects inside a tile
+  + Page nodes (improved performance)
+  + Draco compressed meshes (improved performance)
+  + Compressed textures (improved performance)
+  + PBR materials
+  + Vertex colors
+  + UVRegions
 
+
+#### Other layer improvements
+
+- `ScatterplotLayer` adds `billboard` mode
+- `TripLayer` adds `fadeTrail` mode
 - `PathLayer` now supports controlling `jointRounded` and `capRounded` separately. Dashed lines via `PathStyleExtension` also respects the cap type.
-- `PolygonLayer` and `GeoJsonLayer`: `autoHighlight` now highlights both the outline and the fill of the hovered polygon, instead of either the outline or the fill.
+- `PolygonLayer` and `GeoJsonLayer`: `autoHighlight` now highlight both the outline and the fill of the hovered polygon, instead of either the outline or the fill.
+- `HeatmapLayer` now correctly renders `aggregation: 'MEAN'` with user-supplied `colorDomain`.
+
+
+### Default transpilation and bundle size
+
+The NPM distribution has dropped IE 11 support in exchange for an almost 20% reduction in size.
+
+| Entry point | 8.5 Bundle (gzipped) | 8.4 Bundle (gzipped) | Comments |
+| ---  | ---                     | ---                 | ---                 |
+| module (dist/esm)  | 398 KB (115 KB)         | 485 KB (128 KB)     | Transpiled, tree-shaking enabled   |
+| main (dist/es5)    | 686 KB (178 KB)         | 812 KB (197 KB)     | Transpiled, no tree-shaking |
+
+*Measured as the footprint of @deck.gl/core, bundled and minified with Webpack 4*
+
+To support older or less common browsers, make sure that `node_modules` is included in your application's babel settings.
+
+For backward compatibility, the pre-built bundle (`dist.min.js`) is not affected by this change.
+
+
+### @deck.gl/react
+
+The `DeckGL` React component is rewritten using functional component and hooks.
 
 
 ### @deck.gl/carto