Godot में Spatial Containers का इस्तेमाल करना

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

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

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

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

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

अपने प्रोजेक्ट में Spatial Containers को कॉन्फ़िगर और इस्तेमाल करने के लिए, इस गाइड को पढ़ें.

स्पेशल कंटेनर कैसे काम करते हैं

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

• आपका पूरा ऐक्टिव 3D सीन, एक प्राइमरी स्पेशल कंटेनर में रखा जाता है. यह कंटेनर, सीन के ऑरिजिन (0, 0, 0) पर मौजूद होता है. कंटेनर में रखने के लिए, आपको अलग-अलग Node3D नोड को टैग या असाइन करने की ज़रूरत नहीं है.
• आपका ऐप्लिकेशन, मैनेज किए जा रहे फ़ुल स्पेस मोड में लॉन्च होता है. इसके लिए, वह बाउंड मोड (Bounded या Immersive) और शुरुआती बाउंड डाइमेंशन का इस्तेमाल करता है. इन्हें आपकी प्रोजेक्ट सेटिंग में कॉन्फ़िगर किया जाता है. बाउंडेड मोड में, सिस्टम आपके सीन में मौजूद किसी भी 3D ज्यामिति को अपने-आप क्लिप कर देता है. यह ज्यामिति, बाउंडिंग बॉक्स के डाइमेंशन से बाहर तक फैली होती है.
• डिफ़ॉल्ट रूप से, Android XR सिस्टम में विंडो कंट्रोल की सुविधा मिलती है. इससे उपयोगकर्ता, 3D स्पेस में बाउंडेड कंटेनर को पकड़ सकता है, उसे मूव कर सकता है, और उसकी पोज़िशन बदल सकता है. इसके अलावा, वह उसे छोटा और बंद भी कर सकता है. रनटाइम के दौरान, आपका ऐप्लिकेशन कंटेनर का साइज़ बदल सकता है. साथ ही, बाउंडेड मोड (OpenXRSpatialContainerState.BOUNDED) और फ़ुल-स्क्रीन इमर्सिव मोड (OpenXRSpatialContainerState.IMMERSIVE) के बीच स्विच कर सकता है. इसके अलावा, OpenXRSpatialContainerExtension सिंगलटन का इस्तेमाल करके, बाउंड और स्टेटस में होने वाले बदलावों पर प्रतिक्रिया दे सकता है.

ज़रूरी शर्तें

शुरू करने से पहले, पक्का करें कि आपका डेवलपमेंट एनवायरमेंट और टारगेट डिवाइस, इन ज़रूरी शर्तों को पूरा करते हों:

• Godot का वर्शन: Godot 4.8-dev या इसके बाद का वर्शन.
• प्रोजेक्ट सेटअप: Godot Engine प्रोजेक्ट सेटअप गाइड में दिए गए सभी चरणों को पूरा करें.
• Godot OpenXR Vendors Plugin: Godot OpenXR Vendors Plugin का 5.2 या इसके बाद का वर्शन इंस्टॉल करें. इससे Android XR के लिए खास तौर पर बनाए गए एक्सटेंशन काम करने लगते हैं.
• टारगेट डिवाइस: स्पेशल एपीआई लेवल 4 या इसके बाद के वर्शन के साथ काम करने वाला Android XR डिवाइस. रनटाइम के दौरान, OpenXRSpatialContainerExtension.is_enabled() को कॉल करें, ताकि यह पुष्टि की जा सके कि डिवाइस पर एक्सटेंशन उपलब्ध है या नहीं.

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

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

1. Project > Project Settings खोलें.
2. प्रोजेक्ट सेटिंग विंडो के सबसे ऊपर दाएं कोने में मौजूद, ऐडवांस सेटिंग टॉगल को चालू करें.
3. General > XR > Shaders पर जाएं और Enabled को चुनें.
4. General > XR > OpenXR पर जाएं और ये सेटिंग कॉन्फ़िगर करें:
   • प्रोजेक्ट के लिए OpenXR को चालू करने के लिए, चालू है को चुनें.
   • Environment Blend Mode को Alpha Blend पर सेट करें.
