WebGL-Overlay-Ansicht

Beispiel ansehen

Mit WebGL Overlay View lassen sich Ihren Karten Inhalte hinzufügen. Dazu können Sie WebGL direkt oder gängige Grafikbibliotheken wie Three.js verwenden. WebGL Overlay View bietet direkten Zugriff auf denselben WebGL-Kontext, den die Google Maps Platform zum Rendern der Vektorbasiskarte verwendet. Die Verwendung eines gemeinsamen Renderingkontexts bietet verschiedene Vorteile wie Tiefenverdeckung durch 3D-Gebäudegeometrie und die Möglichkeit, 2D-/3D-Inhalte mit Basiskarten-Rendering zu synchronisieren. Objekte, die mit WebGL Overlay View gerendert werden, können auch mit Breiten- und Längengradkoordinaten verknüpft werden, damit sie sich beim Ziehen, Zoomen, Schwenken oder Neigen der Karte mitbewegen.

Voraussetzungen

Wenn Sie WebGL Overlay View verwenden möchten, müssen Sie die Karte mithilfe einer Karten-ID mit aktivierter Vektorkarte laden. Sie sollten beim Erstellen der Karten-ID die Kameraneigung und ‑drehung aktivieren, um eine vollständige 3D-Kamerasteuerung zu ermöglichen. Weitere Informationen

WebGL Overlay View hinzufügen

Um der Karte das Overlay hinzuzufügen, müssen Sie google.maps.WebGLOverlayView implementieren und dann die Karteninstanz mit setMap übergeben:

// Create a map instance.
const map = new google.maps.Map(mapDiv, mapOptions);

// Create a WebGL Overlay View instance.
const webglOverlayView = new google.maps.WebGLOverlayView();

// Add the overlay to the map.
webglOverlayView.setMap(map);

Lebenszyklus-Hooks

WebGL Overlay View bietet eine Reihe von Hooks, die zu verschiedenen Zeiten im Lebenszyklus des WebGL-Renderingkontexts der Vektorbasiskarte aufgerufen werden. Mit diesen Lebenszyklus-Hooks können Sie alles, was im Overlay gerendert werden soll, einrichten, entwerfen und entfernen.

  • onAdd() wird beim Erstellen des Overlays aufgerufen. Dieser Hook wird verwendet, um vor dem Erstellen des Overlays Zwischendatenstrukturen abzurufen oder zu erstellen, für die kein direkter Zugriff auf den WebGL-Renderingkontext erforderlich ist.
  • onContextRestored({gl}) wird aufgerufen, sobald der Renderingkontext verfügbar ist. Damit können Sie einen WebGL-Zustand wie Shader oder GL-Pufferobjekte initialisieren oder binden. Bei onContextRestored() wird eine WebGLStateOptions-Instanz mit nur einem Feld verwendet:
    • gl ist ein Handle für den WebGLRenderingContext, der von der Basiskarte verwendet wird.
  • onDraw({gl, transformer}) rendert die Szene auf der Basiskarte. Der Parameter für onDraw() ist ein WebGLDrawOptions-Objekt mit zwei Feldern:
    • gl ist ein Handle für den WebGLRenderingContext, der von der Basiskarte verwendet wird.
    • transformer bietet Hilfsfunktionen zur Transformation von Kartenkoordinaten in eine Model-View-Projection-Matrix. Damit können Kartenkoordinaten in den Welt-, Kamera- und Bildschirmraum umgewandelt werden.
  • onContextLost() wird aufgerufen, wenn der Renderingkontext aus irgendeinem Grund verloren geht. Hier sollten Sie alle vorhandenen GL-Zustände bereinigen, da sie nicht mehr benötigt werden.
  • onStateUpdate({gl}) aktualisiert den GL-Zustand außerhalb der Renderingschleife und wird aufgerufen, wenn requestStateUpdate aufgerufen wird. Dabei wird eine WebGLStateOptions-Instanz mit nur einem Feld verwendet:
    • gl ist ein Handle für den WebGLRenderingContext, der von der Basiskarte verwendet wird.
  • onRemove() wird aufgerufen, wenn das Overlay mit WebGLOverlayView.setMap(null) von der Karte entfernt wird. Hier sollten Sie alle Zwischenobjekte entfernen.

