نمای همپوشانی WebGL

مشاهده نمونه

با WebGL Overlay View می‌توانید با استفاده از WebGL یا کتابخانه‌های گرافیکی محبوب مانند Three.js محتوا را به نقشه‌های خود اضافه کنید. WebGL Overlay View دسترسی مستقیم به همان زمینه رندر WebGL را فراهم می کند که پلتفرم Google Maps برای ارائه نقشه پایه برداری استفاده می کند. این استفاده از زمینه رندر مشترک مزایایی مانند انسداد عمق با هندسه ساختمان سه بعدی و توانایی همگام سازی محتوای 2 بعدی/3 بعدی با رندر بیس مپ را فراهم می کند. اشیاء ارائه شده با نمای پوشش WebGL همچنین می توانند به مختصات طول و عرض جغرافیایی متصل شوند، بنابراین هنگام کشیدن، زوم، حرکت یا کج کردن نقشه حرکت می کنند.

الزامات

برای استفاده از WebGL Overlay View، باید نقشه را با استفاده از شناسه نقشه با فعال بودن نقشه برداری بارگیری کنید. اکیداً توصیه می کنیم هنگام ایجاد شناسه نقشه، شیب و چرخش را فعال کنید تا امکان کنترل کامل دوربین سه بعدی فراهم شود. برای جزئیات به نمای کلی مراجعه کنید .

نمای Overlay 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 بازنشانی نشده است.

تحولات مختصات

موقعیت یک شی در نقشه برداری با ارائه ترکیبی از مختصات طول و عرض جغرافیایی و همچنین ارتفاع مشخص می شود. با این حال، گرافیک سه بعدی در فضای جهان، فضای دوربین یا فضای صفحه نمایش مشخص می شود. برای آسان‌تر کردن تبدیل مختصات نقشه به این فضاهای پرکاربرد، WebGL Overlay View تابع کمکی coordinateTransformer.fromLatLngAltitude(latLngAltitude, rotationArr, scalarArr) در قلاب onDraw() ارائه می‌کند که موارد زیر را می‌گیرد و Float64Array برمی‌گرداند:

  • latLngAltitude : مختصات 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 برای ساختن نمونه‌ای که در بالای این صفحه مشاهده می‌کنید، از 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);