開始使用場景

本頁說明如何探索 Hello Sceneform 範例應用程式中的重要概念。注意：

  • 這個範例使用 Sceneform 和 ARCore。

    如要在不使用 ARCore 的情況下使用場景，請按照下列步驟忽略 ARCore 依附元件和 CAMERA 權限需求。按照建構場景中的說明，在應用程式的版面配置中使用 SceneView。

  • 這個範例應用程式是以 AR 必要應用程式編寫。

    如要進一步瞭解「AR 選擇性」與「需要 AR」的應用程式，請參閱啟用 ARCore。

如要開始使用專案中的場景場景，您必須：

  1. 匯入 Sceneform 外掛程式
  2. 設定專案的 build.gradle 檔案
  3. 更新 AndroidManifest.xml
  4. 執行執行階段檢查並建立情境檢視畫面
  5. 建立可轉譯項目
  6. 建構場景

將 Sceneform 外掛程式匯入專案

安裝完成後，Sceneform 外掛程式可讓您透過 Android Studio 中的 Sceneform SDK 匯入、檢視和建構 3D 素材資源。需要 Android Studio 3.1 以上版本。

如何安裝外掛程式：

  1. 在 Android Studio 中開啟「Plugins」(外掛程式) 設定：

    • Windows：檔案 > 設定 > 外掛程式 >瀏覽存放區

    • macOS：Android Studio > Preferences > 外掛程式

  2. 按一下 [Browse repositories]，然後安裝 Google Sceneform Tools (Beta 版)。

設定專案的 build.gradle 檔案

  1. 請確認您的專案 build.gradle 含有 Google 的 Maven 存放區：

    allprojects {
    repositories {
        google()
        …

  2. 更新應用程式的 build.gradle 以新增最新的 ARCore 和場景場景使用者體驗依附元件，並確保專案設定與這兩個程式庫相容。

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

更新AndroidManifest.xml

修改 AndroidManifest.xml，表明您的應用程式使用 (AR 選用) 或需要 (AR 必填) ARCore 和 CAMERA 存取權：

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

執行執行階段檢查並建立情境檢視畫面

如要開始使用場景和建立情境檢視畫面，最簡單的方法是使用 ArFragment，因為在執行必要的 ARCore 執行階段檢查後，系統會自動處理 ARCore 工作階段管理：

  1. 檢查是否已安裝相容的 AR 專用 Google Play 服務版本，並提示使用者視需要安裝或更新

  2. 檢查應用程式是否可存取相機，如果使用者尚未授予權限，系統會要求使用者授予權限

如果應用程式需要要求其他權限，或想自訂 AR 工作階段的建立方式和時間，可以改為：

  • 要求 ArFragment 的子類別以要求其他權限。

  • 直接使用或擴充 ArSceneView。如 太陽能系統範例所示，您的應用程式必須執行 ARCore 版本檢查並呼叫 setupSession() 以手動建立 ARCore 工作階段。

通過檢查後，ArFragment 會建立：

  1. 可透過 getArSceneView() 存取的 ArSceneView：

    • 從工作階段將相機圖片算繪到表面上

    • 轉譯內建的場景場景使用者體驗動畫，讓使用者瞭解如何移動手機以啟動 AR 體驗。

    • 使用預設 PlaneRenderer 偵測到的精選內容 Planes

  2. 可透過 getSession() 存取的 ARCore Session

如要在應用程式中使用 ArFragment，請將其新增至活動的版面配置中，如 Hello Sceneform 範例中的 activity_ux.xml 示範：

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

建立可轉譯項目

Renderable 是一個 3D 模型，可放在場景中的任何位置，由網格、材質和紋理組成。

您可透過下列工具建立可轉譯項目：

範例應用程式可使用 3D andy.obj 素材資源檔案建立可轉譯。匯入這項資產時，場景外掛程式會更新應用程式 build.gradle 以套用外掛程式，並為匯入的模型新增 sceneform.asset() 項目：

apply plugin: 'com.google.ar.sceneform.plugin'

sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
                'default',                    // 'Material Path' specified during import.
                'sampledata/models/andy.sfa', // '.sfa Output Path' specified during import.
                'src/main/res/raw/andy')      // '.sfb Output Path' specified during import.

res/raw/andy 資源用於建立 ModelRenderable：

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

建構場景

ARSceneView 已附加 Scene。場景是樹狀資料結構，用於存放要算繪的虛擬物件 Node。

這裡，andy 可轉譯直接附加至根 Scene 節點：

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

每個節點都包含 Sceneform 提供轉譯的所有資訊 (包括其位置、方向和可轉譯的物件)，以及與節點的互動 (包括其衝突形狀和事件監聽器)。

節點可以新增至其他節點，形成父項/子項關係。當節點為另一個節點的子項，系統會其父項移動、旋轉及縮放，例如手臂移動時的手部移動方式。一個節點可以有多個子項，但只有一個父項，進而建立樹狀結構。這個結構稱為「情境圖表」。

每個場景，「場景」都是從相機的視角轉譯 (由 ARCore 動作追蹤所引導) 的場景圖。應用程式可以監聽觸控和手勢事件、對節點執行命中測試，以及放置錨點，藉此與場景互動。詳情請參閱建構場景並進行互動。