Page Summary

outlined_flag

• WebGL Overlay View empowers you to seamlessly integrate 3D and 2D content into Google Maps using WebGL directly or via libraries like Three.js, leveraging the same rendering context for synchronized visuals and depth occlusion with buildings.

• It's crucial to load the map with a vector map enabled map ID, ideally with tilt and rotation activated, to fully utilize 3D camera control and functionalities.

• WebGL Overlay View offers lifecycle hooks likeonAdd,onContextRestored,onDraw,onContextLost,onStateUpdate, andonRemove, providing control over setup, rendering, and teardown of your overlay elements.

• Remember to reset the GL state after rendering using methods likerenderer.resetState() (Three.js) to avoid rendering conflicts and ensure proper functionality.

• Utilize thecoordinateTransformer.fromLatLngAltitude() helper function withinonDraw to transform latitude/longitude/altitude coordinates to world/camera/screen space for accurate object placement and georeferencing.

View Sample

With WebGL Overlay View you can add content to your maps using WebGL directly,or popular Graphics libraries like Three.js. WebGL Overlay View provides directaccess to the same WebGL rendering context Google Maps Platform uses to renderthe vector basemap. This use of a shared rendering context provides benefitssuch as depth occlusion with 3D building geometry, and the ability to sync 2D/3Dcontent with basemap rendering. Objects rendered with the WebGL Overlay View canalso be tied to latitude/longitude coordinates, so they move when you drag,zoom, pan, or tilt the map.

Requirements

To use WebGL Overlay View, you must load the map using a map ID with the vectormap enabled. We strongly recommend enabling tilt and rotation when you createthe map ID, to allow for full 3D camera control.See the overview for details.

Add WebGL Overlay View

To add the overlay to your map, implementgoogle.maps.WebGLOverlayView, thenpass it your map instance usingsetMap:

// Create a map instance.constmap=newgoogle.maps.Map(mapDiv,mapOptions);// Create a WebGL Overlay View instance.constwebglOverlayView=newgoogle.maps.WebGLOverlayView();// Add the overlay to the map.webglOverlayView.setMap(map);

Lifecycle hooks

WebGL Overlay View provides a set of hooks that are called at various times inthe lifecycle of the WebGL rendering context of the vector basemap. Theselifecycle hooks are where you setup, draw, and tear down anything you wantrendered in the overlay.

• onAdd() is called when the overlay is created. Use it to fetch orcreate intermediate data structures before the overlay is drawn that don’trequire immediate access to the WebGL rendering context.
• onContextRestored({gl}) is called once the rendering context isavailable. Use it to initialize or bind any WebGL state such as shaders, GLbuffer objects, and so on.onContextRestored() takes aWebGLStateOptionsinstance, which has a single field:
  • gl is a handle to theWebGLRenderingContext used by the basemap.
• onDraw({gl, transformer}) renders the scene on the basemap.The parameters foronDraw() is aWebGLDrawOptions object, which has twofields:
  • gl is a handle to theWebGLRenderingContext used by the basemap.
  • transformer provides helper functions to transform from mapcoordinates to model-view-projection matrix, which can be used totranslate map coordinates to world space, camera space, and screenspace.
• onContextLost() is called when the rendering context is lost for anyreason, and is where you should clean up any pre-existing GL state, since itis no longer needed.
• onStateUpdate({gl}) updates the GL state outside of the render loop,and is invoked whenrequestStateUpdate is called. It takes aWebGLStateOptions instance, which has a single field:
  • gl is a handle to theWebGLRenderingContext used by the basemap.
• onRemove() is called when the overlay is removed from the map withWebGLOverlayView.setMap(null), and is where you should remove allintermediate objects.

For example, the following is a basic implementation of all lifecycle hooks:

constwebglOverlayView=newgoogle.maps.WebGLOverlayView();webglOverlayView.onAdd=()=>{// Do setup that does not require access to rendering context.}webglOverlayView.onContextRestored=({gl})=>{// Do setup that requires access to rendering context before onDraw call.}webglOverlayView.onStateUpdate=({gl})=>{// Do GL state setup or updates outside of the render loop.}webglOverlayView.onDraw=({gl,transformer})=>{// Render objects.}webglOverlayView.onContextLost=()=>{// Clean up pre-existing GL state.}webglOverlayView.onRemove=()=>{// Remove all intermediate objects.}webglOverlayView.setMap(map);

Resetting GL State

WebGL Overlay View exposes the WebGL rendering context of the basemap. Becauseof this, it is extremely important that you reset the GL state to its originalstate when you are done rendering objects. Failure to reset the GL state islikely to result in GL state conflicts, which will cause rendering of both themap and any objects you specify to fail.

Resetting the GL state is normally handled in theonDraw() hook. For example,Three.js provides a helper function that clears any changes to the GL state:

webglOverlayView.onDraw=({gl,transformer})=>{// Specify an object to render.renderer.render(scene,camera);renderer.resetState();}

If the map or your objects fail to render, it is very likely that the GL statehas not been reset.

Coordinate Transformations

The position of an object on the vector map is specified by providing acombination of latitude and longitude coordinates, as well as altitude. 3Dgraphics, however, are specified in world space, camera space, or screen space.To make it easier to transform map coordinates to these more commonly usedspaces, WebGL Overlay View provides thecoordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr,scalarArr) helper function in theonDraw() hook that takes the following andreturns aFloat64Array:

• latLngAltitude: Latitude/longitude/altitude coordinates either as aLatLngAltitude orLatLngAltitudeLiteral.
• rotationArr:Float32Array of euler rotation angles specified in degrees.
• scalarArr:Float32Array of scalars to apply to the cardinal axis.

For example, the following usesfromLatLngAltitude() to create a cameraprojection matrix in Three.js:

constcamera=newTHREE.PerspectiveCamera();constmatrix=coordinateTransformer.fromLatLngAltitude({lat:mapOptions.center.lat,lng:mapOptions.center.lng,altitude:120,});camera.projectionMatrix=newTHREE.Matrix4().fromArray(matrix);

Example

The following is a simple example of usingThree.js, apopular, open source WebGL library, to place a 3D object on the map. For acomplete walkthrough of using WebGL Overlay View to build the example you seerunning at the top of this page, try theBuilding WebGL-accelerated Map Experiences codelab.

constwebglOverlayView=newgoogle.maps.WebGLOverlayView();letscene,renderer,camera,loader;webglOverlayView.onAdd=()=>{// Set up the Three.js scene.scene=newTHREE.Scene();camera=newTHREE.PerspectiveCamera();constambientLight=newTHREE.AmbientLight(0xffffff,0.75);// Soft white light.scene.add(ambientLight);// Load the 3D model with GLTF Loader from Three.js.loader=newGLTFLoader();loader.load("pin.gltf");}webglOverlayView.onContextRestored=({gl})=>{// Create the Three.js renderer, using the// maps's WebGL rendering context.renderer=newTHREE.WebGLRenderer({canvas:gl.canvas,context:gl,...gl.getContextAttributes(),});renderer.autoClear=false;}webglOverlayView.onDraw=({gl,transformer})=>{// Update camera matrix to ensure the model is georeferenced correctly on the map.constmatrix=transformer.fromLatLngAltitude({lat:mapOptions.center.lat,lng:mapOptions.center.lng,altitude:120,});camera.projectionMatrix=newTHREE.Matrix4().fromArray(matrix);// Request a redraw and render the scene.webglOverlayView.requestRedraw();renderer.render(scene,camera);// Always reset the GL state.renderer.resetState();}// Add the overlay to the map.webglOverlayView.setMap(map);