Widok nakładki WebGL

Wyświetl próbkę

Za pomocą widoku nakładki WebGL możesz dodawać treści do map bezpośrednio 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 używa Google Maps Platform 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ę za pomocą identyfikatora mapy z włączoną mapą wektorową. Gorąco zalecamy, aby podczas tworzenia identyfikatora mapy włączyć pochylenie i obrót, co umożliwi pełne sterowanie kamerą 3D. Szczegóły znajdziesz w omówieniu

Dodawanie widoku nakładki WebGL

Aby dodać nakładkę do mapy, zaimplementuj google.maps.WebGLOverlayView, a następnie prześlij ją do instancji 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);

Hooks cyklu życia

Widok nakładki WebGL udostępnia zestaw uchwytów wywoływanych w różnych momentach cyklu życia kontekstu renderowania WebGL mapy bazowej wektorowej. Za pomocą tych haka możesz konfigurować, rysować i usuwać wszystko, co chcesz renderować w nakładce.

• Funkcja onAdd() jest wywoływana podczas tworzenia nakładki. Za pomocą tego interfejsu można pobierać lub tworzyć struktury danych pośrednich przed narysowaniem nakładki, które nie wymagają bezpośredniego dostępu do kontekstu renderowania WebGL.
• Gdy kontekst renderowania będzie dostępny, zostanie wywołana funkcja onContextRestored({gl}). Używaj go do inicjowania lub wiązania dowolnego stanu WebGL, np. shaderów, obiektów buforów GL itp. onContextRestored() przyjmuje instancję WebGLStateOptions, która ma jedno pole:
  • gl to uchwyt do WebGLRenderingContext używany przez mapę bazową.
• onDraw({gl, transformer}) renderuje scenę na mapie podstawowej. Parametry onDraw() to obiekt WebGLDrawOptions, który ma 2 pola:
  • gl to uchwyt do WebGLRenderingContext używany przez mapę bazową.
  • transformer udostępnia funkcje pomocnicze do przekształcania współrzędnych mapy na macierz model-widok-projekcja, która może służyć do przekształcania współrzędnych mapy na przestrzeń świata, kamery i ekranu.
• 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ływana po wywołaniu requestStateUpdate. Potrzebna jest instancja WebGLStateOptions, która zawiera 1 pole:
  • gl to uchwyt elementu 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.

Oto przykład podstawowej implementacji wszystkich funkcji 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

Widok nakładki WebGL udostępnia kontekst renderowania WebGL mapy bazowej. Dlatego po zakończeniu renderowania obiektów bardzo ważne jest przywrócenie stanu GL do pierwotnego. Niezresetowanie stanu GL może spowodować konflikty stanu GL, co spowoduje niepowodzenie renderowania mapy i wszelkich określonych 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 renderowanie mapy lub obiektów się nie powiedzie, bardzo prawdopodobne jest, że stan GL nie został zresetowany.

Przekształcenia współrzędnych

Pozycja obiektu na mapie wektorowej jest określana 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 na te bardziej powszechnie używane przestrzenie, WebGL Overlay View udostępnia funkcję pomocniczą coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) w hak onDraw(), która przyjmuje te dane i zwraca Float64Array:

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

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. Szczegółowe instrukcje tworzenia przykładu widocznego u góry tej strony za pomocą widoku nakładki WebGL znajdziesz w ćwiczeniach z programowania Tworzenie map przyspieszonych przez WebGL (w języku angielskim).

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