نمای رونهاد WebGL

مشاهده نمونه

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

الزامات

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

افزودن نمای رونهاد 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» مجموعه‌ای از قلاب‌ها را ارائه می‌دهد که در زمان‌های مختلف در چرخه حیات زمینه 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 است که نقشه پایه از آن استفاده می‌کند.
• وقتی رونهاد با WebGLOverlayView.setMap(null) از نقشه برداشته می‌شود، onRemove() فراخوانده می‌شود و در اینجا باید همه اشیاء واسطه را بردارید.

برای مثال، پیاده‌سازی پایه همه قلاب‌های چرخه حیات به‌صورت زیر است:

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» تابع کمکی 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» برای ساختن نمونه‌ای که در بالای این صفحه درحال اجرا می‌بینید، codelab ساختن تجربه‌های نقشه با شتاب 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);