عرض تراكب WebGL

عرض نموذج

باستخدام عرض تراكب WebGL، يمكنك إضافة محتوى إلى خرائطك باستخدام WebGL مباشرةً، أو مكتبات الرسومات الشائعة مثل Three.js. توفّر ميزة "عرض التراكب باستخدام WebGL" إمكانية الوصول المباشر إلى سياق عرض WebGL نفسه الذي تستخدمه "منصة خرائط Google" لعرض الخريطة الأساسية المستندة إلى المتجهات. يقدّم هذا الاستخدام لسياق العرض المشترَك مزايا، مثل حجب العمق باستخدام هندسة المباني الثلاثية الأبعاد، والقدرة على مزامنة المحتوى المكوّن من رسومات ثنائية/ثلاثية الأبعاد مع عرض الخريطة الأساسية. ويمكن أيضًا ربط الكائنات المعروضة باستخدام العرض المركّب في 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 الذي تستخدمه الخريطة الأساسية.
• يتمّ استدعاء 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 الدالة المساعِدة 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" لإنشاء المثال الذي يظهر أمامك في أعلى هذه الصفحة، يمكنك تجربة الدرس التطبيقي حول إنشاء تجارب خرائط مُسرَّعة باستخدام 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);