Widok nakładki WebGL

Zobacz przykład

Korzystając z widoku nakładki WebGL, możesz bezpośrednio dodawać treści do map za pomocą WebGL lub popularnych bibliotek graficznych, takich jak Three.js. Widok nakładki WebGL zapewnia bezpośredni dostęp do tego samego kontekstu renderowania WebGL, którego Google Maps Platform używa do renderowania wektorowej mapy bazowej. Użycie udostępnionego kontekstu renderowania ma wiele zalet, na przykład głębię przesłania dzięki geometrii budynków 3D oraz możliwość synchronizacji treści 2D/3D z renderowaniem mapy podstawowej. Obiekty renderowane za pomocą widoku nakładki WebGL można też powiązać ze współrzędnymi szerokości i długości geograficznej, dzięki czemu przesuwają się, gdy przeciągasz, powiększasz, przesuwasz lub przechylasz mapę.

Wymagania

Aby korzystać z widoku nakładki WebGL, musisz wczytać mapę przy użyciu identyfikatora mapy z włączoną mapą wektorową. Zdecydowanie zalecamy, aby podczas tworzenia identyfikatora mapy włączyć przechylanie i obrót, ponieważ umożliwi to pełną kontrolę nad kamerą 3D. Szczegółowe informacje znajdziesz w omówieniu.

Dodaj widok nakładki WebGL

Aby dodać nakładkę do mapy, zaimplementuj obiekt google.maps.WebGLOverlayView, a następnie przekaż wystąpienie mapy za pomocą 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);

Elementy zaczepienia cyklu życia

Widok nakładki WebGL to zestaw punktów zaczepienia, które są wywoływane w różnych momentach w kontekście renderowania WebGL w wektorowej mapie bazowej. Za pomocą tych punktów zaczepienia cyklu życia możesz skonfigurować, rysować i usuwać wszystko, co chcesz renderować w nakładce.

• Pole onAdd() jest wywoływane podczas tworzenia nakładki. Służy do pobierania lub tworzenia pośrednich struktur danych przed wyświetleniem nakładki, które nie wymagają bezpośredniego dostępu do kontekstu renderowania WebGL.
• Pole onContextRestored({gl}) jest wywoływane po udostępnieniu kontekstu renderowania. Służy on do inicjowania lub wiązania dowolnego stanu WebGL, takiego jak cieniowanie czy obiekty bufora GL. onContextRestored() wykorzystuje instancję WebGLStateOptions, która zawiera 1 pole:
  • gl to uchwyt obiektu WebGLRenderingContext używany przez mapę podstawową.
• onDraw({gl, transformer}) renderuje scenę na mapie podstawowej. Parametry onDraw() to obiekt WebGLDrawOptions, który ma 2 pola:
  • gl to uchwyt obiektu WebGLRenderingContext używany przez mapę podstawową.
  • transformer udostępnia funkcje pomocnicze do przekształcania współrzędnych mapy w matrycę modelu/widoku/odwzorowania, której można używać do tłumaczenia współrzędnych na mapie w przestrzeni świata, przestrzeni kamery i przestrzeni na ekranie.
• Metoda onContextLost() jest wywoływana, gdy z dowolnego powodu zostanie utracony kontekst renderowania. W tym miejscu należy wyczyścić wszystkie istniejący stan GL, ponieważ nie jest już potrzebny.
• onStateUpdate({gl}) aktualizuje stan GL poza pętlą renderowania i jest wywoływany po wywołaniu funkcji requestStateUpdate. Potrzebna jest instancja WebGLStateOptions, która zawiera 1 pole:
  • gl to uchwyt obiektu WebGLRenderingContext używany przez mapę podstawową.
• Pole onRemove() jest wywoływane, gdy nakładka zostanie usunięta z mapy za pomocą WebGLOverlayView.setMap(null). To w tym miejscu należy usunąć wszystkie obiekty pośrednie.

Poniżej przedstawiono podstawową implementację wszystkich punktów zaczepienia cyklu życia:

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

Resetuję stan GL

Widok nakładki WebGL ujawnia kontekst renderowania WebGL na mapie podstawowej. Z tego powodu niezwykle ważne jest przywrócenie pierwotnego stanu GL po zakończeniu renderowania obiektów. Jeśli nie zresetujesz stanu GL, prawdopodobnie spowoduje to konflikty stanów GL, które spowodują błąd renderowania zarówno mapy, jak i wszystkich wskazanych obiektów.

Resetowanie stanu GL jest zwykle obsługiwane w punkcie zaczepienia onDraw(). Na przykład Three.js udostępnia funkcję pomocniczą, która usuwa wszystkie zmiany stanu GL:

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

Jeśli nie uda się wyrenderować mapy lub obiektów, prawdopodobnie stan GL nie został zresetowany.

Skoordynuj transformacje

Pozycja obiektu na mapie wektorowej określa się za pomocą kombinacji współrzędnych szerokości i długości geograficznej oraz wysokości. Obrazy 3D są jednak określone w przestrzeni świata, obszarze kamery i miejscu na ekranie. Aby ułatwić przekształcanie współrzędnych mapy na te częściej używane przestrzenie, w widoku nakładki WebGL umieszczamy coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) funkcję pomocniczą w haczyku onDraw(), który zwraca: Float64Array:

• latLngAltitude: szerokość/długość geograficzna/wysokość geograficzna w formacie LatLngAltitude lub LatLngAltitudeLiteral.
• rotationArr: Float32Array kątów obrotu Eulera określonych w stopniach.
• scalarArr: Float32Array skalarów do zastosowania na osi kardynał.

Na przykład poniższy kod wykorzystuje kod fromLatLngAltitude() do utworzenia matrycy projekcji kamery w Three.js:

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

Przykład

Poniżej znajdziesz prosty przykład wykorzystania Three.js – popularnej biblioteki WebGL typu open source do umieszczenia obiektu 3D na mapie. Aby zapoznać się z pełną instrukcją korzystania z widoku nakładki WebGL do tworzenia przykładu widocznego na górze tej strony, wykonaj ćwiczenie z programowania w usłudze Tworzenie map z akceleracją WebGL.

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