เริ่มต้นใช้งาน OpenXR สำหรับ Android XR

อุปกรณ์ XR ที่รองรับ

คำแนะนำนี้จะช่วยคุณสร้างประสบการณ์การใช้งานสำหรับอุปกรณ์ XR ประเภทนี้

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ก่อนเริ่มสร้างด้วยส่วนขยาย OpenXR ที่รองรับหรือด้วยเครื่องมือที่รองรับ โปรดตรวจสอบการกำหนดค่าไฟล์ Manifest และข้อกำหนดด้านสิทธิ์ในส่วนต่อไปนี้เพื่อให้แน่ใจว่าแอปได้รับการกำหนดค่าสำหรับการพัฒนา XR

กำหนดค่าไฟล์ Manifest ของแอป

เช่นเดียวกับโปรเจ็กต์แอป Android อื่นๆ แอป Android XR ต้องมีไฟล์ AndroidManifest.xml ที่มีการตั้งค่าไฟล์ Manifest ที่เฉพาะเจาะจง ไฟล์ Manifest อธิบายข้อมูลสำคัญเกี่ยวกับแอปของคุณให้เครื่องมือสร้าง Android, ระบบปฏิบัติการ Android และ Google Play ทราบ ดูข้อมูลเพิ่มเติมได้ที่คู่มือภาพรวมไฟล์ Manifest ของแอป

สำหรับแอปที่แตกต่างกันสำหรับ XR ไฟล์ Manifest ต้องมีองค์ประกอบและแอตทริบิวต์ต่อไปนี้

พร็อพเพอร์ตี้ 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 จะเปิดใน Full Space และต้องใช้โหมดเริ่มต้น XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED Unmanaged Full Space จะส่งสัญญาณไปยัง Android XR ว่าแอปใช้ 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>

พร็อพเพอร์ตี้ 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) เพื่อนำเสนอเนื้อหาในปริมาตร 3 มิติที่มีขอบเขตหรือแผง 2 มิตินอกเหนือจากมุมมองที่สมจริงเต็มรูปแบบ คุณสามารถประกาศพร็อพเพอร์ตี้ไฟล์ Manifest ต่อไปนี้ที่ระดับ <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

<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 Store คุณสามารถระบุฟีเจอร์ฮาร์ดแวร์หรือซอฟต์แวร์ที่จำเป็นในไฟล์ Manifest ของแอปได้ องค์ประกอบ uses-feature ช่วยให้ Play Store กรองแอปที่แสดงต่อผู้ใช้ได้อย่างเหมาะสม

ฟีเจอร์ต่อไปนี้มีไว้สำหรับแอปที่สร้างความแตกต่างด้วย XR โดยเฉพาะ

android.software.xr.api.openxr

แอปที่กำหนดเป้าหมายเป็นแพลตฟอร์ม Android XR และสร้างด้วย OpenXR หรือ Unity ต้องรวมฟีเจอร์นี้ไว้ในไฟล์ Manifest ของแอปโดยตั้งค่าแอตทริบิวต์ android:required เป็น true

แอปที่ใช้แพ็กเกจส่วนขยาย Android XR สำหรับ Unity เวอร์ชัน 1.0.0 ขึ้นไปหรือแพ็กเกจ Unity OpenXR: Android XR เวอร์ชัน 0.5.0-exp.1 ขึ้นไปไม่จำเป็นต้องเพิ่มองค์ประกอบนี้ลงในไฟล์ Manifest ของแอปด้วยตนเอง ทั้ง 2 แพ็กเกจนี้จะแทรกองค์ประกอบนี้ลงในไฟล์ Manifest ของแอปให้คุณ

อุปกรณ์อาจระบุเวอร์ชันสำหรับฟีเจอร์นี้ ซึ่งจะระบุเวอร์ชันสูงสุดของ 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") ดูสร้างด้วยส่วนขยาย 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

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

Flag นี้ระบุว่าแอปต้องใช้ฮาร์ดแวร์การติดตามใบหน้าจึงจะทำงานได้อย่างถูกต้อง หากแอปรองรับการติดตามใบหน้าและทำงานไม่ได้หากไม่มีฟีเจอร์นี้ ให้ตั้งค่าเป็น 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 หากแอปทำงานได้โดยไม่ต้องใช้ฮาร์ดแวร์ GPS

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

ทำความเข้าใจสิทธิ์สำหรับ 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

ขั้นตอนถัดไป

เมื่อกำหนดค่าไฟล์ Manifest ของแอปและตรวจสอบข้อมูลสำคัญเสร็จแล้ว ให้สำรวจวิธีต่างๆ ที่คุณสามารถสร้างด้วย OpenXR ดังนี้

• สร้างด้วยส่วนขยาย OpenXR ที่รองรับ
• สร้างด้วยเครื่องมือที่รองรับ