इकाइयां बनाना, उन्हें कंट्रोल करना, और मैनेज करना

Jetpack XR SDK टूल की मदद से, Entity इंस्टेंस बनाने, उन्हें कंट्रोल करने, और मैनेज करने के लिए, Jetpack SceneCore का इस्तेमाल किया जा सकता है. जैसे, 3D मॉडल, स्टीरियोस्कोपिक वीडियो, और PanelEntity.

Jetpack SceneCore, 3D डेवलपमेंट के लिए आर्किटेक्चर के दो सामान्य पैटर्न अपनाता है: सीन ग्राफ़ और इकाई-कॉम्पोनेंट सिस्टम (ईसीएस).

इकाइयां बनाने और उन्हें कंट्रोल करने के लिए, सीन ग्राफ़ का इस्तेमाल करना

3D स्पेस में ऑब्जेक्ट बनाने और उन्हें कंट्रोल करने के लिए, सीन ग्राफ़ का ऐक्सेस पाने के लिए, Jetpack SceneCore के Session API का इस्तेमाल किया जा सकता है. सीन ग्राफ़, उपयोगकर्ता की असल दुनिया के साथ अलाइन होता है. साथ ही, पैनल और 3D मॉडल जैसी 3D इकाइयों को हैरारकी वाले स्ट्रक्चर में व्यवस्थित करने और उन इकाइयों की स्थिति को बनाए रखने में मदद करता है.

सीन ग्राफ़ का ऐक्सेस मिलने के बाद, XR के लिए Jetpack Compose में मौजूद एपीआई का इस्तेमाल करके, सीन ग्राफ़ में स्पेसिएल यूज़र इंटरफ़ेस (उदाहरण के लिए, SpatialPanel और Orbiter) बनाया जा सकता है. 3D मॉडल जैसे 3D कॉन्टेंट के लिए, सीधे सेशन को ऐक्सेस किया जा सकता है. ज़्यादा जानने के लिए, इस पेज पर ActivitySpace के बारे में जानकारी देखें.

इकाई का कॉम्पोनेंट सिस्टम

इकाई-कॉम्पोनेंट सिस्टम, इनहेरिटेंस के बजाय कंपोज़िशन के सिद्धांत का पालन करता है. इकाइयों के व्यवहार को बेहतर बनाने के लिए, व्यवहार तय करने वाले कॉम्पोनेंट जोड़े जा सकते हैं. इससे, अलग-अलग तरह की इकाइयों पर एक जैसा व्यवहार लागू किया जा सकता है. ज़्यादा जानकारी के लिए, इस पेज पर इकाइयों के लिए सामान्य व्यवहार जोड़ना लेख पढ़ें.

ActivitySpace के बारे में जानकारी

हर Session में एक ActivitySpace होता है, जो Session के साथ अपने-आप बन जाता है. ActivitySpace, सीन ग्राफ़ में सबसे ऊपर वाला Entity होता है.

ActivitySpace, तीन डाइमेंशन वाले स्पेस को दिखाता है. इसमें राइट-हैंडड कोऑर्डिनेट सिस्टम (x-ऐक्सिस दाईं ओर, y-ऐक्सिस ऊपर, और z-ऐक्सिस ऑरिजिन के पीछे) होता है. साथ ही, इसमें इकाइयों के लिए मीटर का इस्तेमाल किया जाता है, जो असल दुनिया से मेल खाते हैं. ActivitySpace का ऑरिजिन कुछ हद तक मनमुताबिक होता है, क्योंकि उपयोगकर्ता असल दुनिया में ActivitySpace की पोज़िशन को रीसेट कर सकते हैं. इसलिए, हमारा सुझाव है कि कॉन्टेंट को ऑरिजिन के बजाय, एक-दूसरे के हिसाब से पोज़िशन करें.

इकाइयों के साथ काम करना

इकाइयां, SceneCore के लिए अहम हैं. उपयोगकर्ता को जो भी दिखता है और जिनसे वह इंटरैक्ट करता है वे इकाइयां, पैनल, 3D मॉडल वगैरह होती हैं.

