स्पेशल कंटेनर की मदद से ऐप्लिकेशन बनाना

इस्तेमाल किए जा सकने वाले XR डिवाइस

इन दिशा-निर्देशों से आपको इस तरह के एक्सआर डिवाइसों के लिए अनुभव तैयार करने में मदद मिलती है.

एक्सआर डिवाइस के टाइप के बारे में जानें →

एक्सआर डिवाइस के टाइप के बारे में जानें →

स्पेशल कंटेनर, OpenXR में वॉल्यूमेट्रिक विंडोइंग की सुविधा उपलब्ध कराते हैं. OpenXR 1.1 में XR_EXT_spatial_container और XR_EXT_spatial_container_self_rendering एक्सटेंशन के ज़रिए तय किया गया स्पेशल कंटेनर, उपयोगकर्ता के स्पेस में सिस्टम से मैनेज किया जाने वाला 3D वॉल्यूमेट्रिक रीजन होता है. इसमें आपका ऐप्लिकेशन, स्टैंडर्ड OpenXR कंपोज़िशन लेयर का इस्तेमाल करके 3D कॉन्टेंट रेंडर करता है.

आम तौर पर, OpenXR सेशन में उपयोगकर्ता के पूरे फ़ील्ड ऑफ़ व्यू (कैमरे से दिख रहा व्यू) का खास ऐक्सेस होता है. स्पेशल कंटेनर की मदद से, आपका ऐप्लिकेशन उपयोगकर्ता के आस-पास के माहौल में, 3D OpenXR कॉन्टेंट को एक सीमित 3D बॉक्स में रेंडर कर सकता है. इसके अलावा, यह किसी भी समय, फ़ुल-स्क्रीन पर इमर्सिव अनुभव में बदल सकता है.

स्पेशल कंटेनर के बारे में जानकारी

स्पेशल कंटेनर, 3D स्पेस होता है. यह बाउंडेड या अनबाउंडेड हो सकता है. इसे Android XR सिस्टम मैनेज करता है और आपका OpenXR ऐप्लिकेशन रेंडर करता है:

• बाउंडेड मोड: आपका ऐप्लिकेशन, 3D डाइमेंशन (चौड़ाई, ऊंचाई, और गहराई मीटर में) का सुझाव देता है. इसके बाद, सिस्टम उपयोगकर्ता के आस-पास के माहौल में 3D बाउंडिंग बॉक्स दिखाता है. आपका ऐप्लिकेशन, वॉल्यूम में स्टीरियो 3D कॉन्टेंट रेंडर करता है. साथ ही, सिस्टम रेंडर किए गए कॉन्टेंट को 3D बॉक्स की सीमाओं के हिसाब से क्लिप करता है.
• इमर्सिव मोड: स्पेशल कंटेनर, अनंत सीमाओं तक फैल जाता है. इससे आपके ऐप्लिकेशन को उपयोगकर्ता का पूरा फ़ील्ड ऑफ़ व्यू मिलता है. यह एक पारंपरिक फ़ुल-स्क्रीन OpenXR सेशन की तरह होता है.

स्पेशल कंटेनर के साथ उपयोगकर्ता कैसे इंटरैक्ट करते हैं

Android XR सिस्टम, स्पेशल कंटेनर की विंडो के कंट्रोल और फ़िज़िकल स्पेस में प्लेसमेंट को मैनेज करता है. इससे सभी ऐप्लिकेशन में एक जैसा इंटरैक्शन मॉडल मिलता है:

• मूव करना और जगह बदलना: उपयोगकर्ता, हाथ के जेस्चर (जैसे, पिंच करना) या मोशन कंट्रोलर का इस्तेमाल करके, स्पेशल कंटेनर के सिस्टम हैंडल को पकड़ सकते हैं. इससे वे 3D स्पेस में उसकी जगह बदल सकते हैं.
• छोटा करना और बंद करना: सिस्टम विंडो कंट्रोल की मदद से, उपयोगकर्ता अलग-अलग स्पेशल कंटेनर को छोटा या बंद कर सकते हैं. जब कोई उपयोगकर्ता किसी कंटेनर को बंद करता है, तो सिस्टम आपके ऐप्लिकेशन को इसकी सूचना देता है, ताकि वह संसाधनों को हटा सके.
• सीन को समझने की सुविधा की मदद से, फ़्लोर पर लॉक करना: जब आपका ऐप्लिकेशन android.permission.SCENE_UNDERSTANDING_COARSE अनुमति का एलान करता है और इसके लिए अनुरोध करता है, तो सिस्टम अपने-आप सरफ़ेस स्नैपिंग की सुविधा चालू कर देता है. इससे उपयोगकर्ता, ऐप्लिकेशन के अतिरिक्त कॉन्फ़िगरेशन के बिना, किसी स्पेशल कंटेनर को फ़िज़िकल फ़्लोर पर रख सकते हैं और लॉक कर सकते हैं. जैसा कि इमेज 1 में नारंगी रंग के टेरेन कंटेनर में दिखाया गया है.
• सीधे तौर पर 3D इंटरैक्शन: जब कोई कंटेनर फ़ोकस में होता है और इंटरैक्टिव होता है, तो उपयोगकर्ता हाथ ट्रैक करने की सुविधा, आई गेज़ या 6DoF कंट्रोलर का इस्तेमाल करके, वॉल्यूम में मौजूद 3D कॉन्टेंट के साथ सीधे तौर पर इंटरैक्ट कर सकते हैं.

• बाउंडेड और इमर्सिव मोड के बीच ट्रांज़िशन करना: उपयोगकर्ता या आपका ऐप्लिकेशन, OpenXR सेशन को रीस्टार्ट किए बिना, कंटेनर को बाउंडेड 3D बॉक्स और अनबाउंडेड फ़ुल-स्क्रीन इमर्सिव व्यू के बीच स्विच कर सकता है.

• चलते-फिरते फ़ॉलो मोड: सिस्टम, हर स्पेशल कंटेनर के कोऑर्डिनेट स्पेस (xrCreateSpatialContainerSpaceEXT) के पोज़ को कंट्रोल करता है. इसलिए, उपयोगकर्ता सिस्टम विंडो कंट्रोल से फ़ॉलो मोड चालू कर सकते हैं. इससे, बाउंड किया गया 3D कंटेनर अपने-आप उन्हें फ़ॉलो करता है और उनके फ़ील्ड ऑफ़ व्यू में रहता है. इसके लिए, आपके ऐप्लिकेशन में किसी अतिरिक्त कॉन्फ़िगरेशन की ज़रूरत नहीं होती.

Android XR पर स्पेशल कंटेनर इस्तेमाल करने का तरीका

स्पेशल कंटेनर की मदद से ऐप्लिकेशन बनाते समय, अपने सीन को कंटेनर की सीमाओं, स्टेटस में होने वाले बदलावों, और बैकग्राउंड ब्लेंड मोड के हिसाब से डिज़ाइन करें.

अपने 3D कॉन्टेंट को कंटेनर की सीमाओं के मुताबिक बनाना

बाउंडेड मोड में, स्पेशल कंटेनर स्पेस (xrCreateSpatialContainerSpaceEXT) का ऑरिजिन (0, 0, 0), 3D बाउंडिंग बॉक्स के बीच में होता है. सिस्टम, उपयोगकर्ता के आस-पास के माहौल में कंटेनर स्पेस की पोज़ को मैनेज करता है. इसलिए, आपका ऐप्लिकेशन (0, 0, 0) के हिसाब से 3D कॉन्टेंट रेंडर करता है. इस दौरान, सिस्टम उपयोगकर्ता की पोज़िशन बदलने और फ़ॉलो मोड को हैंडल करता है. सिस्टम, बॉक्स की चौड़ाई, ऊंचाई या गहराई से बाहर रेंडर की गई किसी भी ज्यामिति को क्लिप कर देता है, ताकि कॉन्टेंट अपने असाइन किए गए वॉल्यूम के अंदर रहे.

