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 obiektuWebGLRenderingContext
używany przez mapę podstawową.
onDraw({gl, transformer})
renderuje scenę na mapie podstawowej. ParametryonDraw()
to obiektWebGLDrawOptions
, który ma 2 pola:gl
to uchwyt obiektuWebGLRenderingContext
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 funkcjirequestStateUpdate
. Potrzebna jest instancjaWebGLStateOptions
, która zawiera 1 pole:gl
to uchwyt obiektuWebGLRenderingContext
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 formacieLatLngAltitude
lubLatLngAltitudeLiteral
.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);