Document Google Vector Maps overlay (visgl#6066)

harisbal · Aug 9, 2021 · af0af91 · af0af91
1 parent 92e18f2
commit af0af91
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 3 deletions.
diff --git a/docs/api-reference/google-maps/google-maps-overlay.md b/docs/api-reference/google-maps/google-maps-overlay.md
@@ -1,6 +1,10 @@
 # GoogleMapsOverlay
 
-This class implements the [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/#OverlayView) interface and can be used as any other Google Maps overlay.
+This class implements the [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/overlay-view#OverlayView)/[WebglOverlayView](https://developers.google.com/maps/documentation/javascript/reference/webgl#WebglOverlayView) (depending on map rendering type) interface and can be used as any other Google Maps overlay.
+
+## Vector/Raster maps
+
+As detailed in the [overview](/docs/api-reference/google-maps/overview.md), the overlay supports both Vector and Raster Google map rendering. Depending on the Google Map configuration, the correct deck.gl overlay rendering method will be chosen at runtime.
 
 ## Usage
 
@@ -11,7 +15,8 @@ This class implements the [OverlayView](https://developers.google.com/maps/docum
   // Create map
   const map = new google.maps.Map(document.getElementById('map'), {
     center: { lat: 40, lng: -100 },
-    zoom: 5
+    zoom: 5,
+    mapId: GOOGLE_MAP_ID // Only required for Vector maps
   });
 
   // Create overlay instance

diff --git a/docs/api-reference/google-maps/overview.md b/docs/api-reference/google-maps/overview.md
@@ -29,6 +29,16 @@ npm install @deck.gl/core @deck.gl/google-maps
 import {GoogleMapsOverlay} from '@deck.gl/google-maps';
 ```
 
+## Vector/Raster maps
+
+Starting with Google Maps v3.45 there are two modes of rendering [Vector and Raster](https://developers.google.com/maps/documentation/javascript/vector-map). To control which rendering mode is used, you need to configure the Google Map using the [Google Cloud Platform](https://developers.google.com/maps/documentation/javascript/webgl).
+
+From v8.6, the `GoogleMapsOverlay` class automatically detects at runtime which rendering type is used. The Vector rendering mode is in general more performant, and the `GoogleMapsOverlay` class offers several features not available when using Raster rendering:
+
+- Shared 3D space: objects drawn by the `GoogleMapsOverlay` class appear inside the Google Maps scene, correctly intersecting with 3D buildings and behind the contextual labels drawn by Google Maps
+- Tilting and rotating the view is supported
+- Rendering uses the same WebGL context as Google Maps, improving performance
+
 ## Supported Features and Limitations
 
 Supported deck.gl features:
@@ -39,10 +49,10 @@ Supported deck.gl features:
 - Attribute transitions
 - `onHover` and `onClick` callbacks
 - Tooltip
+- Tilting & Rotation (Vector maps only)
 
 Not supported features:
 
-- Tilting
 - Views
 - Controller
 - React integration

diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -2,6 +2,20 @@
 
 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.6
+
+Release date: TBD
+
+### Google Maps + deck.gl
+
+#### @deck.gl/googlemaps
+
+[Vector rendering](https://developers.google.com/maps/documentation/javascript/vector-map) of Google Maps is now supported in by the [GoogleMapsOverlay class](/docs/api-reference/google-maps/google-maps-overlay.md), providing the following enhancements:
+
+- Shared 3D space: objects drawn by the `GoogleMapsOverlay` class appear inside the Google Maps scene, correctly intersecting with 3D buildings and behind the contextual labels drawn by Google Maps
+- Tilting and rotating the view is supported
+- Rendering uses the same WebGL context as Google Maps, improving performance
+
 ## deck.gl v8.5
 
 Release date: July 26, 2021