आपके ऐप्लिकेशन को रनटाइम से बाउंड बदलने वाले इवेंट को सुनना चाहिए और आपके 3D सीन को स्केल या फिर से पोज़िशन करना चाहिए, ताकि मुख्य कॉन्टेंट कंटेनर के मौजूदा डाइमेंशन में फ़िट हो सके. जब कंटेनर इमर्सिव मोड में ट्रांज़िशन करता है, तो बाउंड अनंत हो जाते हैं. साथ ही, सीन को उसके पूरे 1:1 वर्ल्ड स्केल में वापस लाया जा सकता है.

कंटेनर की स्थिति में हुए बदलावों का जवाब देना

सिर्फ़ ऐप्लिकेशन लेवल पर विज़िबिलिटी और फ़ोकस को मैनेज करने के बजाय, हर स्पेशल कंटेनर अपनी स्थिति की जानकारी देता है, ताकि आपका ऐप्लिकेशन उसके हिसाब से काम कर सके:

• किसको दिखे: इससे पता चलता है कि कंटेनर फ़िलहाल दिख रहा है या छिपा हुआ है. कंटेनर के छिपे होने पर, ऐनिमेशन, ऑडियो या सिम्युलेशन अपडेट रोकें. आपका ऐप्लिकेशन, कंटेनर को दिखाने या छिपाने का अनुरोध भी कर सकता है.
• इंटरैक्ट करने की सुविधा: इससे पता चलता है कि कंटेनर पर फ़ोकस किया गया है या नहीं. साथ ही, यह भी पता चलता है कि हाथ ट्रैक करने की सुविधा, कंट्रोलर या आंखों की गतिविधि से उपयोगकर्ता का इनपुट मिल रहा है या नहीं. फ़ोकस बदलने पर, इंटरैक्टिव हाइलाइट और इनपुट हैंडलिंग की सुविधा को चालू या बंद करें.
• बाउंड मोड: इससे पता चलता है कि कंटेनर फ़िलहाल XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT (3D बॉक्स में क्लिप किया गया है) या XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT (अनबाउंडेड फ़ुल-स्क्रीन) में है. मोड बदलने पर, अपने सीन का स्केल अपडेट करें और एनवायरमेंट विज़ुअल (जैसे, स्काईबॉक्स या पासथ्रू) को टॉगल करें. आपका ऐप्लिकेशन, बाउंडेड और इमर्सिव मोड के बीच स्विच करने का अनुरोध भी किसी भी समय कर सकता है.

बाउंडेड मोड में, ऐल्फ़ा-ब्लेंडेड ट्रांसपेरेंसी का इस्तेमाल करना

बाउंडेड मोड में, पारदर्शी बैकग्राउंड की मदद से उपयोगकर्ता को अपने आस-पास की चीज़ें और अन्य विंडो, 3D मॉडल के आस-पास दिखती रहती हैं. अपने कैमरे या व्यूपोर्ट को पारदर्शी बैकग्राउंड के साथ कॉन्फ़िगर करें. साथ ही, ऐल्फ़ा-ब्लेंड एनवायरमेंट ब्लेंड मोड का इस्तेमाल करें. इमर्सिव मोड पर स्विच करते समय, पासथ्रू को चालू रखा जा सकता है या ओपेक स्काईबॉक्स एनवायरमेंट पर स्विच किया जा सकता है.

सुविधा की उपलब्धता देखना और मेनिफ़ेस्ट को कॉन्फ़िगर करना

स्पेशल कंटेनर के लिए, Android XR डिवाइस की ज़रूरत होती है. इस डिवाइस में स्पेशल एपीआई लेवल 4 या इसके बाद का वर्शन होना चाहिए. Android एपीआई लेवल की सीधे तौर पर जांच करने के बजाय, OpenXR रनटाइम से क्वेरी करें. इससे यह पता लगाया जा सकता है कि Spatial Containers काम करते हैं या नहीं. इसके लिए, xrEnumerateInstanceExtensionProperties को कॉल करके पुष्टि करें कि XR_EXT_spatial_container और XR_EXT_spatial_container_self_rendering उपलब्ध हैं. इसके बाद, XrSystemSpatialContainerPropertiesEXT के साथ xrGetSystemProperties को कॉल करके, supportsBounded और supportsImmersive की जांच करें.

