عرض تراكب WebGL

عرض النموذج

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