Pierwsze kroki z OpenXR na Androidzie XR

Odpowiednie urządzenia z XR
Te wskazówki pomogą Ci tworzyć treści na te typy urządzeń z XR.
Więcej informacji o typach urządzeń XR →
Gogle XR
Przewodowe okulary XR
Więcej informacji o typach urządzeń XR →

Zanim zaczniesz tworzyć aplikację za pomocą obsługiwanych rozszerzeń OpenXR lub obsługiwanego silnika, zapoznaj się z konfiguracją pliku manifestu i wymaganiami dotyczącymi uprawnień w sekcjach poniżej, aby upewnić się, że aplikacja jest skonfigurowana do programowania na XR.

Konfigurowanie pliku manifestu aplikacji

Podobnie jak w przypadku innych projektów aplikacji na Androida, aplikacja na Androida XR musi mieć plik AndroidManifest.xml z określonymi ustawieniami pliku manifestu. Plik manifestu zawiera podstawowe informacje o aplikacji dla narzędzi do kompilacji Androida, systemu operacyjnego Android i Google Play. Więcej informacji znajdziesz w przewodniku po pliku manifestu aplikacji.

W przypadku aplikacji zróżnicowanych pod kątem XR plik manifestu musi zawierać te elementy i atrybuty:

Właściwość PROPERTY_XR_ACTIVITY_START_MODE

Właściwość android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" informuje system, że aktywność powinna zostać uruchomiona w określonym trybie.

