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 đồ của mình bằng cách sử dụng WebGL trực tiếp, hoặc các thư viện Đồ hoạ phổ biến như Three.js. Chế độ xem lớp phủ WebGL cung cấp trực tiếp quyền truy cập vào cùng một ngữ cảnh kết xuất WebGL mà Nền tảng Google Maps dùng để kết xuất bản đồ cơ sở vectơ. Việc sử dụng bối cảnh kết xuất dùng chung này mang lại nhiều lợi ích như che khuất chiều sâu với hình học toà nhà 3D và khả năng đồng bộ hoá 2D/3D được 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ó thể cũng được gắn với toạ độ vĩ độ/kinh độ, do đó chúng sẽ di chuyển khi bạn kéo, thu phóng, xoay 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 cách sử dụng ID bản đồ có vectơ bản đồ được bật. Chúng tôi thực sự khuyên bạn nên bật nghiêng và xoay khi tạo ID bản đồ để cho phép điều khiển máy ảnh 3D hoàn toàn. Xem tổng quan để biết chi tiết.

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

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

Móc trong vòng đời

Chế độ xem Lớp phủ WebGL cung cấp một tập hợp các liên kết đượ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 hook trong vòng đời là nơi bạn thiết lập, vẽ và chia nhỏ bất kỳ nội dung nào mình muốn hiển thị trong lớp phủ.

• onAdd() được gọi khi lớp phủ được tạo. Sử dụng hàm này để tìm nạp hoặc tạo cấu trúc dữ liệu trung gian trước khi vẽ lớp phủ mà không yêu cầu quyền truy cập ngay lập tức vào ngữ cảnh kết xuất WebGL.
• onContextRestored({gl}) được gọi sau khi ngữ cảnh kết xuất được sẵn có. Sử dụng nó để khởi chạy hoặc liên kết bất kỳ trạng thái WebGL nào như chương trình đổ bóng, GL đối tượng trong bộ đệm, v.v. onContextRestored() mất WebGLStateOptions có một trường duy nhất:
  • gl là một điểm điều khiển đối với WebGLRenderingContext mà bản đồ cơ sở sử dụng.
• onDraw({gl, transformer}) kết xuất cảnh trên bản đồ cơ sở. Tham số cho onDraw() là đối tượng WebGLDrawOptions, trong đó có hai trường:
  • gl là một điểm điều khiển đối với WebGLRenderingContext mà bản đồ cơ sở sử dụng.
  • transformer cung cấp các hàm trợ giúp để biến đổi từ bản đồ thành ma trận hình chiếu mô hình có thể được sử dụng để dịch toạ độ bản đồ sang không gian thế giới, không gian máy ảnh và màn hình .
• onContextLost() được gọi khi ngữ cảnh kết xuất bị mất cho bất kỳ và là nơi bạn nên dọn dẹp mọi trạng thái GL có sẵn, vì trạng thái đó 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ải mất một Thực thể WebGLStateOptions có một trường duy nhất:
  • gl là một điểm điều khiển đối với 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 xóa tất cả đối tượng trung gian.

Ví dụ: sau đây là cách triển khai cơ bản cho tất cả các hook trong 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ở. Bởi vì trong trường hợp này, bạn cần đặt lại trạng thái GL về trạng thái ban đầu trạng thái khi bạn kết xuất xong đối tượng. Việc không đặt lại được trạng thái GL có khả năng dẫn đến xung đột trạng thái GL, điều này sẽ gây ra việc hiển thị cả ánh xạ và bất kỳ đối tượng nào bạn chỉ định là bị lỗi.

Việc đặt lại trạng thái GL thường được xử lý trong hook onDraw(). Ví dụ: Three.js cung cấp hàm trợ giúp xoá bất kỳ thay đổi nào đố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 các đối tượng của bạn không kết xuất được, rất có thể trạng thái GL chưa được đặt lại.

Phép biến đổi phối hợp

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 vĩ độ và kinh độ cũng như độ cao. 3 chiều tuy nhiên, đồ hoạ đượ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. Để chuyển đổi toạ độ bản đồ thành các toạ độ thông dụng hơn dấu cách, Chế độ xem lớp phủ WebGL cung cấp Hàm trợ giúp coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) trong hook onDraw() chứa các hàm sau và trả về một Float64Array:

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

Ví dụ: các đoạn mã sau đây sử dụng fromLatLngAltitude() để tạo một camera ma trận chiếu 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 đồ. Đối với hướng dẫn hoàn chỉnh về việc 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ử Xây dựng lớp học lập trình Trải nghiệm bản đồ được tăng tốc bằng 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);