开始使用 Android XR 的 OpenXR

适用的 XR 设备

本指南可帮助您为以下类型的 XR 设备打造优质体验。

了解 XR 设备类型 →

扩展现实头戴设备

有线扩展现实眼镜

了解 XR 设备类型 →

在开始使用受支持的 OpenXR 扩展程序或受支持的引擎进行构建之前，请查看以下部分中的清单配置和权限要求，确保您的应用已针对 XR 开发进行配置。

配置应用的清单文件

与其他 Android 应用项目一样，您的 Android XR 应用必须具有包含特定清单设置的 AndroidManifest.xml 文件。该清单文件会向 Android 构建工具、Android 操作系统和 Google Play 描述有关应用的基本信息。如需了解详情，请参阅应用清单概览指南。

注意： 虽然使用 Unity、Unreal Engine 或 Godot 为 Android XR 构建的应用基于 OpenXR，但如果您使用这些引擎的官方 Android XR 插件，则无需手动添加大多数清单元素或属性。引擎插件和导出预设会根据您的项目和 build 设置为您的应用配置清单。

对于 XR 差异化应用，清单文件必须包含以下元素和属性：

PROPERTY_XR_ACTIVITY_START_MODE 属性

android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" 属性可让系统知道，在启动 activity 时，应以特定模式启动该 activity。

此属性具有以下值：

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED（仅限 OpenXR）

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

使用 OpenXR 构建的应用会在全沉浸空间中启动，并且必须使用 XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED 启动模式。非代管式全沉浸空间会向 Android XR 发出信号，表明应用使用的是 OpenXR。

注意： 如果您使用某个适用于 Unity 的 Android XR 软件包，您的应用也会在全沉浸空间中启动。不过，您无需手动将其添加到清单中。Unity 软件包会根据您的项目和 build 设置为您的应用创建清单。

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
           android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED" />
       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
               <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
           </intent-filter>
       </activity>
   </application>
</manifest>

PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED 属性

android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" 属性表示应用应以特定类型的边界启动。如果您的应用旨在让用户在物理空间中移动，则需要指定 XR_BOUNDARY_TYPE_LARGE。指定 XR_BOUNDARY_TYPE_NO_RECOMMENDATION 不会提供有关安全边界类型的建议，因此系统会使用已在使用的类型。

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED"
           android:value="XR_BOUNDARY_TYPE_LARGE" />
   </application>
</manifest>

空间容器属性

如果您的应用使用 XR_EXT_spatial_container 扩展程序（在 Spatial API 级别 4 中引入）在有界 3D 体积或 2D 面板中呈现内容，以及全沉浸式视图，您可以在 <activity> 或 <application> 级别声明以下清单属性，以便向运行时提供启动提示：

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES：指定 activity 使用的边界模式，以 | 分隔。

  有效值包括：

  • "2d_panel"
  • "bounded"
  • "immersive"

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE：指定 activity 启动时的初始边界模式。

  有效值包括：

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

注意： 使用 XR_EXT_spatial_container 时，这些属性会替换 <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> intent 过滤器类别。

<manifest ... >

   <application ... >
       <activity
           android:name="com.example.myapp.MainActivity" ... >
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
               android:value="bounded|immersive" />
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
               android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED" />
       </activity>
   </application>
</manifest>

<uses-native-library> OpenXR

OpenXR 应用必须声明使用原生 OpenXR 库，才能成功加载其运行时。如果没有此声明，运行时将无法加载。

<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="false" />

       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
        </activity>
    </application>
</manifest>

适用于 XR 应用的 PackageManager 功能

通过 Google Play 商店分发应用时，您可以在应用清单中指定所需的硬件或软件功能。借助 uses-feature 元素，Play 商店可以适当过滤向用户显示的应用。

以下功能仅适用于 XR 差异化应用。

android.software.xr.api.openxr

以 Android XR 平台为目标平台且使用 OpenXR 或 Unity 构建的应用必须在应用清单中包含此功能，并将 android:required 属性设置为 true。

如果应用使用 Android XR Extensions Package for Unity 1.0.0 或更高版本，或者使用 Unity OpenXR: Android XR Package 0.5.0-exp.1 或更高版本，则无需手动将此元素添加到应用清单中。这两个软件包会为您将此元素注入应用清单。

设备可以为此功能指定一个版本，该版本表示设备支持的最高 OpenXR 版本。高 16 位表示主版本号，低 16 位表示次版本号。例如，如要指定 OpenXR 1.1 版，则应将值设置为 "0x00010001"。

应用可以使用功能版本来指明应用所需的最低 OpenXR 版本。例如，如果您的应用需要 OpenXR 1.1 版支持，请声明以下功能：

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    android:required="true" />

android.software.xr.api.spatial

如果 OpenXR 应用需要特定 Android XR Spatial API 版本中引入的扩展，可以声明 android.software.xr.api.spatial 功能，并将 android:version 设置为所需的最低 Spatial API 级别（例如 "1"、"2"、"3" 或 "4"）。请参阅使用受支持的 OpenXR 扩展进行构建，查看每个扩展所需的 Spatial API 版本。

<!-- Indicates that the app requires Android XR Spatial API Level 4 or higher. -->
<uses-feature android:name="android.software.xr.api.spatial"
    android:version="4"
    android:required="true" />

android.hardware.xr.input.controller

此功能表示应用需要来自高精度 6DoF（自由度）运动控制器的输入才能正常运行。如果您的应用支持控制器，并且没有控制器就无法运行，请将该值设置为 true。如果您的应用支持控制器，但也可以在没有控制器的情况下运行，请将其设置为 false。

