Jetpack SceneCore

使用 3D 內容建構及操控 Android XR 場景圖。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2026 年 10 月 21 日 1.0.0 - - 1.1.0-alpha01

宣告依附元件

如要新增 XR SceneCore 的依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.1.0-alpha01"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.1.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.1.0-alpha01")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.1.0-alpha01")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

1.1 版本

1.1.0-alpha01 版本

2026 年 10 月 21 日

發布 androidx.xr.scenecore:scenecore-*:1.1.0-alpha01。1.1.0-alpha01 版包含這些修訂項目。

API 變更

  • 新增動態網格更新 API (MeshBuffer.createDynamic、MeshBuffer.updateVertexData、MeshBuffer.updateIndexData 和動態 CustomMesh.BuilderFromMeshData 建構函式)，支援在執行階段更新頂點和索引資料。(Ia1ecb)
  • 新增 VertexLayout.getBufferIndex 輔助方法，可輕鬆擷取指定 VertexAttribute 或 VertexBufferLayout 的緩衝區索引。(I1a9e3)
  • 將 CustomMesh.bounds 設為 var，以便在執行階段動態更新定界框。(Ib0397)
  • 將 glTF Animation API (GltfAnimation、GltfModelEntity.getAnimations 和 GltfModelEntity.stopAllAnimations) 升級為公開/穩定版，同時保留 GltfAnimation.loop setter 做為實驗功能，並將 GltfAnimationStartOptions 和 start(options) 設為實驗功能和已淘汰。(Iacdae)
  • 在 GltfModelEntity 中新增 stopAllAnimations()、將 GltfAnimation.start() 設為無參數、在 GltfAnimation 中新增 loop 和 speed 屬性，並淘汰 GltfAnimationStartOptions、start(options) 和 seekTo(Duration)。(I53105)
  • 更新 GltfModelEntity API，在對已處置的實體呼叫時，記錄 IllegalStateException (特別是 Entity.DisposedException)。I65a76f

修正錯誤

  • androidx.lifecycle:lifecycle-runtime 依附元件已更新至 2.10.0。如要搭配 AGP 9.5.0-alpha04 以上版本執行套裝生命週期執行階段 Lint 檢查，則必須使用這個版本。(I99bfd、b/556807521)
  • 改善與 AudioOutputProvider 相關的 kdoc，強調不應與多個 ExoPlayer 執行個體重複使用 (I6b18e)
  • 從多個 XR 模組中移除對 impress 的不必要依附元件。I84636c

1.0 版本

1.0.0 版

2026 年 10 月 21 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0。1.0.0 版包含這些修訂項目。

1.0.0 的主要功能：

  • Jetpack XR SceneCore 現已推出穩定版！SceneCore 可讓您放置及排列 3D 內容 (由實體定義)，並根據彼此和環境調整位置。您可以使用 SceneCore，在虛擬和混合實境場景中建立、放置及操控 2D 面板和 3D 模型、指定空間環境和空間音訊來源，以及將虛擬內容錨定至真實世界。
  • 詳情請參閱總覽頁面和 API 參考資料。

1.0.0-rc02 版

2026 年 10 月 7 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-rc02。1.0.0-rc02 版包含這些修訂項目。

修正錯誤

  • 移除 SessionExt 中的 perceptionRuntimeCache，並重構為直接從 Session 執行個體擷取 PerceptionRuntime，藉此修正潛在的記憶體流失問題。(Ie35b1)
  • 針對 OpenXR 原生控制代碼使用 applicationContext，確保原生執行階段不會保留 Activity 內容的參照，藉此修正潛在的內容外洩問題。(Ie35b1)
  • 透過導入適當的同步處理和初始化鎖定機制，修正 XrInstanceManager 中的競爭狀況。(Ie35b1)
  • 修正 ReferenceCleaner 以支援取消註冊清理動作，並確保在 dispose() 期間明確執行 Entity 清理動作，避免在垃圾收集時重複執行。(Ie35b1)
  • 修正 Scene 中的記憶體流失問題：移除 SessionExt 中的 sceneCache，並重構 Scene，直接從 sessionConnectors 擷取執行個體。(Ie35b1)

1.0.0-rc01 版

2026 年 9 月 9 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-rc01。1.0.0-rc01 版本包含這些修訂版本。

API 變更

  • 新增 xr:scenecore:scenecore-openxr 程式庫。(Ic49f2)
  • 在 1.0.0 穩定版推出前，移除多個已淘汰的 API。

修正錯誤

  • 解決記憶體流失錯誤，即 Activity 刪除後，系統仍會保留 Activity 參照。(I6dcd7)

行為變更

  • 已從 SceneCore 移除 Logcat 輸出內容。(I10c3c)

1.0.0-beta02 版

2026 年 8 月 12 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-beta02。1.0.0-beta02 版包含這些修訂項目。

修正錯誤

  • 如果上層實體已進行垃圾收集，toMoveEvent() 會傳回 null。(Ia7a1b)

1.0.0-beta01 版

2026 年 7 月 15 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-beta01。1.0.0-beta01 版包含這些修訂項目。

API 變更

  • GltfAnimation 和 SpatialGltfModelAnimation API 已標示為實驗性質。部分屬性已轉換為 getter。(I8d689、b/524771027)
  • 移除公開的 MovableComponent.createTrackingMovable 工廠方法。(I00912、b/477169015)
  • 將 Session.create 轉換為暫停函式。(I5d27f)
  • ActivitySpace 和 AnchorSpace 現在會擴充常見的 SpaceEntity 類別，其中包含位置由系統控制的實體常見行為 (I506ec、b/513619219)
  • 將 AnchorEntity 更新為 AnchorSpace (Ifa95e、b/513619219)
  • 提供公開測試 API SoundEffectPoolComponentTester。(I87df7、b/498104417)
  • 在 SurfaceEntity.Shape.Quad 建構函式中新增選用的 cornerRadius 參數，並將 cornerRadius 屬性設為公開。開發人員現在可以在建立四邊形時指定圓角半徑，以圓角算繪 SurfaceEntity 畫布，並查詢現有四邊形的半徑。(Ia7809、b/474681085)
  • 提供公開測試 API SpatialAudioTrackBuilderTester、SpatialAudioTrackTester 和 SceneCoreTestRule.getTester 超載。(I378c6、b/496333938)
  • 為多種 ARCore 類型新增 toString() 的專屬覆寫。這些類型旨在為開發人員提供偵錯所需的額外資訊，不適用於正式版或已推出的應用程式。

1.0.0-alpha16 版本

2026 年 6 月 17 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha16。1.0.0-alpha16 版包含這些修訂項目。