स्पेशल कंटेनर का इस्तेमाल करने वाला ऐप्लिकेशन बनाने से पहले, AndroidManifest.xml में गतिविधि शुरू करने का मोड और किसी सुविधा के लिए ज़रूरी अनुमतियां कॉन्फ़िगर करें.

AndroidManifest.xml में फ़ुल स्पेस मोड चालू करना

स्पेशल कंटेनर के लिए, फ़ुल स्पेस मैनेज्ड मोड ज़रूरी है. भले ही, वे स्टैंडअलोन OpenXR ऐप्लिकेशन हों. फ़ुल-स्क्रीन वाले ट्रेडिशनल OpenXR ऐप्लिकेशन, सिस्टम विंडो मैनेजमेंट के बिना डिसप्ले का खास कंट्रोल लेने के लिए, XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED का एलान करते हैं. इसके उलट, स्पेशल कंटेनर का इस्तेमाल करने वाला ऐप्लिकेशन, Android XR सिस्टम कंपोज़िटर पर निर्भर करता है. इससे, फ़ुल स्पेस मोड में 3D बाउंडेड वॉल्यूम, विंडो कंट्रोल, और स्पेशल प्लेसमेंट को मैनेज किया जाता है. साथ ही, android.window.PROPERTY_XR_ACTIVITY_START_MODE को XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED पर सेट करना ज़रूरी है:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

किसी सुविधा के लिए ज़रूरी अनुमतियों के बारे में बताना और उनके लिए अनुरोध करना

बेसिक स्पेशल कंटेनर बनाने और उसे रेंडर करने के लिए, रनटाइम की खतरनाक अनुमतियों की ज़रूरत नहीं होती. हालांकि, कुछ सुविधाओं का इस्तेमाल करने के लिए, Android XR से जुड़ी अनुमतियों का एलान करना और उनके लिए अनुरोध करना ज़रूरी है:

• सीन को समझने की सुविधा का इस्तेमाल करके, किसी स्पेशल कंटेनर को फ़िज़िकल फ़्लोर पर लॉक और ऐंकर करने के लिए, रनटाइम के दौरान खतरनाक android.permission.SCENE_UNDERSTANDING_COARSE अनुमति का एलान करें और इसके लिए अनुरोध करें.
• OpenXR में उपयोगकर्ता के सिर की पोज़िशन को ट्रैक करने के लिए, android.permission.HEAD_TRACKING का एलान करें और इसके लिए अनुरोध करें.

<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

रनटाइम के दौरान, एक्सआर की खतरनाक अनुमतियों का एलान करने और उनके लिए अनुरोध करने के बारे में ज़्यादा जानने के लिए, एक्सआर के लिए अनुमतियों के बारे में जानकारी देखें.

अपने प्रोजेक्ट में स्पेशल कंटेनर चालू करना

Unity, Godot या C++ में OpenXR का इस्तेमाल करके, Spatial Containers की मदद से ऐप्लिकेशन बनाए जा सकते हैं. अपने पसंदीदा एनवायरमेंट के लिए ज़रूरी शर्तें, एडिटर सेटअप, और कोड का उदाहरण देखने के लिए, कोई टैब चुनें:

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

इन्हें भी देखें

• Unity में स्पेशल कंटेनर इस्तेमाल करना
• Godot में Spatial Containers का इस्तेमाल करना
• एक्सआर के लिए अनुमतियों के बारे में जानकारी

OpenXR™ और OpenXR लोगो, The Khronos Group Inc. के मालिकाना हक वाले ट्रेडमार्क हैं. इन्हें चीन, यूरोपियन यूनियन, जापान, और यूनाइटेड किंगडम में ट्रेडमार्क के तौर पर रजिस्टर किया गया है.