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

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

С помощью WebGL Overlay View вы можете добавлять контент на карты напрямую, используя WebGL или популярные графические библиотеки, такие как Three.js. WebGL Overlay View обеспечивает прямой доступ к тому же контексту рендеринга WebGL, который платформа Google Карт использует для рендеринга векторной базовой карты. Использование общего контекста рендеринга обеспечивает такие преимущества, как перекрытие глубины при использовании трёхмерной геометрии зданий и возможность синхронизации 2D/3D-контента с рендерингом базовой карты. Объекты, отображаемые с помощью WebGL Overlay View, также можно привязать к координатам широты/долготы, чтобы они перемещались при перетаскивании, масштабировании, панорамировании или наклоне карты.

Требования

Чтобы использовать WebGL Overlay View, необходимо загрузить карту, используя идентификатор карты с включённой векторной картой. Настоятельно рекомендуем включить наклон и поворот при создании идентификатора карты, чтобы обеспечить полное управление 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 отображает контекст рендеринга базовой карты WebGL. Поэтому крайне важно сбросить состояние GL в исходное состояние после завершения рендеринга объектов. Отсутствие сброса состояния GL может привести к конфликтам состояний GL, что приведёт к сбою рендеринга как карты, так и любых указанных вами объектов.

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

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

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

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

Положение объекта на векторной карте задаётся комбинацией координат широты и долготы, а также высоты. В трёхмерной графике координаты задаются в мировом пространстве, пространстве камеры или пространстве экрана. Чтобы упростить преобразование координат карты в эти более распространённые пространства, WebGL Overlay View предоставляет вспомогательную функциюordinateTransformer.fromLatLngAltitude coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) в хуке onDraw() , которая принимает следующие данные и возвращает массив 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 с открытым исходным кодом, для размещения трёхмерного объекта на карте. Полное руководство по использованию 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);