API 變更

  • 在 CustomMesh.BuilderFromMeshData 和 CustomMesh.BuilderFromMeshBuffer 中新增 addVertexData、setIndexData 和 addSubset 的超載。開發人員可透過這些超載，直接傳遞原始資料和參數 (例如 ByteBuffer、offset、size、topology、indexOffset、indexCount)，不必包裝在 ByteBufferRegion 或 MeshSubset 等中介物件。(I84d5c)
  • Scene.requestFullSpaceMode() 和 Scene.requestHomeSpaceMode() 已分別重新命名為 requestFullSpace() 和 requestHomeSpace()。其他提及「主畫面模式」和「全螢幕模式」的方法和說明文件也已更新。(I45751)
  • 提供公開測試 API PanelEntityTester 和 MainPanelEntityTester (I961e4)
  • 在 SoundEffectPoolComponent 中新增 pointSourceParams 屬性 (I4a750)
  • 提供公開測試 API MovableComponentTester (I0c972)
  • 提供公開測試 API PointerCaptureComponentTester (Ic0d4f)
  • 提供公開測試 API ActivityPanelEntityTester (I837c4)
  • 提供公開測試 API ResizableComponentTester (I0a3a4)
  • 提供公開測試 API BoundsComponentTester. (Iefd53)
  • 提供公開測試 API SpatialMediaPlayerTester (Ia3e09)
  • 提供公開測試 API SpatialEnvironmentTester (Icf60f)
  • 提供公開測試 API GltfModelTester 和 SceneCoreTestRule.getGltfModelTester。(I33fcb)
  • 提供公開測試 API InteractableComponentTester。(Ia7096)
  • 提供公開測試 API SurfaceEntityTester。(Ic0740)
  • 提供公開測試 API GltfModelEntityTester、TestGltfModelNode 和 TestGltfAnimation。(I72c4d)
  • 提供公開測試 API SceneTester 和 SceneCoreTestRule.sceneTester。(Ib4ec5)
  • 提供公開測試 API PerceptionSpaceTester 和 SceneCoreTestRule.perceptionSpaceTester。(Icf739)
  • 提供公開測試 API MeshEntityTester。(I63801)
  • 提供公開測試 API ImageBasedLightingAssetTester 和 SceneCoreTestRule.getTester 超載。(I57ec4)
  • 提供公開測試 API TextureTester (Ia865b)
  • 提供公開測試 API PositionalAudioComponentTester (Icd96e)
  • 提供公開測試 API SpatialSoundPoolTester (Ia3531)
  • 提供公開測試 API SoundEffectPoolTester (If349a)
  • 提供公開測試 API ActivitySpaceTester 和 SceneCoreTestRule.activitySpaceTester。(I2d5c2)
  • 提供公開測試 API SpatialWindowTester (I41837)
  • 提供公開測試 API AnchorEntityTester (I68404)
  • 提供公開測試 API 介面 SceneCoreTestRule。(Ic72d3)
  • 新增 PixelDensity 類別，並透過 Scene#virtualPixelDensity 公開，提供以硬體為基礎的每公尺像素比例，以便在 ActivitySpace 中準確對應實體尺寸。(I0e3ac)
  • 新增公開 API，用於建立及算繪自訂網格。(I7ad2f)
  • VertexLayout API 已更新為使用 VertexBufferLayout 清單，其中每個 VertexBufferLayout 都會描述單一頂點緩衝區內的屬性。這樣一來，頂點資料的排列方式會更有彈性，包括具有自訂步幅和偏移的交錯屬性。(Ic426b)
  • 提供 MovableComponent.createTrackingMovable，將 ARCore 可追蹤項目轉換為相對於活動空間的姿勢。(I12249)
  • Entity.create 中父項的預設值已更新為空值。(Ic3145)
  • Entity 已更新為類別而非介面，現在是所有實體類型的基礎類別。在本次變更中，我們移除了 BaseEntity。(I7fbc9)
  • GltfModel、ExrImage 和 ImageBasedLightingAsset 現在會實作 AutoCloseable，以便使用 Kotlin 的 use 區塊進行慣用資源管理。(I1ac79)
  • 推出 ImageBasedLightingAsset 類別，取代 ExrImage 來定義空間環境照明。ExrImage 已淘汰，並從公開 API 中移除。SpatialEnvironmentPreference 已更新為使用 ImageBasedLightingAsset。(I6c92a)
  • 將 SpatialEnvironment 中的 skybox 參數重新命名為 imageBasedLightingAsset，以更準確地反映其用途，並明確指出幾何圖形參數應包含視覺天空盒紋理。(I24d4a)
  • 空間實體現在會使用穩定的裝置密度，在空間 API 級別 1 和 2 進行像素到公尺的計算，確保無論系統顯示密度如何變化，大小都能保持一致。(I37051)

1.0.0-alpha15 版本

2026 年 5 月 19 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha15。1.0.0-alpha15 版包含這些修訂項目。

API 變更

  • Entity.dispose() 已從公開 API 中移除。應用程式可以將 parent 設為 null，並清除對這些例項的所有強參照，讓例項可供清除，而不是在 Entity 例項上呼叫 dispose()。(I396c9)
  • SoundEffectPool 的 set/clearOnLoadCompleteListener 方法已刪除。改用 add/removeLoadCompleteListener。(Iae78d)
  • 場景的 set/clearSpatialVisibilityChangedListener 已改為 add/removeSpatialVisibilityChangedListener。(I67dff)
  • 所有 SceneCore add/removeOnFooListener 方法都已重新命名為 add/removeFooListener，並從名稱中移除 On。(Ibe50b)
  • AnchorEntity.setOnOriginChangedListener 和 AnchorEntity.setOnStateChangedListener 方法已替換為 add/removeFooListener 方法，可同時支援多個事件監聽器。(I13749)
  • AnchorEntity.State.TIMEDOUT 已重新命名為 State.TIMED_OUT。(Id2b8d)
  • Component API 經過重構，可提升安全性和擴充性。Component 現在是抽象類別。onAttach() 和 onDetach() 方法現在為 protected，可避免直接呼叫。請使用 Entity.addComponent() 和 Entity.removeComponent() 管理元件生命週期。(Id04e8)
  • SceneCore 的 PlaneSemanticType PlaneOrientation 常數已從 Ints 遷移至自訂類型。系統會移除其 ANY 常數，用戶端應明確列舉所有所需常數，或使用新的 .ALL 不可變 Set 常數。AnchorEntity 工廠方法現在接受一組這類類型，而非單一值。(Ib1033)
  • 實驗性 Custom Mesh API 新增骨架動畫 (蒙皮) 支援。開發人員現在可以建立 MeshEntity 並指定 boneCount，然後使用 MeshEntity.setBoneTransforms() 即時更新動畫，為自訂網格製作動畫。(Id8ba2、b/496692490)
  • 推出實驗性 CustomMesh API。開發人員現在可以使用 CustomMesh、MeshBuffer 和 MeshEntity，以程式輔助方式在場景中建立及算繪 3D 幾何圖形。(I94617)
  • 已移除 androidx.xr.scenecore.SpatializerConstants.SourceType.SOURCE_TYPE_SOUND_FIELD。請改用 SourceType.SOUND_FIELD。(Ia68b9)
  • 新增空間音訊元件：PositionalAudioComponent、SoundEffectPoolComponent 和 SoundFieldAudioComponent (Ieda89)
  • AnchorEntity.getAnchor 已替換為 AnchorEntity.anchor，現在當 AnchorEntity 是從 ARCore Anchor 建立時，會傳回 Anchor (I5c7c8)
  • ActivityPanelEntity、GltfModelEntity、GroupEntity、PanelEntity 和 SurfaceEntity 工廠方法中 parent 參數的預設值已從 ActivitySpace 變更為 null。如要將實體附加至場景圖並顯示，開發人員現在必須在例項化期間或透過 Entity.parent = ... 明確設定其父項 (Ie7cc1)