5. OpenXR में जाकर, Extensions सेक्शन पर जाएं और ये सेटिंग कॉन्फ़िगर करें:
   • रनटाइम की अनुमतियों के लिए अपने-आप अनुरोध करें को चुनें, ताकि आपका ऐप्लिकेशन, Android मेनिफ़ेस्ट में बताई गई एक्सआर की किसी भी अनुमति के लिए, स्टार्टअप के समय उपयोगकर्ता को अपने-आप प्रॉम्प्ट दिखाए.
   • स्पेशल कंटेनर सब-सेक्शन में जाकर, चालू है को चुनें.
   • Bounds Mode को Bounded पर सेट करें, ताकि ऐप्लिकेशन 3D बाउंडिंग बॉक्स में लॉन्च हो. इसके अलावा, Immersive पर सेट करें, ताकि ऐप्लिकेशन फ़ुल-स्क्रीन इमर्सिव मोड में लॉन्च हो.
   • Bounds को शुरुआती चौड़ाई, ऊंचाई, और गहराई के डाइमेंशन पर सेट करें. ये डाइमेंशन मीटर में होने चाहिए, जैसे कि Vector3(1.0, 1.0, 1.0).
6. General > Rendering > Viewport पर जाएं और Transparent Background को चुनें.

Android एक्सपोर्ट, अनुमतियां, और फ़ुल स्पेस मोड को कॉन्फ़िगर करना

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

Android एक्सपोर्ट प्रीसेट को कॉन्फ़िगर करना

1. Project > Export... पर जाएं और Android एक्सपोर्ट प्रीसेट चुनें.

2. Gradle Build में जाकर, Use Gradle Build को चुनें. इसके बाद, Min SDK को 34 या इसके बाद के वर्शन पर सेट करें.

   

3. XR Features में जाकर, XR Mode को OpenXR पर सेट करें. इसके बाद, Enable AndroidXR Plugin को चुनें.

   

4. Android XR की सुविधाएं में जाकर, एक्सपेरिमेंट के तौर पर उपलब्ध सुविधाएं इस्तेमाल करें को चुनें.

फ़्लोर लॉकिंग के लिए, सीन को समझने की अनुमतियां जोड़ना

बेसिक स्पेशल कंटेनर बनाने और उसे रेंडर करने के लिए, रनटाइम की खतरनाक अनुमतियों की ज़रूरत नहीं होती. साथ ही, Use Experimental Features चालू होने पर, मेनिफ़ेस्ट में android.permission.HEAD_TRACKING अपने-आप जुड़ जाता है. हालांकि, अगर आपका ऐप्लिकेशन सीन को समझने वाली सुविधाओं का इस्तेमाल करता है, जैसे कि किसी स्पेशल कंटेनर को फ़िज़िकल फ़्लोर पर लॉक और ऐंकर करना, तो आपके ऐप्लिकेशन को रनटाइम के दौरान android.permission.SCENE_UNDERSTANDING_COARSE अनुमति का एलान करना होगा और इसके लिए अनुरोध करना होगा.

Android XR की अनुमतियों के बारे में ज़्यादा जानने के लिए, एक्सआर की अनुमतियों के बारे में जानकारी देखें. अगर आपका ऐप्लिकेशन, फ़्लोर लॉकिंग या सीन अंडरस्टैंडिंग का इस्तेमाल करता है, तो android.permission.SCENE_UNDERSTANDING_COARSE का एलान करें और इसके लिए अनुरोध करें:

1. प्रोजेक्ट > एक्सपोर्ट करें... में जाकर > Android, अनुमतियां > कस्टम अनुमतियां पर जाएं और android.permission.SCENE_UNDERSTANDING_COARSE जोड़ें.

2. Project Settings > General > XR > OpenXR > Extensions में जाकर, Automatically Request Runtime Permissions को चुनने पर, OpenXR के शुरू होने पर आपका ऐप्लिकेशन अपने-आप रनटाइम की अनुमति का अनुरोध करता है. अगर आपको GDScript में मैन्युअल तरीके से अनुमति का अनुरोध करना है, तो OS.request_permission() को कॉल करें:

   if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
       OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")
   

फ़ुल स्पेस मोड को कॉन्फ़िगर करना

Android XR पर स्पेशल कंटेनर, सिर्फ़ फ़ुल स्पेस मोड (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED) के साथ काम करते हैं. पक्का करें कि आपकी Android गतिविधि, आपके कस्टम बिल्ड टेंप्लेट (android/build/AndroidManifest.xml, जिसे Project > Install Android Build Template... का इस्तेमाल करके इंस्टॉल किया गया है) में XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED का एलान करती हो:

<manifest ...>
    <application ...>
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED"
            tools:replace="android:value" />
        ...
    </application>
</manifest>

GDScript में स्पेशल कंटेनर के साथ काम करना

