Tampilan Overlay WebGL

Lihat Contoh

Dengan Tampilan Overlay WebGL, Anda dapat menambahkan konten ke peta secara langsung menggunakan WebGL, atau library Grafik populer seperti Three.js. Tampilan Overlay WebGL memberikan akses langsung ke konteks proses rendering WebGL yang sama dengan yang digunakan Google Maps Platform untuk merender peta dasar vektor. Penggunaan konteks proses rendering bersama ini memberikan manfaat seperti oklusi kedalaman dengan geometri bangunan 3D, dan kemampuan untuk menyinkronkan konten 2D/3D dengan rendering peta dasar. Objek yang dirender dengan Tampilan Overlay WebGL juga dapat dikaitkan dengan koordinat lintang/bujur, sehingga ikut bergerak saat Anda menarik, melakukan zoom, menggeser, atau memiringkan peta.

Persyaratan

Untuk menggunakan Tampilan Overlay WebGL, Anda harus memuat peta menggunakan ID peta dengan peta vektor diaktifkan. Kami sangat menyarankan Anda mengaktifkan kemiringan dan rotasi saat membuat ID peta agar kontrol kamera 3D penuh dapat dilakukan. Lihat ringkasan untuk mengetahui detailnya.

Menambahkan Tampilan Overlay WebGL

Untuk menambahkan overlay ke peta, implementasikan google.maps.WebGLOverlayView, lalu teruskan ke instance peta Anda menggunakan 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 siklus proses

Tampilan Overlay WebGL menyediakan serangkaian hook yang dipanggil pada berbagai waktu dalam siklus proses dari konteks proses rendering WebGL untuk peta dasar vektor. Hook siklus proses ini adalah tempat Anda menyiapkan, menggambar, dan menghilangkan apa pun yang perlu dirender dalam overlay.

  • onAdd() dipanggil saat overlay dibuat. Gunakan untuk mengambil atau membuat struktur data perantara sebelum overlay digambar yang tidak memerlukan akses langsung ke konteks proses rendering WebGL.
  • onContextRestored({gl}) dipanggil setelah konteks proses rendering tersedia. Gunakan untuk melakukan inisialisasi atau mengikat status WebGL seperti shader, objek buffer GL, dan sebagainya. onContextRestored() mengambil instance WebGLStateOptions, yang memiliki satu kolom:
    • gl adalah handle WebGLRenderingContext yang digunakan oleh peta dasar.
  • onDraw({gl, transformer}) merender kondisi pada peta dasar. Parameter untuk onDraw() adalah objek WebGLDrawOptions, yang memiliki dua kolom:
    • gl adalah handle WebGLRenderingContext yang digunakan oleh peta dasar.
    • transformer menyediakan fungsi bantuan untuk mengubah dari koordinat peta menjadi matriks proyeksi tampilan model, yang dapat digunakan untuk menerjemahkan koordinat peta ke ruang dunia, ruang kamera, dan ruang layar.
  • onContextLost() dipanggil saat konteks proses rendering hilang karena alasan apa pun, dan merupakan tempat untuk menghapus status GL yang sudah ada karena tidak diperlukan lagi.
  • onStateUpdate({gl}) memperbarui status GL di luar loop render, dan dipanggil saat requestStateUpdate dipanggil. Dibutuhkan instance WebGLStateOptions, yang memiliki satu kolom:
    • gl adalah handle WebGLRenderingContext yang digunakan oleh peta dasar.
  • onRemove() dipanggil saat overlay dihapus dari peta dengan WebGLOverlayView.setMap(null), dan merupakan tempat untuk menghapus semua objek perantara.

Misalnya, berikut ini adalah implementasi dasar dari semua hook siklus proses:

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

Mereset Status GL

Tampilan Overlay WebGL mengekspos konteks proses rendering WebGL dari peta dasar. Oleh karena itu, sangat penting untuk mereset status GL ke status awal saat Anda selesai merender objek. Kegagalan mereset status GL kemungkinan akan mengakibatkan konflik status GL, yang akan menyebabkan rendering peta dan objek apa pun yang Anda tentukan gagal.

Mereset status GL biasanya ditangani di hook onDraw(). Misalnya, Three.js menyediakan fungsi bantuan yang menghapus perubahan pada status GL:

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

Jika peta atau objek Anda gagal dirender, kemungkinan besar status GL belum direset.

Transformasi Koordinat

Posisi objek pada peta vektor ditentukan dengan memberikan kombinasi koordinat garis lintang dan bujur, serta ketinggian. Namun, grafik 3D ditentukan dalam ruang dunia, ruang kamera, atau ruang layar. Untuk mempermudah transformasi koordinat peta ke ruang yang lebih umum digunakan, Tampilan Overlay WebGL menyediakan fungsi bantuan coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) dalam hook onDraw() yang mengambil hal berikut dan mengembalikan Float64Array:

  • latLngAltitude: Koordinat lintang/bujur/ketinggian baik sebagai LatLngAltitude atau LatLngAltitudeLiteral.
  • rotationArr: Float32Array sudut rotasi euler yang ditentukan dalam derajat.
  • scalarArr: Float32Array skalar untuk diterapkan pada sumbu kardinal.

Misalnya, kode berikut menggunakan fromLatLngAltitude() untuk membuat matriks proyeksi kamera di 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);

Contoh

Berikut adalah contoh sederhana penggunaan Three.js, library WebGL open source yang populer, untuk menempatkan objek 3D pada peta. Untuk panduan lengkap penggunaan Tampilan Overlay WebGL untuk membuat contoh yang Anda lihat ditampilkan di bagian atas halaman ini, coba Membuat codelab Pengalaman Peta yang dipercepat 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);