修正錯誤

  • SceneCore 現在會在 Entity 執行個體變成虛擬可連線時自動回收，開發人員不必明確叫用 dispose() 即可釋出資源。為確保 [Entity] 執行個體能正確回收，開發人員應：
    • 將 parent 設為 null，即可從場景圖中卸除。
    • 在程式碼中，放棄對執行個體的所有強參照。
    • 特殊實體類型注意事項：對於無法設定父項的實體 (例如 AnchorEntity)，開發人員必須在執行個體使用期間，維持強參照。如果所有參照都已釋出，這些執行個體就會變成可存取的幽靈物件，並自動回收。(I83fe4)
  • 縮小所有 SceneCore 程式庫的 Proguard 保留規則範圍。(I98447)

已知問題

  • 如果將 PositionalAudioComponent 附加至 ExoPlayer 執行個體處於停用狀態的 Entity，會導致當機。請勿在 ExoPlayer 停止時呼叫 setPointSourceParams，或附加/卸離空間音訊元件。我們將在下一個版本中修正這個問題。

1.0.0-alpha14 版本

2026 年 5 月 6 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha14。1.0.0-alpha14 版包含這些修訂項目。

API 變更

  • TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，且 androidx.xr.runtime 中的類型現已淘汰。(Ic7930、b/480462213)
  • Plane.Type 已重新命名為 PlaneType。(I8c90c、b/482675376)
  • Plane.Label 已重新命名為 PlaneLabel。(Ic6b67、b/482675376)
  • 淘汰了 androidx.xr.runtime.FieldOfView。請改用 androidx.xr.runtime.math.FieldOfView。(Ia01a0、b/480233045)
  • 「Matrix4.pose」已重新命名為「Matrix4.toPose()」。姿勢屬性現已淘汰。(I329b4、b/493383490)
  • 重新命名 HandJointType 列舉值。(Ifbc83、b/482670596)
  • 將 Component.onAttach 和 onDetach 公開為公用 API，以便自訂 Component 實作。(I0ca1f)
  • 新增空間音訊元件 (I39ddd、b/489421980、b/436642086、b/436642499)
  • 從 PointSourceParams 移除實體。而是直接與 SpatialAudioTrack、SpatialSoundPool 和 SpatialMediaPlayer 搭配使用 (Ib3685、b/489421980、b/436634048)
  • 將 DeviceTrackingMode.LAST_KNOWN 重新命名為 SPATIAL_LAST_KNOWN (包含已淘汰的備用方案)、新增 INERTIAL_LAST_KNOWN 以進行 3DoF 追蹤，並將 TRACKING_DEGRADED 新增至 TrackingState。(Ie661c、b/445466590)
  • 淘汰了 GroupEntity。如要讓實體僅具備基本實體功能，請呼叫 Entity.create，系統會傳回實體介面。(I4c450、b/473867483)
  • 新增 XrLog API。將 XrLog.isEnabled 設為 true，即可在 JetpackXR 中啟用記錄功能，並使用 XrLog.Level 設定記錄層級。(I76a1f、b/463460895、b/487378441)

修正錯誤

  • Scene.keyEntity 現在預設為 mainPanelEntity。(I6a3ef)

1.0.0-alpha13 版

2026 年 3 月 25 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha13。1.0.0-alpha13 版包含這些修訂項目。

API 變更

  • 已從 Session.create 移除 unscaledGravityAlignedActivitySpace 旗標。ActivitySpace 現在一律不縮放，且與重力對齊。(If6f11、b/458173423)
  • 從 GltfModelEntity 中移除已淘汰的 setMaterialOverride 和 clearMaterialOverride 函式，現在會在個別 GltfModelNode 上呼叫這些函式。(I2e5d2)
  • 在 PanelEntity 中新增 transformPixelCoordinatesToLocalPosition 和 transformNormalizedCoordinatesToLocalPosition，並移除先前用於傳回姿勢而非 Vector3 位置的對等實驗性方法。(Ib6960、b/460123106、b/458333591)
  • 新增 GltfAnimation API，用於控制 SceneCore 中的 glTF 動畫。(I2c172、b/466065486、b/465819070、b/465818617)
  • 將 ScenePose.activitySpacePose 重新命名為 ScenePose.poseInActivitySpace (I8f175、b/427822261)
  • 新增 Scenecore 投影執行階段實作 (I9c4ab、b/476440158)
  • 調整主面板實體的大小時，可能會重新定位至 ActivitySpace 原點。除了手動或透過程式輔助將面板移回原始位置外，沒有其他解決方法。我們會在日後的版本中修正這個錯誤。(b/489427007)。
  • 在某些情況下，SurfaceEntity 和其他非面板實體類型可能不會顯示 MovableComponent 的功能。明確設定 MovableComponent.size 會導致系統顯示預設功能。我們會在日後的版本中修正這個錯誤 (b/490983469)。

1.0.0-alpha12 版

2026 年 2 月 25 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha12。1.0.0-alpha12 版包含這些修訂項目。

已知問題

  • 錨定實體可能會在幾秒後，從錨定位置貼齊至活動空間原點。
  • 建立 SurfaceEntity 執行個體時，應用程式可能會異常終止。這個問題已在 androidx.xr.scenecore:scenecore-*:1.0.0-alpha13 和後續版本中解決。受影響的應用程式應更新至最新版本。

API 變更

  • ActivitySpace.addOnSpaceUpdatedListener 和 ActivitySpace.removeOnSpaceUpdatedListener 已重新命名為 addOnOriginChangedListener 和 removeOnOriginChangedListener。AnchorEntity.setOnSpaceUpdatedListener 已重新命名為 setOnOriginChangedListener。(I5d8fb)
  • 在 FakeEntity 中新增公開名稱屬性，並在 FakePanelEntity 中公開檢視畫面。(Ifa1f9)

修正錯誤

  • 修正新版系統映像檔的像素密度計算方式 (I57d04)