注意 ：6DoF 运动控制器是一对硬件控制器，每只手各一个。每个控制器在空间中都是独立跟踪的，具有六个自由度，包括线性和旋转运动。这些控制器通常有多个硬件按钮，包括触发器和触感反馈。

<!-- Sets android:required to true, indicating that your app can't function on devices without controllers. -->
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

此标志表示应用需要高保真手部追踪才能正常运行，包括用户手部关节的位置、方向和速度。如果您的应用支持手部追踪，并且没有该功能便无法正常运行，请将值设置为 true。如果您的应用支持手部追踪，但没有该功能也能运行，请将其设置为 false。

注意： 检测捏、戳、瞄准和抓握等基本手势时，不需要此标志。

<!-- Sets android:required to true, indicating that your app can't function on devices without hand tracking. -->
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

此标志表示应用需要高保真眼动追踪功能才能正常运行输入。如果您的应用支持眼动追踪输入，并且没有该功能就无法运行，请将值设置为 true。如果您的应用支持眼动追踪输入，但没有眼动追踪也能运行，请将其设置为 false。

<!-- Sets android:required to true, indicating that your app can't function on devices without eye tracking. -->
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

android.hardware.xr.input.face_tracking

此标志表示应用需要面部追踪硬件才能正常运行。如果您的应用支持面部追踪，并且没有该功能便无法正常运行，请将值设置为 true。如果您的应用支持面部追踪，但没有该功能也能运行，请将其设置为 false。

<!-- Sets android:required to true, indicating that your app can't function on devices without face tracking. -->
<uses-feature android:name="android.hardware.xr.input.face_tracking" android:required="true" />

android.hardware.location.gps

此标志表示应用会使用设备上的精确 GPS 位置信息，例如使用地理空间 OpenXR 扩展程序（XR_ANDROID_geospatial 和 XR_ANDROID_geospatial_anchor）时。如果您的应用在没有 GPS 硬件的情况下无法运行，请将 android:required 设置为 true；如果应用在没有 GPS 硬件的情况下也能运行，请将其设置为 false。

<uses-feature android:name="android.hardware.location.gps" android:required="false" />

注意： 手部追踪、眼动追踪、面部追踪、身体追踪、场景理解和位置信息属于隐私敏感功能，需要应用请求运行时权限。如需详细了解如何声明和请求权限，请参阅了解 XR 权限。

了解 OpenXR 的权限

许多 OpenXR 扩展程序都会访问涉及隐私的传感器数据和功能。如需使用这些扩展程序，您的应用必须在其 AndroidManifest.xml 文件中声明所需的 <uses-permission> 元素，并在调用相应的 OpenXR 函数之前在运行时请求危险权限。

<manifest ... >
    <!-- Example dangerous permissions required by specific OpenXR extensions -->
    <uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />
    <uses-permission android:name="android.permission.HAND_TRACKING" />
    ...
</manifest>

下表总结了 Android XR 上受支持的 OpenXR 扩展程序所需的危险 Android 权限。如需详细了解所有 SDK 的 XR 权限，请参阅了解 XR 权限。

权限	功能	OpenXR 扩展程序
android.permission.EYE_TRACKING_COARSE	低精度眼部姿势、状态和方向（例如用于头像）。	XR_ANDROID_eye_tracking （xrGetCoarseTrackingEyesInfoANDROID）
android.permission.EYE_TRACKING_FINE	高精度眼动追踪，可用于选择、输入、互动和眼动追踪注视点渲染。	XR_ANDROID_eye_tracking （xrGetFineTrackingEyesInfoANDROID） XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	跟踪面部混合形状并渲染面部表情。	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	音频驱动的面部追踪数据源的音频输入。	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	追踪手部关节姿势、速度、瞄准状态和手部网格表示。	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	追踪身体关节姿势和骨骼比例。	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	平面跟踪、对象跟踪、图像/标记/二维码跟踪、锚点、持久性、针对可跟踪对象的光线投射、光线估计和透视网格。	XR_ANDROID_anchor_sharing_export XR_ANDROID_composition_layer_passthrough_mesh XR_ANDROID_device_anchor_persistence XR_ANDROID_light_estimation XR_ANDROID_raycast XR_ANDROID_spatial_anchor_space XR_ANDROID_spatial_component_subsumed_by XR_ANDROID_spatial_discovery_bounds XR_ANDROID_spatial_entity_bound_anchor XR_ANDROID_spatial_object_tracking XR_ANDROID_trackables XR_ANDROID_trackables_image XR_ANDROID_trackables_marker XR_ANDROID_trackables_object XR_ANDROID_trackables_qr_code XR_EXT_spatial_anchor XR_EXT_spatial_image_tracking XR_EXT_spatial_marker_tracking XR_EXT_spatial_mesh_tracking XR_EXT_spatial_object_tracking XR_EXT_spatial_persistence XR_EXT_spatial_persistence_operations XR_EXT_spatial_plane_tracking
android.permission.SCENE_UNDERSTANDING_FINE	深度纹理、场景网格、立方体贴图光线估测、深度光线投射和空间注释。	XR_ANDROID_depth_texture XR_ANDROID_light_estimation_cubemap XR_ANDROID_scene_meshing XR_ANDROID_spatial_annotation_tracking XR_ANDROID_spatial_discovery_raycast
android.permission.ACCESS_FINE_LOCATION	用于地理空间跟踪和锚点的精确地球相对位置和方向。	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

后续步骤

现在，您已完成应用清单的配置并查看了重要信息，接下来可以探索使用 OpenXR 进行构建的方法：

• 使用受支持的 OpenXR 扩展进行构建
• 使用受支持的引擎进行构建