Das folgende Beispiel zeigt eine einfache Implementierung aller Lebenszyklus-Hooks:

const webglOverlayView = new google.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);

GL-Zustand zurücksetzen

WebGL Overlay View stellt den WebGL-Renderingkontext der Basiskarte dar. Aus diesem Grund müssen Sie den GL-Zustand nach dem Rendern von Objekten unbedingt auf seinen ursprünglichen Zustand zurücksetzen. Andernfalls kann es zu GL-Zustandskonflikten kommen und das Rendern der Karte und aller von Ihnen angegebenen Objekte schlägt fehl.

Der GL-Zustand wird normalerweise im onDraw()-Hook zurückgesetzt. Three.js bietet beispielsweise eine Hilfsfunktion, mit der alle Änderungen am GL-Zustand gelöscht werden:

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

Wenn die Karte oder Ihre Objekte nicht gerendert werden, wurde der GL-Zustand höchstwahrscheinlich nicht zurückgesetzt.

Koordinaten umwandeln

Um die Position eines Objekts auf der Vektorkarte zu definieren, werden Breiten- und Längengradkoordinaten sowie die Höhe angegeben. 3D-Grafiken werden jedoch im Welt-, Kamera- oder Bildschirmraum angegeben. Um die Umwandlung von Kartenkoordinaten in diese gängigeren Räume zu vereinfachen, bietet WebGL Overlay View die Hilfsfunktion coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) im onDraw()-Hook. Sie wandelt folgende Eingaben in ein Float64Array um:

  • latLngAltitude: Breiten- und Längengrad plus Höhe als LatLngAltitude oder LatLngAltitudeLiteral
  • rotationArr: Float32Array der eulerschen Winkel in Grad
  • scalarArr: Float32Array der Skalare, die auf die Kardinalachse angewendet werden sollen

Im folgenden Beispiel wird mit fromLatLngAltitude() eine Kameraprojektionsmatrix in Three.js erstellt:

const camera = new THREE.PerspectiveCamera();
const matrix = coordinateTransformer.fromLatLngAltitude({
    lat: mapOptions.center.lat,
    lng: mapOptions.center.lng,
    altitude: 120,
});
camera.projectionMatrix = new THREE.Matrix4().fromArray(matrix);

Beispiel

Es folgt ein einfaches Beispiel für die Verwendung von Three.js, einer beliebten Open-Source-WebGL-Bibliothek, um ein 3D-Objekt auf der Karte zu platzieren. Eine vollständige Schritt-für-Schritt-Anleitung zur Verwendung von WebGL Overlay View für das Beispiel, das Sie oben auf dieser Seite sehen, finden Sie im Codelab 3D-Karten mit WebGL Overlay View erstellen.

const webglOverlayView = new google.maps.WebGLOverlayView();
let scene, renderer, camera, loader;

webglOverlayView.onAdd = () => {
  // Set up the Three.js scene.
  scene = new THREE.Scene();
  camera = new THREE.PerspectiveCamera();
  const ambientLight = new THREE.AmbientLight( 0xffffff, 0.75 ); // Soft white light.
  scene.add(ambientLight);

  // Load the 3D model with GLTF Loader from Three.js.
  loader = new GLTFLoader();
  loader.load("pin.gltf");
}

webglOverlayView.onContextRestored = ({gl}) => {
  // Create the Three.js renderer, using the
  // maps's WebGL rendering context.
  renderer = new THREE.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.
  const matrix = transformer.fromLatLngAltitude({
      lat: mapOptions.center.lat,
      lng: mapOptions.center.lng,
      altitude: 120,
  });
camera.projectionMatrix = new THREE.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);