1.0.0-alpha11 版本

2026 年 1 月 28 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha11。1.0.0-alpha11 版包含這些修訂項目。

API 變更

  • 將 PerceivedResolutionResult.InvalidCameraView 重新命名為 PerceivedResolutionResult.InvalidRenderViewpoint，因為 getPerceivedResolution API 現在依賴 ARCore 的 RenderViewpoint API，而非 CameraViewScenePose。這個名稱更能反映新的導入方式。(I8c967、b/446989745、b/419311998)
  • PanelEntity/SurfaceEntity.getPerceivedResolution 方法現在會採用開發人員提供的 RenderViewpoint 做為引數。先前，執行階段會任意選擇用於計算感知解析度的 RenderViewpoint。(I8c967、b/446989745、b/419311998)
  • 已移除 SpatialUser、ScenePose.Head 和 ScenePose.CameraView。ARCore for Jetpack XR 的 ArDevice 和 RenderViewpoint API 涵蓋這些 API 的功能。如要取得與使用者頭部或左/右眼對應的 ScenePose，開發人員可以使用 PerceptionSpace.getScenePoseFromPerceptionPose，並搭配透過 ARCore API 取得的適當姿勢。(I2f69c、b/446989745)

1.0.0-alpha10 版本

2025 年 12 月 3 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha10。1.0.0-alpha10 版包含這些修訂項目。

API 變更

  • 在 PanelEntity 中新增 transformPixelCoordinatesToPose 和 transformNormalizedCoordinatesToPose (I462b3)
  • 根據 SceneCore 中的邏輯，在 SceneCore 執行階段中新增輔助類別 Utils (I570b9)

修正錯誤

  • 修正了在工作階段刪除並收到 SpatialModeChangeEvent 時，可能發生的當機問題 (If44e8)
  • 修正離開或重新進入 Activity 時，可能擲回 IllegalStateException 的錯誤。(Ibff1c)

1.0.0-alpha09 版本

2025 年 11 月 19 日

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha09。1.0.0-alpha09 版包含這些修訂項目。

新功能

  • 新增 API，用於擷取代表感知空間原點姿勢和相對於感知空間原點姿勢組合的 ScenePose。(I5b50a)
  • 新增 getGravityAlignedPose 函式。與重力對齊的姿勢會忽略旋轉的俯仰和滾動。(I5ae21)
  • AnchorEntity.State 常數類型已從 Int 變更為 State 子類型。(Ib0c49)
  • 在 Entity 介面中新增 getChildren()。已更新 MainPanelEntity 生命週期。(Ia69d6)

API 變更

  • PointerCaptureComponent.PointerCaptureState 常數類型已從 Int 變更為 PointerCaptureState 子類型。(Ic888a)
  • Scene.spatialCapabilities 現在是 Set<SpatialCapability> 類型，而非 Int 欄位。SpatialCapability 常數已重新命名。(I9c109)
  • SurfaceEntity 常數類型已重新命名，並從 Int 變更為 SurfaceEntity 子類型。(I419ed)
  • SpatializerConstant 常數類型已重新命名，並從 Int 變更為 SpatializerConstant 子類型。(Ia0e18)
  • TextureSampler 常數類型已重新命名，並從 Int 變更為 TextureSampler 子類型。(I44078)
  • SpatialVisibility 常數類型已從 Int 變更為 SpatialVisibility 子類型。(I70739)
  • ResizeEvent.ResizeState 常數類型已重新命名，並從 Int 變更為 ResizeState 子類型。(I384d5)
  • InputEvent 常數類型已重新命名，並從 Ints 變更為繼承自各自的封閉類型。(I82817)
  • GltfModelEntity.AnimationState 常數類型已從 Int 變更為 AnimationState 子類型。(I24f4e)
  • AlphaMode 常數類型已重新命名，並從 Int 變更為 AlphaMode 子類型。(I27b56)
  • Space 常數類型已從 Int 變更為 Space 子類型。(I9255b)
  • 如果找不到交集，ScenePose.hitTest 和相關方法現在會傳回 null，而不是 hitPosition 為空值的 HitTestResult。HitTestResult.hitPosition 不再可為空值。(I1400a)
  • 將 ActivityPose 的參照變更為 ScenePose。(I7fe43)

1.0.0-alpha08 版本

October 22, 2025

發布 androidx.xr.scenecore:scenecore-*:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

API 變更

  • 將 ActivityPanelEntity.moveActivity 重新命名為 transferActivity (I273c5、b/430332856)

修正錯誤

  • :xr:scenecore:scenecore-spatial-rendering 和 :xr:scenecore:scenecore-spatial-core 已新增為 :xr:scenecore:scenecore 的實作依附元件 (I6ab65、b/447000520)
  • 如果在工作階段刪除後存取 session.scene，系統會擲回例外狀況。(I77e6f)

1.0.0-alpha07 版本

2025 年 9 月 24 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha07、androidx.xr.scenecore:scenecore-guava:1.0.0-alpha07 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha07。1.0.0-alpha07 版包含這些修訂版本。