OpenXRSpatialContainerExtension सिंगलटन और OpenXRSpatialContainerState क्लास, GDScript में XR_EXT_spatial_container और XR_EXT_spatial_container_self_rendering एक्सटेंशन को एक्सपोज़ करती हैं. रनटाइम के दौरान, मुख्य स्पेशल कंटेनर की स्थिति और सीमाओं की जांच करने, कंटेनर सिग्नल सुनने, और BOUNDED मोड (3D बाउंडिंग बॉक्स) और IMMERSIVE मोड (फ़ुल-स्क्रीन अनबाउंडेड व्यू) के बीच ट्रांज़िशन का अनुरोध करने के लिए, OpenXRSpatialContainerExtension का इस्तेमाल करें.

स्पेशल कंटेनर सिग्नल से कनेक्ट करना

OpenXRSpatialContainerExtension.is_enabled() को देखें और पुष्टि करें कि मौजूदा डिवाइस पर, Spatial Container एक्सटेंशन काम करता है और चालू है. साथ ही, _ready() में कंटेनर की सीमाओं और स्थिति के सिग्नल से कनेक्ट करें.

OpenXRSpatialContainerExtension, स्पेशल कंटेनर के लिए, स्थिति के ये सिग्नल भेजता है:

• spatial_container_visibility_changed: कंटेनर के दिखने (true) या छिपने (false) पर, (spatial_container, is_visible) के साथ ट्रिगर होता है. is_visible के false होने पर, ऐनिमेशन, ऑडियो या सिम्युलेशन के अपडेट रोकें.
• spatial_container_interactability_changed: जब कंटेनर को उपयोगकर्ता के इनपुट का फ़ोकस मिलता है (true) या वह फ़ोकस खो देता है (false), तब (spatial_container, is_interactive) के साथ उत्सर्जित होता है. फ़ोकस बदलने पर, इंटरैक्टिव हाइलाइट और इनपुट हैंडलिंग की सुविधा को चालू या बंद करें.
• spatial_container_bounds_mode_changed: जब कंटेनर OpenXRSpatialContainerState.BOUNDED और OpenXRSpatialContainerState.IMMERSIVE के बीच स्विच करता है, तब (spatial_container, bounds_mode) के साथ एमिट होता है. एनवायरमेंट विज़ुअल (जैसे, स्काईबॉक्स या पासथ्रू) और मोड के हिसाब से यूज़र इंटरफ़ेस (यूआई) कंट्रोल को टॉगल करें.

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_bounds_mode_changed.connect(
            _on_bounds_mode_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_visibility_changed.connect(
            _on_visibility_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_interactability_changed.connect(
            _on_interactability_changed
        )

func _on_visibility_changed(_rid: RID, is_visible: bool) -> void:
    # Pause or resume simulation and audio based on visibility
    pass

func _on_interactability_changed(_rid: RID, is_interactive: bool) -> void:
    # Enable or disable input handling and focus highlights
    pass

3D कॉन्टेंट को कंटेनर की सीमाओं के हिसाब से स्केल करना

BOUNDED मोड में होने पर, अपने 3D कॉन्टेंट को bounds के सबसे छोटे डाइमेंशन के हिसाब से एक जैसा स्केल करें. इससे उसका आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) बना रहता है और वह हमेशा कंटेनर के सबसे छोटे हिस्से में फ़िट हो जाता है. IMMERSIVE मोड में ट्रांज़िशन करते समय, अपने सीन को 1:1 स्केल पर वापस लाएं:

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

func _on_bounds_mode_changed(
    _rid: RID, bounds_mode: OpenXRSpatialContainerState.BoundsMode
) -> void:
    if bounds_mode == OpenXRSpatialContainerState.IMMERSIVE:
        content_root.scale = Vector3.ONE

बाउंडेड और इमर्सिव मोड के बीच स्विच करना

बाउंडेड 3D वॉल्यूम और फ़ुल-स्क्रीन इमर्सिव व्यू के बीच स्विच करने के लिए, OpenXRSpatialContainerState.BOUNDED या OpenXRSpatialContainerState.IMMERSIVE के साथ request_main_spatial_container_bounds_mode को कॉल करें:

# Request transitioning to immersive mode (or pass BOUNDED to return)
OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
    OpenXRSpatialContainerState.IMMERSIVE
)

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

• स्पेशल कंटेनर की मदद से ऐप्लिकेशन बनाना
• एक्सआर के लिए अनुमतियों के बारे में जानकारी
• Godot XR के किसी मौजूदा प्रोजेक्ट में Android XR के लिए सहायता जोड़ना

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