WebGL-Overlay-Ansicht

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Beispiel ansehen

Mit der WebGL-Overlay-Ansicht können Sie Ihren Karten mithilfe von WebGL Inhalte direkt hinzufügen oder mit beliebten Grafikbibliotheken wie Three.js. Die WebGL-Overlay-Ansicht bietet direkten Zugriff auf denselben WebGL-Renderingkontext, den die Google Maps Platform zum Rendern der Vektorbasiskarte verwendet. Dieser gemeinsame Kontext bietet Vorteile wie Tiefenverdeckung durch 3D-Gebäudegeometrie und die Möglichkeit, 2D-/3D-Inhalte mit Basiskarten-Rendering zu synchronisieren. Mit der WebGL Overlay View gerenderte Objekte können auch an Breiten- und Längengrade gebunden werden, sodass sie sich beim Ziehen, Zoomen, Schwenken oder Neigen der Karte mitbewegen.

Voraussetzungen

Wenn Sie die WebGL-Overlay-Ansicht verwenden möchten, müssen Sie die Karte mithilfe einer Karten-ID mit aktivierter Vektorkarte laden. Wir empfehlen dringend, die Neige- und Drehfunktion beim Erstellen der Karten-ID zu aktivieren, um eine vollständige 3D-Kamerasteuerung zu ermöglichen. Weitere Informationen

WebGL-Overlay-Ansicht hinzufügen

Implementiere google.maps.WebGLOverlayView, um das Overlay zur Karte hinzuzufügen, und übergib es dann auf der Karteninstanz mit setMap:

// 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

Die WebGL-Overlay-Ansicht 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, zeichnen und entfernen.

  • onAdd() wird beim Erstellen des Overlays aufgerufen. Verwenden Sie sie, um Zwischendatenstrukturen abzurufen oder zu erstellen, bevor das Overlay gezeichnet wird, die keinen sofortigen Zugriff auf den WebGL-Renderingkontext erfordern.
  • onContextRestored({gl}) wird aufgerufen, sobald der Rendering-Kontext verfügbar ist. Damit können Sie einen WebGL-Status wie Shader, GL-Zwischenspeicherobjekte usw. initialisieren oder binden. onContextRestored() verwendet eine WebGLStateOptions-Instanz mit einem einzelnen Feld:
    • gl ist ein Handle für die WebGLRenderingContext, die von der Basiskarte verwendet wird.
  • onDraw({gl, transformer}) rendert die Szene auf der Basiskarte. Die Parameter für onDraw() sind ein WebGLDrawOptions-Objekt mit zwei Feldern:
    • gl ist ein Handle für die WebGLRenderingContext, die von der Basiskarte verwendet wird.
    • transformer bietet Hilfsfunktionen zur Transformation von Kartenkoordinaten in eine Matrix für die Modellaufruf-Projektion. Damit können Kartenkoordinaten in Welt-, Kamera- und Bildschirmbereiche übersetzt werden.
  • onContextLost() wird aufgerufen, wenn der Renderingkontext aus irgendeinem Grund verloren geht. Hier sollten Sie jeden vorhandenen GL-Status bereinigen, da er nicht mehr benötigt wird.
  • onStateUpdate({gl}) aktualisiert den GL-Status außerhalb der Rendering-Schleife und wird aufgerufen, wenn requestStateUpdate aufgerufen wird. Dazu wird die Instanz WebGLStateOptions verwendet, die nur ein Feld enthält:
    • gl ist ein Handle für die WebGLRenderingContext, die von der Basiskarte verwendet wird.
  • onRemove() wird aufgerufen, wenn das Overlay mit WebGLOverlayView.setMap(null) aus der Karte entfernt wird. Hier sollten Sie alle Zwischenobjekte entfernen.

Im Folgenden finden Sie beispielsweise eine grundlegende 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-Status wird zurückgesetzt

In der WebGL-Overlay-Ansicht wird der WebGL-Renderingkontext der Basiskarte angezeigt. Aus diesem Grund ist es sehr wichtig, dass Sie den GL-Status auf den ursprünglichen Zustand zurücksetzen, wenn Sie mit dem Rendern von Objekten fertig sind. Wenn der GL-Status nicht zurückgesetzt wird, führt dies wahrscheinlich zu GL-Statuskonflikten, die dazu führen, dass sowohl die Karte als auch alle von Ihnen angegebenen Objekte gerendert werden.

Das Zurücksetzen des GL-Status erfolgt normalerweise im Hook onDraw(). Three.js bietet beispielsweise eine Hilfsfunktion, mit der alle Änderungen am GL-Status 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-Status höchstwahrscheinlich nicht zurückgesetzt.

Umwandlung von Koordinaten

Die Position eines Objekts auf der Vektorkarte wird durch die Kombination aus Breiten- und Längengraden sowie der Höhe angegeben. 3D-Grafiken werden jedoch im Welt-, Kamera- oder Bildschirmbereich angegeben. Damit sich die Kartenkoordinaten einfacher in diese gängigere Bereiche umwandeln lassen, bietet die WebGL Overlay View-Ansicht die Hilfsfunktion coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) im Hook onDraw(), die Folgendes annimmt und ein Float64Array zurückgibt:

  • latLngAltitude: Breiten-/Längengrad-/Höhenkoordinaten, angegeben als LatLngAltitude oder LatLngAltitudeLiteral.
  • rotationArr: Float32Array der Ellendrehwinkel in Grad.
  • scalarArr: Float32Array von Skalaren, 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

Im Folgenden finden Sie 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 Komplettlösung zur Verwendung von WebGL Overlay View zum Erstellen des Beispiels, das Sie oben auf dieser Seite sehen, finden Sie im Codelab „Building WebGL-Accelerated Map Experiences“.

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);