API 變更

  • 將 fixedAspectRatio 重新命名為 isFixedAspectRatioEnabled，並設為布林值屬性 (I5c4e8、b/440588971)
  • Scenecore 假資料現在位於 xr:scenecore:scenecore-testing 模組中。(Idd951)
  • 將 shouldAutoHideContent 重新命名為 isAutoHideContentWhileResizingEnabled，並將 shouldAlwaysShowOverlay 重新命名為 isAlwaysShowOverlayEnabled (I97c36、b/432335421)
  • 更新 SceneCore TextureSampler 常數以提高可讀性，例如 TextureSampler.MinFilter.LINEAR 現在是 TextureSampler.MIN_FILTER_LINEAR (Ib159c)
  • Scene 的 setKeyEntity setter 已合併至 keyEntity 變數。如果將 keyEntity 設為不可移動的實體 (例如 AnchorEntity)，系統會擲回 IllegalArgumentException，而不是傳回布林值 false。(I62080、b/428721695、b/422215745)
  • 場景的 SpatialModeChangeListener 變數已替換為 setSpatialModeChangedListener。它會接收 Consumer<SpatialModeChangeEvent>，而不是 SpatialModeChangedListener。setSpatialModeChangedListener 現在可選擇採用執行工具。(I62080、b/428721695、b/422215745)
  • 從 ActivityPanelEntity.startActivity 移除 bundle 參數 (I64344、b/430332856、b/430333040)
  • SpatializerConstants.SOURCE_TYPE_BYPASS 已重新命名為 SpatializerConstants.SOURCE_TYPE_DEFAULT。(Ifc7fe、b/422215565)
  • 新增 SpatialSoundPool.PLAY_FAILED 常數。(Ifc7fe、b/422215565)
  • 在 SpatialSoundPool.play 方法中新增預設引數。(Ifc7fe、b/422215565)
  • 已移除 SpatialAudioTrackBuilder 中 setter 的傳回值。(Ifc7fe、b/422215565)
  • SurfaceEntity 變更
    • SurfaceEntity.CanvasShape已將Shape重新命名
    • SurfaceEntity.CanvasShape.Vr180Hemisphere已將Hemisphere重新命名
    • SurfaceEntity.CanvasShape.Vr360Sphere已將Sphere重新命名
    • SurfaceEntity.EdgeFeatheringParams.SmoothFeather已將RectangleFeather重新命名
    • SurfaceEntity.EdgeFeathingParams.SolidEdge已將NoFeathering重新命名
    • SurfaceEntity.ContentSecurityLevel已將SurfaceProtection重新命名
    • SurfaceEntity.ContentSecurityLevel.{values}新增了「SURFACE_PROTECTION_」前置字串。
    • SurfaceEntity.SuperSampling.{$values}新增了「SUPER_SAMPLING_」前置字串
    • SurfaceEntity.StereoMode.{values}新增了「STEREO_MODE_」前置字串
    • SurfaceEntity.ContentColorMetadata.maxCLL 已重新命名為 maxContentLightLevel (I7eb5f、b/422216050、b/427529950)
  • 將 launchActivity 重新命名為 startActivity (I7db90、b/430332856)
  • 已移除 Scene.activitySpaceRoot。請改用 Scene.activitySpace。(I05ee8、b/378706624、b/422215745)
  • configureBundleForFullSpaceModeLaunch 和 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited 分別重新命名為 createBundleForFullSpaceModeLaunch 和 createBundleForFullSpaceModeLaunchWithEnvironmentInherited，並移至 LaunchUtils.kt 檔案做為頂層方法，並將 Session 做為第一個參數 (I64a2c、b/437186050)
  • GroupEntity 工廠現在會傳回 GroupEntity 類型，而非實體。(I66042)

修正錯誤

1.0.0-alpha06 版本

2025 年 8 月 13 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha06、androidx.xr.scenecore:scenecore-guava:1.0.0-alpha06 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha06。1.0.0-alpha06 版包含這些修訂項目。

API 變更

  • 取消限制 SceneCore 的 BaseEntity 和 BaseScenePose API (88c0ff6)

1.0.0-alpha05 版本

2025 年 7 月 30 日

發布 androidx.xr.scenecore:scenecore-guava:1.0.0-alpha05、androidx.xr.scenecore:scenecore-testing:1.0.0-alpha05 和 androidx.xr.scenecore:scenecore:1.0.0-alpha05。1.0.0-alpha05 版包含這些修訂項目。

新功能

  • Perceived Resolution API 已新增至面板實體和 SurfaceEntities。(I118f6)
  • PerceivedResolution 新增至 Scene.kt 的回呼方法，用於監控 HSM 中活動主面板的感知解析度。(I58084)
  • SurfaceEntity - 新增應用程式支援，可在建立時要求超級取樣。這可讓應用程式使用超級取樣篩選器進行反鋸齒處理。(I06913)
  • 在 ActivitySpace 中新增 recommendedContentBoxInFullSpace 屬性。在全螢幕模式下，系統會傳回建議的內容放置框。(I4cd6f)
  • 為可移動修飾符提供多載建構函式，可進行錨定。(Ic0c70)

API 變更

