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

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

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

Требования

Для использования режима наложения 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 не было сброшено.

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

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