С помощью 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);