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

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

С помощью WebGL Overlay View вы можете добавлять контент на свои карты, используя WebGL напрямую или популярные графические библиотеки, такие как Three.js. WebGL Overlay View обеспечивает прямой доступ к тому же контексту рендеринга WebGL, который платформа Google Maps использует для рендеринга векторной базовой карты. Такое использование общего контекста рендеринга обеспечивает такие преимущества, как окклюзия глубины с трехмерной геометрией зданий и возможность синхронизации 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 Overlay View раскрывает контекст рендеринга 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 не было сброшено.

Координатные преобразования

Положение объекта на векторной карте указывается путем указания комбинации координат широты и долготы, а также высоты. Однако 3D-графика указывается в мировом пространстве, пространстве камеры или пространстве экрана. Чтобы упростить преобразование координат карты в эти более часто используемые пространства, 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 с открытым исходным кодом, для размещения 3D-объекта на карте. Для полного пошагового руководства по использованию WebGL Overlay View для создания примера, который вы видите запущенным в верхней части этой страницы, попробуйте лабораторную работу Building WebGL-accelerated Map Experiences .

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