Widok nakładki WebGL

Wyświetl przykład

Dzięki WebGL Overlay View możesz dodawać treści do map bezpośrednio za pomocą WebGL lub popularnych bibliotek graficznych, takich jak Three.js. WebGL Overlay View zapewnia bezpośredni dostęp do tego samego kontekstu renderowania WebGL, którego Google Maps Platform używa do renderowania wektorowej mapy bazowej. Korzystanie ze wspólnego kontekstu renderowania zapewnia takie korzyści jak okluzja głębi z geometrią budynków 3D oraz możliwość synchronizowania treści 2D i 3D z renderowaniem mapy podstawowej. Obiekty renderowane za pomocą WebGL Overlay View można też powiązać ze współrzędnymi geograficznymi, dzięki czemu przesuwają się, gdy przeciągasz, powiększasz, przesuwasz lub przechylasz mapę.

Wymagania

Aby korzystać z WebGL Overlay View, musisz wczytać mapę za pomocą identyfikatora mapy z włączoną mapą wektorową. Zdecydowanie zalecamy włączenie przechylania i obracania podczas tworzenia identyfikatora mapy, aby umożliwić pełną kontrolę nad kamerą 3D. Więcej informacji znajdziesz w omówieniu.

Dodawanie WebGL Overlay View

Aby dodać nakładkę do mapy, zaimplementuj google.maps.WebGLOverlayView, a następnie przekaż do niej instancję 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);

Punkty zaczepienia cyklu życia

WebGL Overlay View udostępnia zestaw punktów zaczepienia, które są wywoływane w różnych momentach cyklu życia kontekstu renderowania WebGL wektorowej mapy bazowej. W tych punktach zaczepienia cyklu życia możesz skonfigurować, narysować i usunąć wszystko, co chcesz renderować w nakładce.

• onAdd() jest wywoływany, gdy nakładka jest tworzona. Użyj go, aby pobrać lub utworzyć pośrednie struktury danych przed narysowaniem nakładki, które nie wymagają natychmiastowego dostępu do kontekstu renderowania WebGL.
• onContextRestored({gl}) jest wywoływany, gdy kontekst renderowania jest dostępny. Użyj go, aby zainicjować lub powiązać dowolny stan WebGL, taki jak shadery, obiekty buforów GL itp. onContextRestored() przyjmuje instancję WebGLStateOptions, która ma jedno pole:
  • gl to uchwyt do WebGLRenderingContext używanego przez mapę podstawową.
• onDraw({gl, transformer}) renderuje scenę na mapie podstawowej. Parametry onDraw() to obiekt WebGLDrawOptions, który ma 2 pola:
  • gl to uchwyt do WebGLRenderingContext używanego przez mapę podstawową.
  • transformer udostępnia funkcje pomocnicze do przekształcania współrzędnych mapy w macierz model-widok-projekcja, której można użyć do przekształcania współrzędnych mapy w przestrzeń świata, przestrzeń kamery i przestrzeń ekranu.
• onContextLost() jest wywoływany, gdy kontekst renderowania zostanie utracony z dowolnego powodu. W tym miejscu należy zwolnić miejsce po wszystkich dotychczasowych stanach GL, ponieważ nie są już potrzebne.
• onStateUpdate({gl}) aktualizuje stan GL poza pętlą renderowania i jest wywoływany, gdy wywoływana jest funkcja requestStateUpdate. Przyjmuje instancję WebGLStateOptions, która ma jedno pole:
  • gl to uchwyt do WebGLRenderingContext używanego przez mapę podstawową.
• onRemove() jest wywoływany, gdy nakładka zostanie usunięta z mapy za pomocą WebGLOverlayView.setMap(null). W tym miejscu należy usunąć wszystkie obiekty pośrednie.

Oto podstawowa implementacja 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);

Resetowanie stanu GL

WebGL Overlay View udostępnia kontekst renderowania WebGL mapy bazowej. Z tego powodu bardzo ważne jest, aby po zakończeniu renderowania obiektów zresetować stan GL do stanu pierwotnego. Jeśli nie zresetujesz stanu GL, prawdopodobnie wystąpią konflikty stanu GL, które spowodują niepowodzenie renderowania zarówno mapy, jak i wszystkich określonych przez Ciebie 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 mapa lub Twoje obiekty nie są renderowane, bardzo prawdopodobne jest, że stan GL nie został zresetowany.

Przekształcenia współrzędnych

Położenie obiektu na mapie wektorowej jest określane przez podanie kombinacji współrzędnych szerokości i długości geograficznej oraz wysokości. Grafika 3D jest jednak określana w przestrzeni świata, przestrzeni kamery lub przestrzeni ekranu. Aby ułatwić przekształcanie współrzędnych mapy w te powszechnie używane przestrzenie, WebGL Overlay View udostępnia funkcję pomocniczą coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) w punkcie zaczepienia onDraw(), która przyjmuje te parametry i zwraca Float64Array:

• latLngAltitude: współrzędne szerokości/długości/wysokości geograficznej jako LatLngAltitude lub LatLngAltitudeLiteral.
• rotationArr: Float32Array kątów obrotu Eulera podanych w stopniach.
• scalarArr: Float32Array skalarów do zastosowania do osi głównych.

Na przykład poniższy kod używa fromLatLngAltitude() do utworzenia macierzy 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 użycia Three.js, popularnej biblioteki WebGL o otwartym kodzie źródłowym, do umieszczenia obiektu 3D na mapie. Aby zapoznać się z pełnym przewodnikiem po tworzeniu przykładu, który widzisz u góry tej strony, za pomocą WebGL Overlay View, zapoznaj się z ćwiczeniem 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);