At Google I/O 2021, we announced the beta release of Tilt and Rotation, and Webgl Overlay View, which give you a fundamentally new way to build mapping experiences. You may be familiar with the existing Overlay View feature of the Maps JavaScript API that lets you render in a transparent layer that sits on top of the map. For years, developers have been using Overlay View to draw in two dimensions over the top of the map, but for as much as you can do with Overlay View, it only allows you to render on a transparent layer that effectively floats above the map.

In contrast, WebGL Overlay View gives you direct hooks into the lifecycle of the exact same WebGL rendering context we use to render the vector basemap. This means that for the first time ever, you can performantly render two and three dimensional objects directly on the map, enabling you to build experiences that were previously impossible with the Maps JavaScript API.

Today, we’re going to give you a quick overview of the new WebGL-powered features of the Maps JavaScript API, so that you have all the knowledge you need to get started creating next generation mapping experiences.

What is WebGL?

WebGL is a low-level browser API, originally authored by the Mozilla Foundation, that gives you access to the rendering and processing power of the graphics processing unit (GPU) on client devices, such as mobile phones and computers, in your web apps. On its own, the browser is not able to handle the heavy computation needed to render objects in 3D space, but using WebGL it is able to pass those processes off to be handled by the GPU, which is purpose built to handle such computations.

To learn more about WebGL, check out the documentation from the Khronos Group, the designers and maintainers of WebGL.

Requirements

To use WebGL Overlay View, you’ll need a Map ID with the vector map enabled. It’s also strongly recommended that you enable Tilt and Rotation when you create your Map ID, otherwise your map will be constrained to the default top-down view - in short, you won’t be able to move your map in three-dimensions. 

To learn more about using Map IDs and the vector map, see the documentation.

Setting Tilt and Rotation

To load your map with a set tilt and rotation, you can provide a value for the `tilt` and `heading` properties when you create the map:

const mapOptions = {
  mapId: "15431d2b469f209e",
  tilt: 0,
  heading: 0,
  zoom: 17,
  center: {
    lat: -33.86957547870852, 
    lng: 151.20832318199652
  }
}
const mapDiv = document.getElementById("map");
const map = new google.maps.Map(mapDiv, mapOptions);

Tilt is specified as a number or float in degrees between 0 and 67.5, with 0 degrees being the default straight down view and 67.5 being the maximum tilt. The available  maximum tilt also varies by zoom level. 

The rotation is set in the heading property as a number or float between 0 and 360 degrees, where 0 is true north.

You can also change the tilt and rotation programmatically at runtime whenever you want by calling `setTilt` and `setHeading` directly on the map object. This is useful if you want to change the orientation of the map in response to events like user interactions.

map.setTilt(45);
map.setHeading(180);

In addition, your users can manually control the tilt and rotation of the map by holding the key and dragging with the mouse or using the arrow keys.

For more information on Tilt and Rotation, see the documentation.

Adding WebGL Overlay View to the Map

WebGL Overlay View is made available in the Maps JavaScript API by creating an instance of `google.maps.WebglOverlayView`. Once an instance of the overlay is created, you simply need to call `setMap` on the instance to apply it to the map.

const webglOverlayView = new google.maps.WebglOverlayView;
webglOverlayView.setMap(map);

To give you access to the WebGL rendering context of the map and handle any objects you want to render there, WebGL Overlay View exposes a set of five hooks into the lifecycle of the WebGL rendering context of the vector basemap.

Here’s a quick rundown:

• `onAdd` is where most of your pre-processing should be done, like fetching and creating intermediate data structures to eventually pass to the overlay. The reason to do all of that here is to ensure you don’t bog down the rendering of the map.

• `onRemove` is where you’ll want to destroy all intermediate objects, though it would be nice if you did it sooner.

• `onContextRestored` is called before the map is rendered and is where you should initialize, bind, reinitialize or rebind any WebGL state, such as shaders, GL buffer objects, etc.

• `onDraw` is where we actually render the map, as well as anything that you specify in this hook. You should try to execute the minimal set of draw calls to render your scene. If you try to do too much here you’ll bog down both the rendering of the basemap and anything you’re trying to do with WebGL, and trust me, no one wants that.

• `onContextLost` is where you’ll want to clean up any state associated with pre-existing GL state, since at this point the WebGL context will have been destroyed, so it’ll be garbage.

To implement these hooks, set them to a function, which the Maps JavaScript API will execute at the appropriate time in the WebGL rendering context lifecycle. For example:

webglOverlayView.onDraw = (gl,
coordinateTransformer) => { //do some
rendering }

For more information on using WebGL Overlay View and its lifecycle hooks, check out the documentation.

Creating Camera Animations

As part of the beta release of WebGL Overlay View, we’re also introducing `moveCamera`, a new integrated camera control that you can use to set the position, tilt, rotation, and zoom of the camera position simultaneously. Like `setTilt` and `setHeading`, `moveCamera` is called directly on the `Map` object.

By making successive calls to `moveCamera` in an animation loop you can also create smooth animations between camera positions. For example, here we are using the browser’s `requestAnimationFrame` API to change the tilt and rotation each frame:

const cameraOptions = {
  tilt: 0,
  heading: 0
}

function animateCamera () {
  cameraOptions.tilt += 1;
  cameraOptions.heading += 1;
  map.moveCamera(cameraOptions);
}

requestAnimationFrame(animateCamera);

Plus, all of these adjustments, including zoom, support floats, which means not only can you control the camera like never before, you can also do it with a high degree of precision.

For more information on `moveCamera`, see the documentation.

Give it a try

You can try the new WebGL-powered features of the Maps JavaScript API right now by loading the API from the beta channel. We’ve got a new codelab, and documentation with all the details, as well as sample code and end-to-end example apps to help you get started. Also, be sure to check out our feature tour and travel demos to learn more and play with a real implementation of these features.

And let us know what you think by reporting through our issue tracker. We need your bug reports, your feature requests, and your feedback to help us test and improve the new WebGL-based map features. 

Have fun building with the map in 3D—we can’t wait to see the amazing things you’ll build.

For more information on Google Maps Platform, visit our website.