ActivitySpace, सीन ग्राफ़ का टॉप-लेवल नोड है. इसलिए, डिफ़ॉल्ट रूप से, सभी नई इकाइयों को सीधे ActivitySpace में रखा जाता है. setParent या addChild को कॉल करके, सीन ग्राफ़ में इकाइयों को फिर से सेट किया जा सकता है.

इकाइयों के लिए कुछ डिफ़ॉल्ट व्यवहार होते हैं. ये सभी इकाइयों के लिए यूनिवर्सल होते हैं. जैसे, पोज़िशन, रोटेशन या दिखने की स्थिति बदलना. GltfEntity जैसी खास Entity सबक्लास में, सबक्लास के साथ काम करने वाली अतिरिक्त कार्रवाइयां होती हैं.

इकाइयों में बदलाव करना

जब किसी Entity प्रॉपर्टी में बदलाव किया जाता है, जो बेस Entity क्लास से जुड़ी होती है, तो यह बदलाव उसके सभी चाइल्ड पर लागू हो जाएगा. उदाहरण के लिए, माता-पिता Entity के Pose में बदलाव करने पर, उनके सभी बच्चों के लिए एक ही बदलाव होता है. चाइल्ड Entity में बदलाव करने से, उसके पैरंट पर कोई असर नहीं पड़ता.

Pose, 3D स्पेस में इकाई की जगह और घुमाव को दिखाता है. जगह एक Vector3 है, जिसमें x, y, z संख्यात्मक पोज़िशन होती हैं. रोटेशन को Quaternion से दिखाया जाता है. Entity की स्थिति हमेशा अपनी पैरंट इकाई के हिसाब से होती है. दूसरे शब्दों में, जिस Entity की पोज़िशन (0, 0, 0) है उसे पैरंट इकाई के ऑरिजिन पर रखा जाएगा.

// Place the entity forward 2 meters
val newPosition = Vector3(0f, 0f, -2f)
// Rotate the entity by 180 degrees on the up axis (upside-down)
val newOrientation = Quaternion.fromEulerAngles(0f, 0f, 180f)
// Update the position and rotation on the entity
entity.setPose(Pose(newPosition, newOrientation))
Entities.kt

किसी Entity की 'किसको दिखे' सेटिंग बदलने के लिए, setHidden का इस्तेमाल करें.

// Hide the entity
entity.setHidden(true)
Entities.kt

Entity का साइज़ बदलने के लिए, उसका आकार बदले बिना, setScale का इस्तेमाल करें.

// Double the size of the entity
entity.setScale(2f)
Entities.kt

इकाइयों के लिए सामान्य व्यवहार जोड़ना

इकाइयों में सामान्य व्यवहार जोड़ने के लिए, इन कॉम्पोनेंट का इस्तेमाल किया जा सकता है:

  • MovableComponent: उपयोगकर्ता को इकाइयों को एक से दूसरी जगह ले जाने की अनुमति देता है
  • ResizableComponent: इससे उपयोगकर्ता को यूज़र इंटरफ़ेस (यूआई) के एक जैसे पैटर्न वाली इकाइयों का साइज़ बदलने की अनुमति मिलती है
  • InteractableComponent: कस्टम इंटरैक्शन के लिए इनपुट इवेंट कैप्चर करने की सुविधा देता है

कॉम्पोनेंट को इंस्टैंशिएट करने के लिए, Session क्लास में कॉम्पोनेंट बनाने का सही तरीका अपनाना ज़रूरी है. उदाहरण के लिए, ResizableComponent बनाने के लिए, ResizableComponent.create() को कॉल करें.

Entity में किसी कॉम्पोनेंट के खास व्यवहार को जोड़ने के लिए, addComponent() का इस्तेमाल करें.

इकाई को उपयोगकर्ता के लिए मूव करने लायक बनाने के लिए, MovableComponent का इस्तेमाल करना

MovableComponent की मदद से, उपयोगकर्ता Entity को एक जगह से दूसरी जगह ले जा सकता है. यह भी तय किया जा सकता है कि इकाई को किसी तरह की सतह पर ऐंकर किया जा सकता है या नहीं. जैसे, हॉरिज़ॉन्टल या वर्टिकल सतहें या टेबल, दीवार या छत जैसी खास सिमेंटिक सतहें. ऐंकर के विकल्पों की जानकारी देने के लिए, MovableComponent बनाते समय AnchorPlacement का एक सेट तय करें.

