Con la visualizzazione sovrapposta di WebGL, puoi aggiungere contenuti alle tue mappe direttamente tramite WebGL o tramite librerie grafiche popolari come Three.js. La visualizzazione sovrapposta di WebGL fornisce l'accesso diretto allo stesso contesto di rendering di WebGL utilizzato da Google Maps Platform per eseguire il rendering della mappa base vettoriale. L'uso di un contesto di rendering condiviso offre vantaggi come l'occlusione della profondità con la geometria di edifici 3D e la possibilità di sincronizzare i contenuti 2D/3D con il rendering della mappa base. Gli oggetti sottoposti a rendering con la visualizzazione sovrapposta di WebGL possono essere associati alle coordinate di latitudine e longitudine, in modo che si muovano quando trascini, esegui lo zoom, la panoramica o l'inclinazione della mappa.
Requisiti
Per utilizzare la visualizzazione sovrapposta di WebGL, devi caricare la mappa utilizzando un ID mappa con la mappa vettoriale abilitata. Ti consigliamo vivamente di attivare l'inclinazione e la rotazione quando crei l'ID mappa, per consentire il controllo completo della fotocamera 3D. Consulta la panoramica per i dettagli.
Aggiungi vista sovrapposta WebGL
Per aggiungere l'overlay alla mappa, implementa google.maps.WebGLOverlayView, poi passalo alla tua istanza di mappa utilizzando 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);
Hook ciclo di vita
La visualizzazione sovrapposta di WebGL fornisce una serie di hook chiamati in vari momenti del ciclo di vita del contesto di rendering WebGL della mappa base vettoriale. Questi hook del ciclo di vita sono i punti in cui configuri, disegna e rimuovi tutto ciò che vuoi che venga visualizzato nell'overlay.
onAdd()viene chiamato quando viene creato l'overlay. Utilizzala per recuperare o creare strutture di dati intermedie prima che venga disegnato l'overlay che non richiedono l'accesso immediato al contesto di rendering WebGL.onContextRestored({gl})viene chiamato quando il contesto di rendering è disponibile. Utilizzala per inizializzare o associare qualsiasi stato WebGL come Shar, oggetti buffer GL e così via.onContextRestored()utilizza un'istanzaWebGLStateOptions, che ha un solo campo:glè un handle per il valoreWebGLRenderingContextutilizzato dalla mappa base.
onDraw({gl, transformer})esegue il rendering della scena sulla mappa base. Il parametro peronDraw()è un oggettoWebGLDrawOptions, che ha due campi:glè un handle per il valoreWebGLRenderingContextutilizzato dalla mappa base.transformeroffre funzioni helper per passare dalle coordinate della mappa alla matrice-vista-modello-proiezione, che può essere utilizzata per tradurre le coordinate della mappa nello spazio mondiale, nello spazio della fotocamera e nello spazio dello schermo.
onContextLost()viene chiamato quando il contesto del rendering viene perso per qualsiasi motivo ed è dove devi ripulire qualsiasi stato GL preesistente, dato che non è più necessario.onStateUpdate({gl})aggiorna lo stato GL al di fuori del loop di rendering e viene richiamato quando viene chiamatorequestStateUpdate. Serve un'istanzaWebGLStateOptions, che ha un solo campo:glè un handle per il valoreWebGLRenderingContextutilizzato dalla mappa base.
onRemove()viene richiamato quando l'overlay viene rimosso dalla mappa conWebGLOverlayView.setMap(null)ed è il punto in cui devi rimuovere tutti gli oggetti intermedi.
Ad esempio, di seguito è riportata un'implementazione di base di tutti gli hook del ciclo di vita:
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);
Reimpostazione dello stato GL
La visualizzazione sovrapposta di WebGL mostra il contesto di rendering WebGL della mappa base. Per questo motivo, è estremamente importante ripristinare lo stato originale dello stato GL al termine del rendering degli oggetti. La mancata reimpostazione dello stato GL ha maggiori probabilità di provocare conflitti di stato GL, che causeranno un errore del rendering sia della mappa sia degli oggetti specificati.
La reimpostazione dello stato GL viene solitamente gestita nell'hook onDraw(). Ad esempio, Three.js fornisce una funzione helper che cancella tutte le modifiche allo stato GL:
webglOverlayView.onDraw = ({gl, transformer}) => {
// Specify an object to render.
renderer.render(scene, camera);
renderer.resetState();
}
Se non viene eseguito il rendering della mappa o degli oggetti, è molto probabile che lo stato GL non sia stato reimpostato.
Coordina le trasformazioni
La posizione di un oggetto sulla mappa vettoriale viene specificata fornendo una combinazione di coordinate di latitudine e longitudine, nonché dell'altitudine. Le immagini 3D, tuttavia, vengono specificate nello spazio globale, nello spazio della fotocamera o sullo schermo.
Per semplificare la trasformazione delle coordinate della mappa in questi spazi più comuni, la visualizzazione sovrapposta di WebGL fornisce la funzione helper coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr,
scalarArr) nell'hook onDraw() che prende quanto segue e restituisce un Float64Array:
latLngAltitude: coordinate di latitudine/longitudine/altitudine comeLatLngAltitudeoLatLngAltitudeLiteral.rotationArr:Float32Arraydegli angoli di rotazione euler specificati in gradi.scalarArr:Float32Arraydi scalari da applicare all'asse cardinale.
Ad esempio, nell'esempio seguente viene utilizzato fromLatLngAltitude() per creare una matrice di proiezione della fotocamera in 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);
Esempio
Di seguito è riportato un semplice esempio di utilizzo di Three.js, una popolare libreria WebGL open source, per posizionare un oggetto 3D sulla mappa. Per una procedura dettagliata completa sull'utilizzo della vista sovrapposta di WebGL per creare l'esempio che vedi in esecuzione nella parte superiore di questa pagina, prova il codelab Creazione di esperienze mappa con accelerazione 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);