Начало работы с OpenXR для Android XR

Поддерживаемые XR-устройства

Это руководство поможет вам создавать продукты для таких XR-устройств.

Подробнее о типах устройств XR…

XR-шлемы

Проводные XR-очки

Подробнее о типах устройств XR…

Прежде чем начать разработку с использованием поддерживаемых расширений OpenXR или поддерживаемого движка, ознакомьтесь с требованиями к конфигурации манифеста и разрешениям в следующих разделах, чтобы убедиться, что ваше приложение настроено для разработки XR.

Как настроить файл манифеста приложения

Как и в других проектах приложений для Android, в вашем приложении для Android XR должен быть файл AndroidManifest.xml с определенными настройками манифеста. Файл манифеста содержит важную информацию о приложении для инструментов сборки Android, операционной системы Android и Google Play. Подробную информацию можно найти в руководстве по манифесту приложения.

Примечание. Хотя приложения, созданные с помощью Unity, Unreal Engine или Godot для Android XR, основаны на OpenXR, вам не нужно вручную добавлять большинство этих элементов или атрибутов манифеста, если вы используете официальные плагины Android XR для этих движков. Плагины движка и наборы настроек экспорта настраивают манифест для приложения на основе параметров проекта и сборки.

Для приложений с поддержкой XR файл манифеста должен содержать следующие элементы и атрибуты:

Свойство PROPERTY_XR_ACTIVITY_START_MODE

Свойство android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" сообщает системе, что действие должно быть запущено в определенном режиме.

У этого свойства есть следующие значения:

• 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.

Примечание. Если вы используете один из пакетов Android XR для Unity, ваше приложение также будет запускаться в полном пространстве. Однако вам не нужно добавлять его в манифест вручную. Пакеты Unity создают манифест для приложения на основе настроек проекта и сборки.

<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), чтобы показывать контент в ограниченных трехмерных областях или на двумерных панелях в дополнение к полноэкранному режиму с эффектом присутствия, вы можете объявить следующие свойства манифеста на уровне <activity> или <application>, чтобы предоставить подсказки для запуска в среде выполнения:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES – указывает режимы границ, используемые действием, разделенные символом |.

  Допустимые значения:

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

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE – указывает начальный режим границ действия при запуске.

  Допустимые значения:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Примечание. Эти свойства заменяют категорию фильтра намерений <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> при использовании XR_EXT_spatial_container.

<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>

Функции PackageManager для XR-приложений

При распространении приложений через Google Play вы можете указать в манифесте приложения требования к аппаратному или программному обеспечению. Элемент uses-feature позволяет Google Play фильтровать приложения, которые показываются пользователям.

Следующие функции доступны только для приложений, оптимизированных для XR.

android.software.xr.api.openxr

Приложения, предназначенные для платформы Android XR и созданные с помощью OpenXR или Unity, должны включать эту функцию в манифест приложения с атрибутом android:required, для которого задано значение true.

Если в приложении используется пакет расширений Android XR для Unity версии 1.0.0 или выше либо пакет Unity OpenXR: Android XR версии 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, которым требуются расширения, представленные в определенной версии Spatial API Android XR, могут объявить функцию android.software.xr.api.spatial, указав в android:version минимальный требуемый уровень Spatial API (например, "1", "2", "3" или "4"). Чтобы узнать, какая версия Spatial API требуется для каждого расширения, прочитайте статью Как создавать приложения с поддерживаемыми расширениями OpenXR.

<!-- 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

Эта функция указывает, что для правильной работы приложения требуется ввод данных от высокоточного контроллера движения с шестью степенями свободы. Если приложение поддерживает контроллеры и не может работать без них, установите значение true. Если приложение поддерживает контроллеры, но может работать и без них, выберите false.

Примечание. Контроллеры движения с шестью степенями свободы – это пара аппаратных контроллеров, по одному для каждой руки. Каждый контроллер отслеживается в пространстве независимо по шести степеням свободы – как линейные, так и вращательные движения. Обычно на таких контроллерах есть несколько аппаратных кнопок, включая триггер, а также виброотклик.

<!-- 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). Установите для android:required значение true, если ваше приложение не может работать без GPS, или false, если может.

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

Примечание. Отслеживание рук, отслеживание взгляда, отслеживание лица, отслеживание тела, распознавание сцены и определение местоположения – это функции, связанные с конфиденциальностью. Чтобы использовать их, приложения должны запрашивать динамические разрешения. Подробнее о том, как объявлять и запрашивать разрешения, рассказывается в статье Разрешения для XR.

Разрешения для OpenXR

Многие расширения OpenXR получают доступ к конфиденциальным данным датчиков и функциям. Чтобы использовать эти расширения, ваше приложение должно объявить необходимые элементы <uses-permission> в файле AndroidManifest.xml и запросить опасные разрешения во время выполнения, прежде чем вызывать соответствующие функции 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, которые требуются поддерживаемым расширениям OpenXR в Android XR. Подробную информацию о разрешениях XR для всех SDK можно найти в статье Разрешения для 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	Отслеживание плоскостей, объектов, изображений, маркеров и QR-кодов, привязки, сохранение, рейкастинг отслеживаемых объектов, оценка освещенности и сквозные сетки.	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
• Создание кампаний в поддерживаемых поисковых системах