本頁面由 Cloud Translation API 翻譯而成。

在 Android NDK 應用程式中使用深度

Depth API 可協助裝置的相機瞭解場景中真實物體的大小和形狀。這項功能會使用相機拍攝深度圖片或深度地圖，為應用程式增添 AR 寫實感。您可以運用深度圖片提供的資訊，讓虛擬物件準確出現在現實世界中或物件後方，帶來身歷其境且逼真的使用者體驗。

深度資訊是根據動作計算得出，可能會與硬體深度感應器的資訊結合，例如飛行時間 (ToF) 感應器 (如有)。裝置不需要 ToF 感應器即可支援 Depth API。

必要條件

請務必瞭解基本 AR 概念以及如何在繼續操作前設定 ARCore 工作階段。

限制存取深度支援裝置

如果您的應用程式需要 Depth API 支援，原因可能是 AR 體驗需要深度，或是缺乏流暢的備用選項您可以選擇限制應用程式發行範圍請前往 Google Play 商店支援 Depth API 的裝置 (方法是在除了 AndroidManifest.xml 《AndroidManifest.xml》「啟用 ARCore」指南：

<uses-feature android:name="com.google.ar.core.depth" />

啟用深度

在新的 ARCore 工作階段中，檢查使用者的裝置是否支援深度。基於處理電源限制，並非所有與 ARCore 相容的裝置都支援 Depth API。為節省資源，ARCore 預設會停用深度功能。啟用深度模式，讓應用程式使用 Depth API。

// Check whether the user's device supports the Depth API.
int32_t is_depth_supported = 0;
ArSession_isDepthModeSupported(ar_session, AR_DEPTH_MODE_AUTOMATIC,
                               &is_depth_supported);

// Configure the session for AR_DEPTH_MODE_AUTOMATIC.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
if (is_depth_supported) {
  ArConfig_setDepthMode(ar_session, ar_config, AR_DEPTH_MODE_AUTOMATIC);
}
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
ArConfig_destroy(ar_config);

取得深度圖片

呼叫 ArFrame_acquireDepthImage16Bits() 即可取得目前影格的深度圖片。

// Retrieve the depth image for the current frame, if available.
ArImage* depth_image = NULL;
// If a depth image is available, use it here.
if (ArFrame_acquireDepthImage16Bits(ar_session, ar_frame, &depth_image) !=
    AR_SUCCESS) {
  // No depth image received for this frame.
  // This normally means that depth data is not available yet.
  // Depth data will not be available if there are no tracked
  // feature points. This can happen when there is no motion, or when the
  // camera loses its ability to track objects in the surrounding
  // environment.
  return;
}

傳回的圖片會提供原始圖片緩衝區，這個緩衝區可傳遞到片段著色器，讓 GPU 上的每個算繪物件被遮蔽。此 API 使用 AR_COORDINATES_2D_OPENGL_NORMALIZED_DEVICE_COORDINATES，並可透過呼叫 ArFrame_transformCoordinates2d() 變更為 AR_COORDINATES_2D_TEXTURE_NORMALIZED。可在物件著色器中存取深度圖片後，可直接存取這些深度測量結果進行遮蔽處理。

瞭解深度值

觀察到的實際幾何圖形和 2D 點 a 上的已知點 A 代表深度圖片中的相同點，也就是深度圖片提供的值 a 處的 API 等於投影到主要軸的 CA 長度。這也稱為相機相對於 A 的 z 座標來源：C。使用 Depth API 時，請務必瞭解深度值不是灰色 CA 本身的長度，而是投影我們很快就會深入探討所以目前先概略介紹

使用深度著色器

剖析目前影格的深度資訊

在片段著色器中使用輔助函式 DepthGetMillimeters() 和 DepthGetVisibility()，存取目前畫面位置的深度資訊。然後使用這項資訊，選擇性地遮蔽算繪物件的部分。

// Use DepthGetMillimeters() and DepthGetVisibility() to parse the depth image
// for a given pixel, and compare against the depth of the object to render.
float DepthGetMillimeters(in sampler2D depth_texture, in vec2 depth_uv) {
  // Depth is packed into the red and green components of its texture.
  // The texture is a normalized format, storing millimeters.
  vec3 packedDepthAndVisibility = texture2D(depth_texture, depth_uv).xyz;
  return dot(packedDepthAndVisibility.xy, vec2(255.0, 256.0 * 255.0));
}

// Return a value representing how visible or occluded a pixel is relative
// to the depth image. The range is 0.0 (not visible) to 1.0 (completely
// visible).
float DepthGetVisibility(in sampler2D depth_texture, in vec2 depth_uv,
                         in float asset_depth_mm) {
  float depth_mm = DepthGetMillimeters(depth_texture, depth_uv);

  // Instead of a hard Z-buffer test, allow the asset to fade into the
  // background along a 2 * kDepthTolerancePerMm * asset_depth_mm
  // range centered on the background depth.
  const float kDepthTolerancePerMm = 0.015f;
  float visibility_occlusion = clamp(0.5 * (depth_mm - asset_depth_mm) /
    (kDepthTolerancePerMm * asset_depth_mm) + 0.5, 0.0, 1.0);

 // Use visibility_depth_near to set the minimum depth value. If using
 // this value for occlusion, avoid setting it too close to zero. A depth value
 // of zero signifies that there is no depth data to be found.
  float visibility_depth_near = 1.0 - InverseLerp(
      depth_mm, /*min_depth_mm=*/150.0, /*max_depth_mm=*/200.0);

  // Use visibility_depth_far to set the maximum depth value. If the depth
  // value is too high (outside the range specified by visibility_depth_far),
  // the virtual object may get inaccurately occluded at further distances
  // due to too much noise.
  float visibility_depth_far = InverseLerp(
      depth_mm, /*min_depth_mm=*/7500.0, /*max_depth_mm=*/8000.0);

  const float kOcclusionAlpha = 0.0f;
  float visibility =
      max(max(visibility_occlusion, kOcclusionAlpha),
          max(visibility_depth_near, visibility_depth_far));

  return visibility;
}

省略虛擬物件

在片段著色器的主體中省略虛擬物件。根據物件的深度更新物件的 Alpha 通道。這會顯示遭遮蔽的物件。

// Occlude virtual objects by updating the object’s alpha channel based on its depth.
const float kMetersToMillimeters = 1000.0;

float asset_depth_mm = v_ViewPosition.z * kMetersToMillimeters * -1.;

// Compute the texture coordinates to sample from the depth image.
vec2 depth_uvs = (u_DepthUvTransform * vec3(v_ScreenSpacePosition.xy, 1)).xy;

gl_FragColor.a *= DepthGetVisibility(u_DepthTexture, depth_uvs, asset_depth_mm);

您可以使用兩道算繪或個別物件的正向傳遞算繪，算繪遮蔽情形。每個方法的效率都取決於場景的複雜程度，以及其他應用程式特有的考量因素。

每個物件的正向傳遞轉譯

個別物件的正向循環算繪會決定該物件在其 Material 著色器中每個像素的遮蔽情形。如果像素看不見，就會遭到裁剪 (通常是透過 Alpha 混合)，進而模擬使用者裝置上的遮蔽情形。

雙通道算繪

透過雙傳遞算繪，第一個傳遞會將所有虛擬內容算繪到中介緩衝區。第二張票證根據實際深度與虛擬場景深度之間的差異，將虛擬場景融入背景。這種方法不需要其他物件專屬的著色器工作，而且通常會產生比轉寄傳遞方法更加統一的結果。

轉換相機圖像和深度圖片之間的座標

相較於深度圖片，使用 ArFrame_acquireCameraImage() 取得的圖片可能會有不同的顯示比例。在這種情況下，縱深圖片是相機圖片的裁剪，因此相機影像中並非所有像素都有相應的有效深度估計值。

如要取得 CPU 圖像座標的深度圖片座標：

const float cpu_image_coordinates[] = {(float)cpu_coordinate_x,
                                 (float)cpu_coordinate_y};
float texture_coordinates[2];
ArFrame_transformCoordinates2d(
    ar_session, ar_frame, AR_COORDINATES_2D_IMAGE_PIXELS, 1,
    cpu_image_coordinates, AR_COORDINATES_2D_TEXTURE_NORMALIZED,
    texture_coordinates);
if (texture_coordinates[0] < 0 || texture_coordinates[1] < 0) {
  // There are no valid depth coordinates, because the coordinates in the CPU
  // image are in the cropped area of the depth image.
} else {
  int depth_image_width = 0;
  ArImage_getWidth(ar_session, depth_image, &depth_image_width);
  int depth_image_height = 0;
  ArImage_getHeight(ar_session, depth_image, &depth_image_height);

  int depth_coordinate_x = (int)(texture_coordinates[0] * depth_image_width);
  int depth_coordinate_y = (int)(texture_coordinates[1] * depth_image_height);
}

如何取得深度圖片座標的 CPU 圖片座標：

int depth_image_width = 0;
ArImage_getWidth(ar_session, depth_image, &depth_image_width);
int depth_image_height = 0;
ArImage_getHeight(ar_session, depth_image, &depth_image_height);

float texture_coordinates[] = {
    (float)depth_coordinate_x / (float)depth_image_width,
    (float)depth_coordinate_y / (float)depth_image_height};
float cpu_image_coordinates[2];
ArFrame_transformCoordinates2d(
    ar_session, ar_frame, AR_COORDINATES_2D_TEXTURE_NORMALIZED, 1,
    texture_coordinates, AR_COORDINATES_2D_IMAGE_PIXELS,
    cpu_image_coordinates);

int cpu_image_coordinate_x = (int)cpu_image_coordinates[0];
int cpu_image_coordinate_y = (int)cpu_image_coordinates[1];

深度點擊測試

命中測試可讓使用者將物件放置在場景中的實際位置。先前您只能針對偵測到的飛機執行命中測試，將位置限制在大型平坦的平面上，例如綠色 Android 顯示的結果。深度命中測試利用流暢與原始的深度資訊，提供更精確的命中結果，即使在非平面和低紋理表面上也一樣。如紅色 Android 所示。

如要使用深度啟用命中測試，請呼叫 ArFrame_hitTest()，然後檢查傳回清單中是否有 AR_TRACKABLE_DEPTH_POINT。

// Create a hit test using the Depth API.
ArHitResultList* hit_result_list = NULL;
ArHitResultList_create(ar_session, &hit_result_list);
ArFrame_hitTest(ar_session, ar_frame, hit_x, hit_y, hit_result_list);

int32_t hit_result_list_size = 0;
ArHitResultList_getSize(ar_session, hit_result_list, &hit_result_list_size);

ArHitResult* ar_hit_result = NULL;
for (int32_t i = 0; i < hit_result_list_size; ++i) {
  ArHitResult* ar_hit = NULL;
  ArHitResult_create(ar_session, &ar_hit);
  ArHitResultList_getItem(ar_session, hit_result_list, i, ar_hit);

  ArTrackable* ar_trackable = NULL;
  ArHitResult_acquireTrackable(ar_session, ar_hit, &ar_trackable);
  ArTrackableType ar_trackable_type = AR_TRACKABLE_NOT_VALID;
  ArTrackable_getType(ar_session, ar_trackable, &ar_trackable_type);
  // Creates an anchor if a plane or an oriented point was hit.
  if (AR_TRACKABLE_DEPTH_POINT == ar_trackable_type) {
    // Do something with the hit result.
  }
  ArTrackable_release(ar_trackable);
  ArHitResult_destroy(ar_hit);
}

ArHitResultList_destroy(hit_result_list);

後續步驟

使用 Raw Depth API 啟用更準確的感應功能。
歡迎查看 ARCore Depth Lab，瞭解存取深度資料的各種方式。