यहां एक ऐसी इकाई का उदाहरण दिया गया है जिसे किसी भी वर्टिकल प्लैटफ़ॉर्म पर ले जाया और ऐंकर किया जा सकता है. साथ ही, इसे सिर्फ़ फ़्लोर और सीलिंग के हॉरिज़ॉन्टल प्लैटफ़ॉर्म पर ले जाया जा सकता है.

val anchorPlacement = AnchorPlacement.createForPlanes(
    planeTypeFilter = setOf(PlaneSemantic.FLOOR, PlaneSemantic.TABLE),
    planeSemanticFilter = setOf(PlaneType.VERTICAL)
)

val movableComponent = MovableComponent.create(
    session = session,
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)
Entities.kt

जब उपयोगकर्ता इकाई को एक जगह से दूसरी जगह ले जाता है, तो scaleInZ पैरामीटर अपने-आप इकाई के स्केल में बदलाव करता है. यह उसी तरह होता है जिस तरह होम स्पेस में सिस्टम, पैनल का स्केल बदलता है. इकाई कॉम्पोनेंट सिस्टम के "कैस्केडिंग" नेचर की वजह से, पैरंट के स्केल का असर उसके सभी चाइल्ड पर पड़ेगा.

ResizableComponent का इस्तेमाल करके, इकाई को उपयोगकर्ता के हिसाब से बड़ा या छोटा किया जा सकता है

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

ResieableComponent का इस्तेमाल करते समय, आपको onResizeUpdate या onResizeEnd जैसे साइज़ बदलने वाले खास इवेंट का जवाब देने के लिए, ResizeListener तय करना होगा.

यहां SurfaceEntity पर, तय आसपेक्ट रेशियो के साथ ResizableComponent का इस्तेमाल करने का उदाहरण दिया गया है:

val resizableComponent = ResizableComponent.create(session)
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f)
resizableComponent.fixedAspectRatio = 16f / 9f // Specify a 16:9 aspect ratio

resizableComponent.addResizeListener(
    executor,
    object : ResizeListener {
        override fun onResizeEnd(entity: Entity, finalSize: Dimensions) {

            // update the size in the component
            resizableComponent.size = finalSize

            // update the Entity to reflect the new size
            (entity as SurfaceEntity).canvasShape = SurfaceEntity.CanvasShape.Quad(finalSize.width, finalSize.height)
        }
    },
)

entity.addComponent(resizableComponent)
Entities.kt

उपयोगकर्ता के इनपुट इवेंट कैप्चर करने के लिए, InteractableComponent का इस्तेमाल करना

InteractableComponent की मदद से, उपयोगकर्ता के इनपुट इवेंट कैप्चर किए जा सकते हैं. जैसे, जब उपयोगकर्ता किसी Entity पर इंटरैक्ट करता है या उस पर कर्सर घुमाता है. InteractableComponent बनाते समय, आपको इनपुट इवेंट पाने के लिए, InputEventListener की जानकारी देनी होगी. जब उपयोगकर्ता कोई इनपुट ऐक्शन करता है, तो onInputEvent विधि को InputEvent पैरामीटर में दी गई खास इनपुट जानकारी के साथ कॉल किया जाएगा.

सभी InputEvent कॉन्स्टेंट की पूरी सूची के लिए, रेफ़रंस दस्तावेज़ देखें.

नीचे दिया गया कोड स्निपेट, InteractableComponent का इस्तेमाल करके किसी इकाई के साइज़ को बढ़ाने और घटाने का उदाहरण दिखाता है. इसके लिए, दाएं हाथ का इस्तेमाल किया जाता है और बाएं हाथ का इस्तेमाल किया जाता है.

val executor = Executors.newSingleThreadExecutor()
val interactableComponent = InteractableComponent.create(session, executor) {
    // when the user disengages with the entity with their hands
    if (it.source == InputEvent.SOURCE_HANDS && it.action == InputEvent.ACTION_UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.POINTER_TYPE_RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.POINTER_TYPE_LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)
Entities.kt