這個版本對 SceneCore 進行了廣泛的 API 變更。多個類別已重新命名和/或移至其他模組，且大多數 getter/setter 方法已替換為 Kotlin 屬性。雖然我們預期在第一個 Beta 版發布前，API 仍會出現破壞性變更，但這些變更不會造成太大影響，數量也不會太多。

  • 重新命名及/或移動下列類別和介面：androidx.xr.scenecore.PixelDimensions 重新命名為 androidx.xr.runtime.math.IntSize2d；androidx.xr.scenecore.Dimensions 重新命名為 androidx.xr.runtime.math.FloatSize3d；androidx.xr.scenecore.ActivityPose 重新命名為 ScenePose，androidx.xr.scenecore.ContentlessEntity 重新命名為 GroupEntity，androidx.xr.scenecore.PlaneType 重新命名為 PlaneOrientation；androidx.xr.scenecore.PlaneSemantic 重新命名為 PlaneSemanticType。(Ifd405)(I3b622) (If534d)
  • Scene 屬性的多個 setter 已設為私人，不應由 SceneCore 用戶端變更：activitySpace、activitySpaceRoot、mainPanelEntity、perceptionSpace、spatialCapabilities、spatialEnvironment 和 spatialUser。(I2f506)
  • 在 Entity 中：將下列項目變更為屬性：get/setParent()、setContentDescription；已淘汰 Entity.is/setHidden()，請改用 Entity.is/setEnabled。(Ibc4c6)
  • 移除 androidx.xr.scenecore.BasePanelEntity 類別，請直接改用 PanelEntity。將 PanelEntity 的 getter 和 setter 替換為屬性。PanelEntity.size 屬性已從 Float3dSize 變更為 Float2dSize。移除已淘汰的方法 androidx.xr.scenecore.PanelEntity.getPixelDimensions，請改用 getSizeInPixels。(Icc174)
  • 以 Runnable 取代 androidx.xr.scenecore.OnSpaceUpdatedListener。(I19308)
  • 以屬性取代 SpatialUser.getCameraViews()。(Ib0cc5) 針對 ExrImage 和 GltfModel:，將 create 方法變更為暫停函式；修改建立參數，接受 Uri 或 Path，而非 String。(Id8883) (I0d247)、(I25706)
  • 將 SpatialEnvironment.requestFullSpaceMode 和 SpatialEnvironment.requestHomeSpaceMode 移至 Scene，例如使用 session.scene.requestFullSpaceMode()，而非 session.scene.spatialEnvironment.requestFullSpaceMode()。addOnPassthroughOpacityChangedListener 和 addOnSpatialEnvironmentChangedListener 現在有可接受選用執行器的覆寫。(I12fe0) (I6b21e)
  • 移除下列已淘汰的 SpatialEnvironment 方法：togglePassthrough、setPassthrough、setPassthroughOpacity、getPassthroughMode、getPassthroughOpacity、setSkybox 和 setGeometry。此外，也移除了已淘汰的類別 SpatialEnvironment.PassthroughMode (I927bd) (I927bd) (I927bd)
  • 將下列 SpatialEnvironment getter 和 setter 替換為 Kotlin 屬性：getCurrentPassthroughOpacity()、get/setPassthroughOpacityPreference()、get/setSpatialEnvironmentPreference()、isSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
  • SpatialEnvironmentPreference.preferredPassthroughOpacity類型已從Float?變更為Float。不再接受空值。而是使用 SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE 表示沒有不透明度偏好設定。(I40107)
  • 在建立方法中，將 windowBoundsPx 參數更新為 pixelDimensions，並將其類型從 Rect 變更為 IntSize2d。(I1926e)
  • SpatialEnvironment 建構函式現已改為內部函式 (I75a51)
  • 將 SpatialPointerIconNone 和 SpatialPointerIconCircle 類別替換為伴生物件 SpatialPointerIcon.NONE 和 SpatialPointerIcon.CIRCLE (I416d2)
  • SpatialPointerComponent 中的 SpatialPointerIcon 不再可為空值。請使用 SpatialPointerIcon.DEFAULT (而非空值) 表示應使用系統預設指標圖示。(I416d2)
  • 將 androidx.xr.scenecore.AnchorEntity.getState() 替換為唯讀屬性。為求明確，重新命名 AnchorEntity.create() 方法的參數。在 AnchorEntity 設定及新增事件監聽器的方法中，事件監聽器已移至最終引數，以啟用結尾 lambda。已將「AnchorEntity」的 androidx.xr.scenecore.OnStateChangedListener 替換為 Consumer<AnchorEntity.State>。(I472e0)
  • GltfModelEntity.getAnimationState() 現在是屬性。(I10b29)
  • 以屬性取代 ActivitySpace.getBounds()。ActivitySpace.addBoundsChangedListener 已重新命名為 ActivitySpace.addOnBoundsChangedListener。將 ActivitySpace.setOnSpaceUpdatedListener 替換為新增/移除方法。(I4c956)
  • AnchorPlacement: planeTypeFilter 已重新命名為 anchorablePlaneOrientations，planeSemanticFilter 已重新命名為 anchorablePlaneSemanticTypes。在 AnchorEntity 或 ActivitySpace 中新增 MovableComponent 會傳回 false，MoveListener 已重新命名為 EntityMoveListener shouldDisposeParentAnchor，disposeParentOnReAnchor systemMovable 已從 create 函式中移除，改用 creeateCustomMovable、createSystemMovable 和 createAnchorable (If11c4)
  • 已移除 SurfaceEntity.featherRadiusX/Y 並新增 EdgeFeatheringParams 類別概念。(Ic78fc)
  • PanelEntity.enablePanelDepthTest() 方法已替換為 panelClippingConfig 屬性。將 Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) 設為啟用深度測試，或將 PanelClippingConfig(isDepthTestEnabled = false) 設為停用。(I0cbe0)
  • Scene.mainPanelEntity 現在是 MainPanelEntity 類型，而非 PanelEntity (I7125a)
  • 將 Scene 的 setFullSpaceMode 方法重新命名為 configureBundleForFullSpaceModeLaunch，並將 setFullSpaceModeWithEnvironmentInherited 方法重新命名為 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited。(I0cbe0) (I0cbe0)
  • 將 SpatialVisibility 的 UNKNOWN、OUTSIDE_FOV、PARTIALLY_WITHIN_FOV 和 WITHIN_FOV 值分別重新命名為 SPATIAL_VISIBILITY_UNKNOWN、SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW、SPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW 和 SPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW (Ie7e8c)
  • SpatialVisibility 類別已替換為具有 const Int 值的公開物件。setSpatialVisibilityChangedListener 現在接受 Consumer<Int>，而非 Consumer<SpatialVisibility> (Ie7e8c)
  • PointerCaptureComponent 常數已重新命名並移至 PointerCaptureComponent.PointerCaptureState 物件 (I9c7ac)
  • 以 Consumer<Int> 取代 PointerCaptureComponents' StateListener。(I9c7ac)
  • 將 InputEventListener 替換成 Consumer<InputEvent> (I9c7ac)
  • setPreferredAspectRatio 已從 Scene 類別移至 SpatialWindow 物件，並將 Session 做為第一個參數。(I7b717)
  • Entity.setHidden() 已由 Entity.setEnabled() 取代，Entity.isHidden() 已由 Entity.isEnabled() 取代。setHidden(false) 等於 setEnabled(true) 和 isHidden() == !isEnabled()。(Icf0de)
  • Entity.contentDescription 類型已從字串變更為 CharSequence。(Ie59be)
  • 現在，如果未授予足夠權限，Session.create 和 Session.configure 會擲回 SecurityException，而不是傳回 SessionCreatePermissionsNotGranted 或 SessionConfigurePermissionsNotGranted。(I7c488)
  • ResizableComponent.create 現在需要 Consumer<ResizeEvent> ResizeEventListener，已替換為 Consumer<ResizeEvent> ResizableComponent.size，已重新命名為 ResizableComponent.affordanceSize ResizableComponent.minimumSize，已重新命名為 ResizableComponent.minimumEntitySize ResizableComponent.maximumSize，已重新命名為 ResizableComponent.maximumEntitySize，ResizableComponent.autoHideContent 已重新命名為 ResizableComponent.shouldAutoHideContent，ResizableComponent.forceShowResizeOverlay 已重新命名為 ResizableComponent.shouldAlwaysShowOverlay (I97a2d)
  • 將 androidx.xr.scenecore 和 androidx.xr.compose 的 minSDK 減少至 24。XR 套件在執行階段仍需要 API 34。(I17224)
  • 已移除所有 Jetpack XR 套件的 RequiresApi(34) 限制。由於 Jetpack XR 目前僅適用於 API 級別 34 以上的裝置，因此這項限制是多餘的。(Iae0f8)
  • 主要 SceneCore 構件 (xr:scenecore:scenecore) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:scenecore:scenecore-guava 程式庫，存取相容的 API。(If221b)
  • 使用 Kotlin 2.0 發布的專案需要 KGP 2.0.0 以上版本才能使用 (Idb6b5)
  • 這個程式庫現在使用 JSpecify 可為空值註解，屬於類型用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 以上版本的預設值) (Ia8420)
  • 所有傳回 ListenableFuture 的非同步方法都已替換為 Kotlin 暫停函式。Java 開發人員如想使用以 ListenableFuture 為基礎的非同步方法，而非 Kotlin 暫停函式，現在必須使用 :xr:scenecore-scenecore-guava 中的擴充功能函式。舉例來說，GuavaExrImage 包含與 Guava 相當的 ExrImage 非同步函式、GuavaScenePose 包含與 Guava 相當的 ScenePose 非同步函式、GuavaGltfModel 包含 Guava-equivalent GltfModel 非同步函式等。(If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

修正錯誤

  • 更新 Jetpack XR Scenecore ProGuard 規則，防止精簡用戶端發生 AbstractMethodError。(I91a01)
  • 其他修正項目，支援 Jetpack XR SceneCore 的 Proguard 壓縮 (I4f47e)
  • 修正以下錯誤：如果系統傳回的 hitPosition 為空值，InputEvent HitInfo 上的 hitPosition 可能會導致 InteractableComponent 異常終止 (I7a695)
  • Config *Mode 值已重新命名，以反映其行為。(I6d247)
  • 修正 SceneCore TestApp 中視野和 HitTest 的問題。(I2c51e)
  • 修正 SpatialCapabilities.hasCapability() 中的錯誤：如果使用位元 OR 傳入的任何功能為 true，則會傳回 true，而不是只有在所有功能都為 true 時才傳回 true。(I2cd40)
  • SurfaceEntity.StereoMode.TOP_BOTTOM已更新，頂端對應左眼，底部對應右眼。(I4ae68)

1.0.0-alpha04 版本

2025 年 5 月 7 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha04 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂項目。

新功能

  • 現在，不含嵌入活動的面板實體可使用返回處理功能。如要讓返回處理功能正常運作，您必須在 Android 資訊清單中指定 android:enableOnBackInvokedCallback= "true"。
  • StereoSurfaceEntity 現在支援透過兩個新的 StereoMode 值播放 MV-HEVC：MULTIVIEW_LEFT_PRIMARY 和 MULTIVIEW_RIGHT_PRIMARY。
  • PanelEntity.setSize 和 PanelEntity.getSize 現在會傳回父項空間的大小。
  • Entity.setPose、Entity.getPose、Entity.setScale、Entity.getScale、Entity.setAlpha 和 Entity.getAlpha 現在採用新的參數 relativeTo，可取得/設定與不同空間相關的值。支援的值為 Parent、Activity 和 Real World 空間，預設值為 Parent。
  • 在 SessionExt.kt 中新增空間可見度回呼擴充功能方法，用於監控場景內容何時移入或移出使用者的視野。
  • setPointSourceParams 已新增至 SpatialAudioTrack，可在建構音軌後更新參數。
  • 新增了 Scene 類別，並參照 Scenecore API。Scene 可做為 Session 的擴充功能屬性存取。SessionExt 內的函式已移至 Scene，因此需要調整匯入項目，例如 SessionExt.getScene(session)。addSpatialCapababilitiesChangedListener對SessionExt.addSpatialCapabilitiesChangedListener。
  • 新增 ActivityPose.hitTestAsync，可對虛擬內容啟用 hitTest。
  • 新增元件類型 SpatialPointerComponent，可讓用戶端指定指標顯示的圖示，或停用圖示。這項元件目前只能附加至 PanelEntity 個執行個體。
  • 推出新的 PanelEntity 工廠，可接受以公尺或像素為單位的面板尺寸。已移除舊版 PanelEntity 工廠，該工廠會採用兩個 Dimension 類型參數。

API 變更

  • 已移除所有 Jetpack XR 套件的 RequiresApi(34) 限制。由於 Jetpack XR 目前僅適用於 API 級別 34 以上的裝置，因此這項限制是多餘的。(Iae0f8)
  • 使用 Kotlin 2.0 發布的專案需要 KGP 2.0.0 以上版本才能使用 (Idb6b5)
  • 已移除 PermissionHelper 類別。
  • PanelEntity.getPixelDensity 已淘汰。
  • PanelEntity.setPixelDimensions 和 PanelEntity.getPixelDimension 已移除，並由 setSizeInPixels 和 getSizeInPixels 取代。
  • 已移除Entity.getActivitySpaceAlpha。可替換為 Entity.getAlpha(Space.Activity)。
  • 已移除Entity.getWorldSpaceScale。可替換為 Entity.getScale(Space.REAL\_WORLD)。
  • SceneCore 中的 Session 類別已刪除，改用 XR 執行階段中的 Session。
  • StereoSurfaceEntity 已重新命名為 SurfaceEntity。
  • Entity.setSize 和 Entity.getSize 已移除，並將相同方法新增至 PanelEntity。
  • PointSourceAttributes 已重新命名為 PointSourceParams。
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS 已重新命名為 SpatializerConstants.SOURCE\_TYPE\_DEFAULT。
  • PointSourceParams 實體已從公開存取權修改為內部存取權。
  • AnchorEntity.create 現在需要在 Session.configure() 中設定 PlaneTrackingMode。
  • SpatialUser API 現在必須在 Session.configure() 中設定 HeadTrackingMode。
  • 如果未附加 ResizableComponent，系統會提供 INFO 層級記錄，而非 ERROR 層級記錄。
  • Fov 類別現在是一般 Kotlin 類別。
  • 分割 Entity.kt，將每個具體實體類型放入專屬檔案。
  • 建立新的 PanelEntity 時，大多數檢視畫面都會重新設定父項為 FrameLayout。這樣一來，LayoutInspector 就能與空間面板搭配使用。
  • 目前使用的 XrExtensions 執行個體現已註冊至平台，並盡可能協助應用程式偵錯。

修正錯誤

  • 新增修正程式，防止移動含有 MovableComponent 和 AnchorPlacement 的 PanelEntity 時可能發生的當機問題
  • 修正 ResizableComponent 在 onResizeStart 回呼中提供過時大小的問題。
  • 修正多次呼叫 JxrPlatformAdapterAxr 的 dispose() 時發生的異常終止問題。

1.0.0-alpha03 版本

2025 年 2 月 26 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha03 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03。1.0.0-alpha03 版包含這些修訂版本。

新功能

  • Jetpack XR 程式碼現已支援 Proguard 壓縮

修正錯誤

  • 其他修正，支援 Jetpack XR SceneCore 的 Proguard 壓縮 (I4f47e)
  • 更新 Jetpack XR Scenecore ProGuard 規則，防止精簡用戶端發生 AbstractMethodError。(I91a01)

1.0.0-alpha02 版

2025 年 2 月 12 日

發布 androidx.xr.scenecore:scenecore:1.0.0-alpha02 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

即將推出的破壞性變更會影響 1.0.0-alpha02 之前建構的應用程式

  • 工廠方法已從 Session 類別移至各個類型的隨附方法：
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) 已刪除，並替換為 ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) 已刪除，並替換為 AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) 已刪除，並替換為 AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) 已刪除，並替換為 ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) 已刪除，並替換為 ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) 已刪除，並替換為 GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) 已刪除，並替換為 GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) 已刪除，並替換為 InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) 已刪除，並替換為 MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) 已刪除，並替換為 PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) 已刪除，並替換為 ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) 已刪除，並替換為 StereoSurface.create(Session, Int, Dimensions, Pose)
  • 下列已淘汰的方法已移除：
    • 已刪除 Session.canEmbedActivityPanel(Activity)。改用 getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY)。
    • 已刪除 Session.hasSpatialCapability(Int)。由於 getSpatialCapabilities() 會傳回 SpatialCapabilities 物件，因此我們已改用 getSpatialCapabilities().hasCapability()，以更細分的方式檢查空間功能是否存在。
    • Session.requestFullSpaceMode() 已刪除，並替換為 SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() 已刪除，並替換為 SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) 和 Session.setFullSpaceModeWithEnvironmentInherited(Bundle) 已移至擴充功能函式。開發人員檔案需要新增匯入項目，才能存取：
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) 已移至擴充功能函式。開發人員檔案需要新增匯入項目，才能存取：
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) 和 Session.getEntityForRtEntity(RtEntity) 已移至擴充功能函式。開發人員檔案需要新增匯入項目，才能存取：
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • 已刪除「Session.unpersistAnchor(Anchor)」
  • 已刪除「Session.createPersistedAnchorEntity(UUID)」

已知問題

  • PanelEntity.setCornerRadius() 和 ActivityPanelEntity.setCornerRadius() 可能要等到面板下次移動時才會生效，如要解決這個問題，可以將面板移至目前位置
  • 在 ActivitySpace 上呼叫 BoundsChanged 時，部分 ActivityPose 可能未正確更新。系統會在 ActivitySpace的下一次OnSpaceUpdated通話中更新

破壞性與行為變更

  • PanelEntity 和 ActivityPanelEntity 的預設圓角半徑為 32dp，如果面板的寬度或高度小於 32dp，則圓角半徑會更小

新 API 和功能

  • 推出 StereoSurface.CanvasShape，可建立 Spherical 和 Hemispherical 畫布，用於算繪沉浸式媒體。
  • StereoSurfaceEntity.create() 現在接受 CanvasShape 參數。(系統目前會忽略這個參數，但日後會使用)
  • StereoSurfaceEntity.create() 不再使用 Dimensions 參數。應用程式應透過設定 CanvasShape 來控制畫布大小
  • StereoSurfaceEntity 具有可動態設定的 CanvasShape 成員。
  • StereoSurfaceEntity.dimensions 現在是唯讀屬性；應用程式應設定 CanvasShape 來變更維度。
  • StereoSurfaceEntity 現在允許在建構後重新設定 StereoMode。

