العرض المركّب باستخدام WebGL

عرض نموذج

باستخدام العرض المركّب باستخدام WebGL، يمكنك إضافة محتوى إلى خرائطك مباشرةً باستخدام WebGL، أو مكتبات الرسومات الشائعة، مثل Three.js. توفّر العرض المركّب باستخدام WebGL إمكانية الوصول المباشر إلى سياق العرض نفسه الذي تستخدمه "منصة خرائط Google" لعرض الخريطة الأساسية المتّجهة. ويوفّر استخدام سياق العرض المشترك هذا مزايا، مثل حجب العمق باستخدام أشكال هندسية ثلاثية الأبعاد للمباني، وإمكانية مزامنة المحتوى الثنائي الأبعاد/الثلاثي الأبعاد مع عرض الخريطة الأساسية. يمكن أيضًا ربط العناصر المعروضة باستخدام WebGL Overlay View بإحداثيات خط العرض وخط الطول، وبالتالي تتحرّك هذه العناصر عند سحب الخريطة أو تكبيرها أو تصغيرها أو تحريكها أو إمالتها.

المتطلبات

لاستخدام العرض المركّب باستخدام 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);