Режим наложения в WebGL

Посмотреть образец

With WebGL Overlay View you can add content to your maps using WebGL directly, or popular Graphics libraries like Three.js. WebGL Overlay View provides direct access to the same WebGL rendering context Google Maps Platform uses to render the vector basemap. This use of a shared rendering context provides benefits such as depth occlusion with 3D building geometry, and the ability to sync 2D/3D content with basemap rendering. Objects rendered with the WebGL Overlay View can also be tied to latitude/longitude coordinates, so they move when you drag, zoom, pan, or tilt the map.

Требования

Для использования режима наложения WebGL необходимо загрузить карту, используя идентификатор карты с включенной векторной картой. Мы настоятельно рекомендуем включить наклон и вращение при создании идентификатора карты, чтобы обеспечить полный контроль над 3D-камерой. Подробности см. в обзоре .

Добавить наложенное представление WebGL

Чтобы добавить наложение на вашу карту, реализуйте интерфейс google.maps.WebGLOverlayView , а затем передайте ему экземпляр вашей карты с помощью 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);

Зацепки жизненного цикла

WebGL Overlay View предоставляет набор обработчиков событий, которые вызываются в различные моменты жизненного цикла контекста рендеринга WebGL для векторной базовой карты. В этих обработчиках жизненного цикла вы настраиваете, отрисовываете и удаляете все, что хотите отобразить в оверлее.

  • onAdd() вызывается при создании наложения. Используйте его для получения или создания промежуточных структур данных перед отрисовкой наложения, которые не требуют немедленного доступа к контексту рендеринга WebGL.
  • onContextRestored({gl}) вызывается после того, как контекст рендеринга становится доступен. Используйте его для инициализации или привязки любого состояния WebGL, такого как шейдеры, объекты буфера GL и так далее. onContextRestored() принимает экземпляр WebGLStateOptions , который имеет одно поле:
    • gl — это дескриптор объекта WebGLRenderingContext , используемого базовой картой.
  • onDraw({gl, transformer}) отображает сцену на базовой карте. Параметры для onDraw() представляют собой объект WebGLDrawOptions , который имеет два поля:
    • gl — это дескриптор объекта WebGLRenderingContext , используемого базовой картой.
    • transformer предоставляет вспомогательные функции для преобразования координат карты в матрицу проекции модели-вида, которая может использоваться для перевода координат карты в мировое пространство, пространство камеры и экранное пространство.
  • onContextLost() вызывается при потере контекста рендеринга по любой причине, и именно здесь следует очистить любое существующее состояние GL, поскольку оно больше не требуется.
  • onStateUpdate({gl}) обновляет состояние GL вне цикла рендеринга и вызывается при вызове requestStateUpdate . Он принимает экземпляр WebGLStateOptions , который имеет одно поле:
    • gl — это дескриптор объекта WebGLRenderingContext , используемого базовой картой.
  • onRemove() вызывается при удалении наложения с карты с помощью WebGLOverlayView.setMap(null) , и именно здесь следует удалить все промежуточные объекты.

Например, ниже представлена ​​базовая реализация всех хуков жизненного цикла:

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

Сброс состояния GL

WebGL Overlay View предоставляет доступ к контексту рендеринга WebGL базовой карты. Поэтому крайне важно сбросить состояние GL до исходного состояния после завершения рендеринга объектов. Несоблюдение этого требования может привести к конфликтам состояний GL, что вызовет сбой рендеринга как карты, так и любых указанных вами объектов.

Сброс состояния GL обычно обрабатывается в хуке onDraw() . Например, Three.js предоставляет вспомогательную функцию, которая отменяет любые изменения состояния GL:

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

Если карта или ваши объекты не отображаются, весьма вероятно, что состояние GL не было сброшено.

Преобразования координат

The position of an object on the vector map is specified by providing a combination of latitude and longitude coordinates, as well as altitude. 3D graphics, however, are specified in world space, camera space, or screen space. To make it easier to transform map coordinates to these more commonly used spaces, WebGL Overlay View provides the coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) helper function in the onDraw() hook that takes the following and returns a Float64Array :

  • latLngAltitude : Координаты широты/долготы/высоты, представленные либо в виде LatLngAltitude , либо в LatLngAltitudeLiteral .
  • rotationArr : Float32Array содержащий углы поворота Эйлера, заданные в градусах.
  • scalarArr : Массив скалярных значений Float32Array , применяемых к кардинальной оси.

Например, в следующем примере fromLatLngAltitude() используется для создания матрицы проекции камеры в 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);

Пример

Ниже приведён простой пример использования Three.js , популярной библиотеки WebGL с открытым исходным кодом, для размещения 3D-объекта на карте. Для полного пошагового руководства по использованию WebGL Overlay View для создания примера, который вы видите вверху этой страницы, попробуйте пройти мастер-класс «Создание картографических интерфейсов с ускорением 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);