其他變更

  • 將編譯時間 minSDK 縮減到 24。所有 Jetpack XR API 在執行階段仍需要 API 34。
  • SceneCore 的工作階段工廠 (Session.create) 不會再啟動意圖來取得 SCENE_UNDERSTANDING 權限。用戶端應用程式必須先明確要求使用者授予權限，才能嘗試建立錨點。如果使用者未授予權限，就無法建立錨點。

修正錯誤

  • getActivitySpacePose() 已修正，可透過傳回縮放公尺的平移值 (而非一律傳回非縮放公尺)，來考量 ActivitySpace 比例。如果來源或目的地涉及 ActivitySpace，transformPoseTo 現在也會使用正確的單位計算座標變化。
  • 現在，只要使用 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) 傳遞空值天空盒偏好設定，天空盒就會設為全黑。如要還原為系統預設的天空盒和幾何圖形，請使用 setSpatialEnvironmentPreference(null).

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.scenecore:scenecore-* 1.0.0-alpha01。

初始版本的功能 Jetpack SceneCore 的初始開發人員版本，這是一個 3D 場景圖程式庫，用於建立及操控沉浸式場景和環境。這個程式庫可讓您放置及排列 3D 模型和內容面板，並調整其相對位置，以及與虛擬或真實世界環境的相對位置。

  • SpatialEnvironment：使用天空盒圖片和/或 3D 模型幾何圖形做為 XR 場景的背景，打造完全沉浸式的體驗。你也可以啟用穿透模式，將虛擬場景與使用者的真實環境整合。
  • PanelEntity：將標準 Android 版面配置和活動嵌入空間化面板，即可在 3D 場景中加入 2D 內容。這些面板可以懸浮或固定在真實世界的表面上。
  • GltfModelEntity：在場景中放置 3D 模型、為模型加上動畫，以及與模型互動。SceneCore 支援 glTF 檔案格式，可輕鬆與現有模型整合。
  • SpatialAudio：在 3D 場景中加入環境和點音訊來源，打造完全身歷其境的空間化音效。
  • StereoSurfaceEntity：SceneCore 支援將轉譯至 Android Surface 的內容，轉送至左/右眼。這可用於以並排或上下格式算繪立體內容，例如立體相片、3D 影片或其他動態算繪的使用者介面。應用程式應使用 MediaPlayer 或 ExoPlayer 解碼影片。
  • 元件系統：SceneCore 提供強大且靈活的元件系統，可為 XR 內容新增功能，包括讓使用者移動、調整大小，以及與模型和面板互動。
  • 錨定：啟用穿透模式後，您可以將面板和模型附加到實際表面，讓使用者在真實環境中流暢整合虛擬內容。
  • 使用者姿勢：存取使用者在虛擬場景中的位置，根據使用者位置調整內容方向。
  • SpatialCapabilities：建構完全自動調整的應用程式，在可用時充分運用空間化功能，例如 UI 內容的 3D 定位。不僅如此，應用程式還能在執行時監控功能變化，並根據使用者操作 Android XR 裝置的方式調整體驗。

已知問題

  • 目前，您必須使用 minSDK 30 才能使用 Jetpack SceneCore。如要解決這個問題，請新增下列資訊清單項目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>，以便使用 minSDK 23 建構及執行。
  • 在各種會自動重新建立 Activity 的情況下，工作階段可能會失效，包括調整主面板大小、連接周邊裝置，以及切換淺色和深色模式。如果遇到工作階段失效問題，解決方法包括將主面板設為不可調整大小、使用動態面板實體、針對特定設定變更停用活動重建功能，或停用淺色/深色模式主題變更。
  • GltfEntity 不支援可移動和可調整大小的元件。
  • GltfEntity 不支援 Entity.getSize()。
  • Jetpack XR 應用程式必須在 AndroidManifest 中要求 android.permission.SCENE_UNDERSTANDING 權限。
  • 建立工作階段的功能僅適用於 Android XR 裝置。目前，如果您建立工作階段，並嘗試在非 Android XR 裝置上使用，就會收到 RuntimeException。
  • 透過 `SpatialEnvironment.setSpatialEnvironmentPreference()` 將天空盒設為空值，不會像說明文件所述，產生純黑色的天空盒。這可能會導致系統預設天空盒，或目前的天空盒沒有變化。
  • SceneCore 用戶端應將 implementation(“com.google.guava:listenablefuture-1.0”) 新增至 Gradle 設定，用於應用程式的依附元件。在日後的版本中，scenecore 會將這個程式庫納為 api 依附元件，因此用戶端不需要明確宣告。
  • SceneCore 誤將 com.google.guava:guava-31.1-android 和 com.google.protobuf:protobuf-javalite 納入為轉換依附元件。如果這導致建構作業中出現重複的類別錯誤，可以放心排除這兩個依附元件。
  • 如果應用程式使用 SceneCore 並啟用 ProGuard，則在建立工作階段時會異常終止。如要暫時解決這個問題，請停用 ProGuard。如要進一步瞭解如何啟用 ProGuard，請參閱這份指南。