عرض تراكب 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);