«نشست توسعه‌دهندگان Android» با یک بخش اختصاصی برای Android XR بازگشته است. با ما همراه باشید، چیزهای جدید را امتحان کنید، و بازخوردتان را برای ما ارسال کنید!

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

شروع به کار با OpenXR برای Android XR

دستگاه‌های XR واجدشرایط

این راهنمایی به شما کمک می‌کند برای این نوع دستگاه‌های واقعیت گسترده تجربه بسازید.

آشنایی با انواع دستگاه‌های XR →

هدست‌های واقعیت گسترده

عینک واقعیت گسترده سیمی

آشنایی با انواع دستگاه‌های XR →

قبل‌از شروع ساخت با افزونه‌های OpenXR پشتیبانی‌شده یا با موتور پشتیبانی‌شده، پیکربندی مانیفست و الزامات اجازه را در بخش‌های زیر مرور کنید تا مطمئن شوید برنامه‌تان برای توسعه XR پیکربندی شده است.

پیکربندی فایل مانیفست برنامه

مانند سایر پروژه‌های برنامه Android، برنامه Android XR شما باید یک فایل AndroidManifest.xml با تنظیمات مانیفست خاص داشته باشد. فایل مانیفست اطلاعات ضروری درباره برنامه‌تان را برای ابزارهای ساخت Android، سیستم‌عامل Android، و Google Play شرح می‌دهد. برای اطلاعات بیشتر، به راهنمای نمای کلی مانیفست برنامه مراجعه کنید.

برای برنامه‌های متمایز 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 استفاده می‌کند.


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

<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 به «فروشگاه Play» اجازه می‌دهد برنامه‌های نشان‌داده‌شده به کاربران را به‌طور مناسب فیلتر کند.

ویژگی‌های زیر مختص برنامه‌های متمایز XR است.

android.software.xr.api.openxr

برنامه‌هایی که پلاتفرم Android XR را هدف قرار می‌دهند و با OpenXR یا Unity ساخته شده‌اند باید این ویژگی را در مانیفست برنامه با مشخصه android:required تنظیم‌شده روی true اضافه کنند.

برنامه‌هایی که از بسته افزونه‌های Android XR برای Unity نسخه ۱.۰.۰ یا بالاتر یا Unity OpenXR: بسته Android XR نسخه ۰.۵.۰-exp.۱ یا بالاتر استفاده می‌کنند، لازم نیست این عنصر را به‌صورت دستی به مانیفست برنامه اضافه کنند. این دو بسته این عنصر را در مانیفست برنامه برای شما تزریق خواهند کرد.

دستگاه‌ها ممکن است نسخه‌ای را برای این ویژگی مشخص کنند که نشان‌دهنده بالاترین نسخه OpenXR پشتیبانی‌شده توسط دستگاه است. ۱۶ بیت بالاتر نشان‌دهنده عدد اصلی و ۱۶ بیت پایین‌تر نشان‌دهنده عدد فرعی است. برای مثال، برای مشخص کردن OpenXR نسخه ۱.۱، مقدار روی "0x00010001" تنظیم می‌شود.

برنامه‌ها می‌توانند از نسخه ویژگی برای نشان دادن حداقل نسخه OpenXR که برنامه نیاز دارد استفاده کنند. برای مثال، اگر برنامه‌تان به پشتیبانی از OpenXR نسخه ۱.۱ نیاز دارد، ویژگی زیر را اعلام کنید:

<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

این ویژگی نشان می‌دهد که برنامه برای عملکرد صحیح به ورودی از کنترل‌کننده حرکتی 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

این پرچم نشان می‌دهد که برنامه برای عملکرد صحیح به سخت‌افزار ردگیری چهره نیاز دارد. اگر برنامه‌تان از ردگیری چهره پشتیبانی می‌کند و بدون آن نمی‌تواند کار کند، مقدار را روی 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 تنظیم کنید، یا اگر می‌تواند بدون آن کار کند، روی false تنظیم کنید.

<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 نیاز دارند خلاصه می‌کند. برای جزئیات کامل درباره اجازه‌های واقعیت گسترده در همه کیت‌های توسعه نرم‌افزار، به آشنایی با اجازه‌های واقعیت گسترده مراجعه کنید.

اجازه	قابلیت‌ها	افزونه‌های 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 بسازید کاوش کنید: