มุมมองการวางซ้อนของ WebGL

ดูตัวอย่าง

มุมมองการวางซ้อน WebGL ช่วยให้คุณเพิ่มเนื้อหาลงในแผนที่ได้โดยใช้ WebGL โดยตรง หรือใช้ไลบรารีกราฟิกยอดนิยมอย่าง Three.js มุมมองภาพซ้อนทับ WebGL ช่วยให้เข้าถึงบริบทการแสดงผล WebGL เดียวกันกับที่ Google Maps Platform ใช้ในการแสดงผลแผนที่ฐานแบบเวกเตอร์ได้โดยตรง การใช้บริบทการแสดงผลที่แชร์นี้มีประโยชน์ เช่น การบดบังเชิงลึกด้วยรูปทรงเรขาคณิตของอาคาร 3 มิติ และความสามารถในการซิงค์เนื้อหา 2 มิติ/3 มิติ กับการแสดงผลแผนที่ฐาน นอกจากนี้ วัตถุที่แสดงผลด้วยมุมมองการวางซ้อน WebGL ยังเชื่อมโยงกับพิกัดละติจูด/ลองจิจูดได้ด้วย ดังนั้นวัตถุจะเคลื่อนที่เมื่อคุณลาก ซูม เลื่อน หรือเอียงแผนที่

ข้อกำหนด

หากต้องการใช้ WebGL Overlay View คุณต้องโหลดแผนที่โดยใช้รหัสแผนที่ที่เปิดใช้แผนที่เวกเตอร์ เราขอแนะนำอย่างยิ่งให้เปิดใช้การเอียงและการหมุนเมื่อสร้างรหัสแผนที่ เพื่อให้ควบคุมกล้อง 3 มิติได้อย่างเต็มที่ ดูรายละเอียดได้ที่ภาพรวม

เพิ่มมุมมองการวางซ้อนของ 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);

Hook วงจรการใช้งาน

มุมมองการวางซ้อนของ WebGL มีชุดฮุกที่เรียกใช้ในเวลาต่างๆ ในวงจรของบริบทการแสดงผล WebGL ของแผนที่ฐานแบบเวกเตอร์ ฮุกวงจรนี้เป็นที่ที่คุณตั้งค่า วาด และลบทุกอย่างที่ต้องการ แสดงในโอเวอร์เลย์

• onAdd() จะเรียกใช้เมื่อสร้างภาพซ้อนทับ ใช้เพื่อดึงข้อมูลหรือ สร้างโครงสร้างข้อมูลกลางก่อนที่จะวาดภาพซ้อนทับ ซึ่งไม่ ต้องเข้าถึงบริบทการแสดงผล WebGL ทันที
• onContextRestored({gl}) จะเรียกใช้เมื่อบริบทการแสดงผลพร้อมใช้งาน ใช้เพื่อเริ่มต้นหรือเชื่อมโยงสถานะ WebGL เช่น Shader, ออบเจ็กต์บัฟเฟอร์ GL และอื่นๆ onContextRestored() รับอินสแตนซ์ WebGLStateOptions ซึ่งมีฟิลด์เดียว ดังนี้
  • gl คือแฮนเดิลของ WebGLRenderingContext ที่ใช้โดยแผนที่ฐาน
• onDraw({gl, transformer}) จะแสดงฉากบนแผนที่ฐาน พารามิเตอร์สำหรับ onDraw() คือออบเจ็กต์ WebGLDrawOptions ซึ่งมีฟิลด์ 2 รายการ
  • 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 มีฟังก์ชัน Helper ที่ล้างการเปลี่ยนแปลงสถานะ GL

webglOverlayView.onDraw = ({gl, transformer}) => {
  // Specify an object to render.
  renderer.render(scene, camera);
  renderer.resetState();
}

หากแผนที่หรือออบเจ็กต์แสดงผลไม่สำเร็จ อาจเป็นไปได้ว่ายังไม่ได้รีเซ็ตสถานะ GL

การแปลงพิกัด

ตำแหน่งของออบเจ็กต์บนแผนที่เวกเตอร์จะระบุโดยการระบุ ชุดค่าผสมของพิกัดละติจูดและลองจิจูด รวมถึงระดับความสูง อย่างไรก็ตาม กราฟิก 3 มิติจะระบุในพื้นที่โลก พื้นที่กล้อง หรือพื้นที่หน้าจอ มุมมองการวางซ้อนของ 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 แบบโอเพนซอร์สที่ได้รับความนิยม เพื่อวางออบเจ็กต์ 3 มิติบนแผนที่ หากต้องการดูคำแนะนำแบบสมบูรณ์เกี่ยวกับการใช้มุมมองการวางซ้อนของ WebGL เพื่อสร้างตัวอย่างที่คุณเห็นทำงานที่ด้านบนของหน้านี้ ให้ลองใช้ Codelab การสร้างประสบการณ์การใช้งานแผนที่ที่เร่งด้วย 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);