عرض تراكب 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(). على سبيل المثال، يوفر ثلاثة.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);