Chế độ xem lớp phủ WebGL

Xem mẫu

Với Chế độ xem lớp phủ WebGL, bạn có thể thêm nội dung vào bản đồ bằng cách sử dụng trực tiếp WebGL hoặc các thư viện Đồ hoạ phổ biến như Three.js. Chế độ xem lớp phủ WebGL cung cấp quyền truy cập trực tiếp vào cùng một ngữ cảnh kết xuất WebGL mà Nền tảng Google Maps sử dụng để kết xuất bản đồ cơ sở vectơ. Việc sử dụng ngữ cảnh kết xuất dùng chung này mang lại các lợi ích như che khuất chiều sâu bằng hình học toà nhà 3D và khả năng đồng bộ hoá nội dung 2D/3D với kết xuất bản đồ cơ sở. Các đối tượng được kết xuất bằng Chế độ xem lớp phủ WebGL cũng có thể được liên kết với toạ độ vĩ độ/kinh độ, vì vậy, các đối tượng này sẽ di chuyển khi bạn kéo, thu phóng, kéo hoặc nghiêng bản đồ.

Yêu cầu

Để sử dụng Chế độ xem lớp phủ WebGL, bạn phải tải bản đồ bằng mã bản đồ đã bật bản đồ vectơ. Bạn nên bật chế độ nghiêng và xoay khi tạo mã bản đồ để có thể kiểm soát toàn bộ máy ảnh 3D. Xem thông tin tổng quan để biết thông tin chi tiết.

Thêm Chế độ xem lớp phủ WebGL

Để thêm lớp phủ vào bản đồ, hãy triển khai google.maps.WebGLOverlayView, sau đó truyền lớp phủ đó vào thực thể bản đồ bằng 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);

Lệnh gọi lại vòng đời

Chế độ xem lớp phủ WebGL cung cấp một tập hợp các trình bổ trợ được gọi tại nhiều thời điểm trong vòng đời của ngữ cảnh kết xuất WebGL của bản đồ cơ sở vectơ. Các trình bổ trợ vòng đời này là nơi bạn thiết lập, vẽ và phá bỏ mọi nội dung bạn muốn hiển thị trong lớp phủ.

  • onAdd() được gọi khi lớp phủ được tạo. Sử dụng lớp này để tìm nạp hoặc tạo cấu trúc dữ liệu trung gian trước khi lớp phủ được vẽ mà không yêu cầu quyền truy cập ngay vào ngữ cảnh kết xuất WebGL.
  • onContextRestored({gl}) được gọi sau khi có bối cảnh kết xuất. Sử dụng đối tượng này để khởi tạo hoặc liên kết bất kỳ trạng thái WebGL nào, chẳng hạn như chương trình đổ bóng, đối tượng vùng đệm GL, v.v. onContextRestored() lấy một thực thể WebGLStateOptions, có một trường duy nhất:
    • gl là một handle cho WebGLRenderingContext mà bản đồ cơ sở sử dụng.
  • onDraw({gl, transformer}) kết xuất cảnh trên bản đồ cơ sở. Các tham số cho onDraw() là một đối tượng WebGLDrawOptions, có hai trường:
    • gl là một handle cho WebGLRenderingContext mà bản đồ cơ sở sử dụng.
    • transformer cung cấp các hàm trợ giúp để chuyển đổi từ toạ độ bản đồ sang ma trận chiếu chế độ xem mô hình. Ma trận này có thể được dùng để dịch toạ độ bản đồ sang không gian thế giới, không gian máy ảnh và không gian màn hình.
  • onContextLost() được gọi khi ngữ cảnh kết xuất bị mất vì bất kỳ lý do nào và là nơi bạn nên dọn dẹp mọi trạng thái GL hiện có, vì trạng thái này không còn cần thiết nữa.
  • onStateUpdate({gl}) cập nhật trạng thái GL bên ngoài vòng lặp kết xuất và được gọi khi requestStateUpdate được gọi. Phương thức này lấy một thực thể WebGLStateOptions có một trường duy nhất:
    • gl là một handle cho WebGLRenderingContext mà bản đồ cơ sở sử dụng.
  • onRemove() được gọi khi lớp phủ bị xoá khỏi bản đồ bằng WebGLOverlayView.setMap(null) và là nơi bạn nên xoá tất cả đối tượng trung gian.

Ví dụ: sau đây là cách triển khai cơ bản của tất cả các trình kích hoạt vòng đời:

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

Đặt lại trạng thái GL

Chế độ xem lớp phủ WebGL hiển thị ngữ cảnh kết xuất WebGL của bản đồ cơ sở. Do đó, điều cực kỳ quan trọng là bạn phải đặt lại trạng thái GL về trạng thái ban đầu khi kết thúc quá trình kết xuất đối tượng. Việc không đặt lại trạng thái GL có thể dẫn đến xung đột trạng thái GL, khiến quá trình kết xuất cả bản đồ và mọi đối tượng bạn chỉ định không thành công.

Việc đặt lại trạng thái GL thường được xử lý trong trình nối onDraw(). Ví dụ: Three.js cung cấp một hàm trợ giúp xoá mọi thay đổi đối với trạng thái GL:

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

Nếu bản đồ hoặc đối tượng của bạn không hiển thị, rất có thể trạng thái GL chưa được đặt lại.

Biến đổi toạ độ

Vị trí của một đối tượng trên bản đồ vectơ được chỉ định bằng cách cung cấp một tổ hợp toạ độ vĩ độ và kinh độ, cũng như độ cao. Tuy nhiên, đồ hoạ 3D được chỉ định trong không gian thế giới, không gian máy ảnh hoặc không gian màn hình. Để dễ dàng chuyển đổi toạ độ bản đồ sang các không gian thường dùng hơn này, Chế độ xem lớp phủ WebGL cung cấp hàm trợ giúp coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) trong trình nối onDraw(). Hàm này sẽ lấy các thông tin sau và trả về một Float64Array:

  • latLngAltitude: Toạ độ vĩ độ/kinh độ/cao độ dưới dạng LatLngAltitude hoặc LatLngAltitudeLiteral.
  • rotationArr: Float32Array của các góc xoay euler được chỉ định theo độ.
  • scalarArr: Float32Array của các đại lượng vô hướng để áp dụng cho trục chính.

Ví dụ: đoạn mã sau sử dụng fromLatLngAltitude() để tạo ma trận chiếu camera trong 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);

Ví dụ:

Sau đây là ví dụ đơn giản về cách sử dụng Three.js, một thư viện WebGL nguồn mở phổ biến, để đặt đối tượng 3D trên bản đồ. Để xem hướng dẫn đầy đủ về cách sử dụng Chế độ xem lớp phủ WebGL để tạo ví dụ mà bạn thấy đang chạy ở đầu trang này, hãy thử tham gia Lớp học lập trình về cách tạo trải nghiệm bản đồ được tăng tốc 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);