Ta właściwość ma te wartości:

  • XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (tylko OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Aplikacje utworzone za pomocą OpenXR uruchamiają się w trybie pełnej przestrzeni i muszą używać trybu uruchamiania XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. Niezarządzana pełna przestrzeń sygnalizuje Androidowi XR, że aplikacja używa OpenXR.


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

Właściwość android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" wskazuje, że aplikacja powinna zostać uruchomiona z określonym typem granicy. Jeśli aplikacja jest przeznaczona do tego, aby użytkownicy mogli poruszać się po przestrzeni fizycznej, musi określać XR_BOUNDARY_TYPE_LARGE. Jeśli określisz XR_BOUNDARY_TYPE_NO_RECOMMENDATION, nie otrzymasz rekomendacji dotyczących typu granicy bezpieczeństwa, więc system użyje typu, który jest już używany.

<manifest ... >

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

Właściwości kontenera przestrzennego

Jeśli Twoja aplikacja używa rozszerzenia XR_EXT_spatial_container (wprowadzonego w Spatial API na poziomie 4) do prezentowania treści w ograniczonych przestrzeniach 3D lub panelach 2D oprócz widoków w pełni immersyjnych, możesz zadeklarować te właściwości pliku manifestu na poziomie <activity> lub <application>, aby przekazać środowisku wykonawczemu wskazówki dotyczące uruchamiania:

  • org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: określa tryby granic używane przez aktywność, rozdzielone znakiem |.

    Prawidłowe wartości to:

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

  • org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: określa początkowy tryb granic aktywności po uruchomieniu.

    Prawidłowe wartości to:

    • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
    • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
    • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED
<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

Aplikacje OpenXR muszą zadeklarować użycie natywnej biblioteki OpenXR, aby pomyślnie załadować środowisko wykonawcze. Bez tej deklaracji nie uda się wczytać środowiska wykonawczego.

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

Funkcje PackageManager w aplikacjach XR

Gdy rozpowszechniasz aplikacje w Sklepie Google Play, możesz określić wymagane funkcje sprzętowe lub programowe w pliku manifestu aplikacji. Element uses-feature umożliwia Sklepowi Play odpowiednie filtrowanie aplikacji wyświetlanych użytkownikom.

Te funkcje są dostępne tylko w aplikacjach XR.

android.software.xr.api.openxr

Aplikacje kierowane na platformę Android XR i tworzone za pomocą OpenXR lub Unity muszą zawierać tę funkcję w manifeście aplikacji z atrybutem android:required ustawionym na true.

Aplikacje, które używają pakietu rozszerzeń Androida XR dla Unity w wersji 1.0.0 lub nowszej albo pakietu Unity OpenXR: Android XR w wersji 0.5.0-exp.1 lub nowszej, nie muszą ręcznie dodawać tego elementu do manifestu aplikacji. Te 2 pakiety wstawią ten element do manifestu aplikacji.

Urządzenia mogą określać wersję tej funkcji, która wskazuje najwyższą wersję OpenXR obsługiwaną przez urządzenie. Wyższe 16 bitów reprezentuje numer wersji głównej, a niższe 16 bitów – numer wersji podrzędnej. Na przykład aby określić OpenXR w wersji 1.1, należy ustawić wartość "0x00010001".

Aplikacje mogą używać wersji funkcji, aby wskazać minimalną wersję OpenXR, której wymagają. Jeśli na przykład aplikacja wymaga obsługi OpenXR w wersji 1.1, zadeklaruj tę funkcję:

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

android.software.xr.api.spatial

Aplikacje OpenXR, które wymagają rozszerzeń wprowadzonych w określonej wersji interfejsu Spatial API Androida XR, mogą zadeklarować funkcję android.software.xr.api.spatial z atrybutem android:version ustawionym na minimalny wymagany poziom interfejsu Spatial API (np. "1", "2", "3" lub "4"). Aby sprawdzić wersję interfejsu Spatial API wymaganą w przypadku poszczególnych rozszerzeń, zapoznaj się z sekcją Tworzenie aplikacji z obsługiwanymi rozszerzeniami 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

Ta funkcja wskazuje, że aplikacja wymaga do prawidłowego działania danych wejściowych z kontrolera ruchu o wysokiej precyzji i 6 stopniach swobody. Jeśli aplikacja obsługuje kontrolery i nie może bez nich działać, ustaw wartość true. Jeśli aplikacja obsługuje kontrolery, ale może działać bez nich, ustaw wartość 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

Ta flaga wskazuje, że aplikacja wymaga do prawidłowego działania precyzyjnego śledzenia rąk, w tym pozycji, orientacji i prędkości stawów dłoni użytkownika. Jeśli aplikacja obsługuje śledzenie rąk i nie może działać bez tej funkcji, ustaw wartość true. Jeśli aplikacja obsługuje śledzenie rąk, ale może działać bez tej funkcji, ustaw wartość 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

Ta flaga wskazuje, że aplikacja wymaga precyzyjnego śledzenia wzroku, aby dane wejściowe działały prawidłowo. Jeśli aplikacja obsługuje śledzenie wzroku jako metodę wprowadzania danych i nie może działać bez tej funkcji, ustaw wartość true. Jeśli aplikacja obsługuje śledzenie wzroku jako metodę wprowadzania danych, ale może działać bez tej funkcji, ustaw wartość 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

Ta flaga wskazuje, że aplikacja wymaga do prawidłowego działania sprzętu do śledzenia twarzy. Jeśli aplikacja obsługuje śledzenie twarzy i nie może działać bez tej funkcji, ustaw wartość na true. Jeśli aplikacja obsługuje śledzenie twarzy, ale może działać bez tej funkcji, ustaw wartość 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

Ta flaga wskazuje, że aplikacja używa dokładnej lokalizacji GPS na urządzeniu, np. podczas korzystania z rozszerzeń geoprzestrzennych OpenXR (XR_ANDROID_geospatial i XR_ANDROID_geospatial_anchor). Ustaw android:required na true, jeśli aplikacja nie może działać bez sprzętu GPS, lub na false, jeśli może działać bez niego.

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

Informacje o uprawnieniach OpenXR

Wiele rozszerzeń OpenXR uzyskuje dostęp do danych z czujników i funkcji, które są istotne z punktu widzenia prywatności. Aby korzystać z tych rozszerzeń, aplikacja musi zadeklarować wymagane elementy <uses-permission> w pliku AndroidManifest.xml i poprosić o niebezpieczne uprawnienia w czasie działania przed wywołaniem odpowiednich funkcji 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>

Tabela poniżej zawiera podsumowanie niebezpiecznych uprawnień Androida wymaganych przez obsługiwane rozszerzenia OpenXR na Androidzie XR. Szczegółowe informacje o uprawnieniach XR we wszystkich pakietach SDK znajdziesz w artykule Uprawnienia XR.

Uprawnienie

Uprawnienia

Rozszerzenia OpenXR

android.permission.EYE_TRACKING_COARSE

pozycja, stan i orientacja oczu o niskiej precyzji (np. w przypadku awatarów);

android.permission.EYE_TRACKING_FINE

Precyzyjne śledzenie wzroku na potrzeby zaznaczania, wprowadzania danych, interakcji i renderowania fowistycznego.

android.permission.FACE_TRACKING

śledzenie kształtów twarzy i renderowanie mimiki;

android.permission.RECORD_AUDIO

Wejście audio dla źródeł danych śledzenia twarzy sterowanych dźwiękiem.

android.permission.HAND_TRACKING

Śledzenie pozycji stawów dłoni, prędkości, stanu celowania i reprezentacji siatki dłoni.

android.permission.BODY_TRACKING

śledzenie pozycji stawów i proporcji szkieletu;

android.permission.SCENE_UNDERSTANDING_COARSE

śledzenie płaszczyzny, śledzenie obiektów, śledzenie obrazów/znaczników/kodów QR, kotwice, trwałość, rzutowanie promieni na obiekty możliwe do śledzenia, szacowanie oświetlenia i siatki passthrough.

android.permission.SCENE_UNDERSTANDING_FINE

Tekstury głębi, siatka sceny, szacowanie światła mapy sześciennej, rzutowanie promieni głębi i adnotacje przestrzenne.

android.permission.ACCESS_FINE_LOCATION

Dokładna lokalizacja i orientacja względem Ziemi na potrzeby śledzenia i kotwic geoprzestrzennych.

Dalsze kroki

Po skonfigurowaniu pliku manifestu aplikacji i zapoznaniu się z ważnymi informacjami możesz zacząć tworzyć aplikacje za pomocą OpenXR: