Öğe oluşturma, kontrol etme ve yönetme

Jetpack XR SDK, Jetpack SceneCore'u kullanarak Entity gibi 3D modeller, stereoskopik video ve PanelEntity örnekleri oluşturmanıza, kontrol etmenize ve yönetmenize olanak tanır.

Jetpack SceneCore, 3D geliştirmeyi desteklemek için iki yaygın mimari kalıbı kullanır: sahne grafiği ve varlık-bileşen sistemi (ECS).

Varlıkları oluşturmak ve kontrol etmek için sahne grafiğini kullanma

3D uzayda nesneler oluşturmak ve bunları kontrol etmek için Jetpack SceneCore'un Session API'sini kullanarak sahne grafiğine erişebilirsiniz. Sahne grafiği, kullanıcının gerçek dünyasıyla uyumludur ve paneller ile 3D modeller gibi 3D öğeleri hiyerarşik bir yapıda düzenlemenize ve bu öğelerin durumunu korumanıza olanak tanır.

Sahne grafiğine erişim kazandıktan sonra, sahne grafiğinde uzamsal kullanıcı arayüzü (ör. SpatialPanel ve Orbiter örnekleri) oluşturmak için Jetpack Compose for XR'daki API'leri kullanabilirsiniz. 3D modeller gibi 3D içeriklerde oturuma doğrudan erişebilirsiniz. Daha fazla bilgi için bu sayfadaki ActivitySpace hakkında bölümüne bakın.

Varlık bileşen sistemi

Bir varlık bileşen sistemi, devralma yerine kompozisyon ilkesini izler. Davranış tanımlayan bileşenler ekleyerek varlıkların davranışını genişletebilirsiniz. Bu sayede, aynı davranışı farklı türlerdeki varlıklara uygulayabilirsiniz. Daha fazla bilgi için bu sayfadaki Varlıklara ortak davranış ekleme bölümüne bakın.

ActivitySpace hakkında

Her Session, Session ile otomatik olarak oluşturulan bir ActivitySpace içerir. ActivitySpace, sahne grafiğindeki en üst düzey Entity'dir.

ActivitySpace, sağ el koordinat sistemine sahip (x ekseni sağa, y ekseni yukarı, z ekseni ise başlangıç noktasına göre geriye doğru yönlendirir) ve gerçek dünyayla eşleşen birimler için metre kullanan 3 boyutlu bir alanı temsil eder. ActivitySpace için başlangıç noktası biraz rastgeledir (kullanıcılar ActivitySpace konumunu gerçek dünyada sıfırlayabilir). Bu nedenle, içeriği başlangıç noktasına göre değil, birbirine göre konumlandırmanız önerilir.

Varlıklarla çalışma

Varlıklar, SceneCore'un temelini oluşturur. Kullanıcının gördüğü ve etkileşimde bulunduğu neredeyse her şey panelleri, 3D modelleri ve daha fazlasını temsil eden öğelerdir.

ActivitySpace, sahne grafiğinin üst düzey düğümü olduğundan varsayılan olarak tüm yeni öğeler doğrudan ActivitySpace içine yerleştirilir. parent değerini ayarlayarak veya addChild() kullanarak sahne grafiğindeki öğeleri yeniden konumlandırabilirsiniz.

Öğelerin, tüm öğeler için geçerli olan bazı varsayılan davranışları vardır. Örneğin, konum, yön veya görünürlük değiştirme. Entity gibi belirli GltfModelEntity alt sınıfları, alt sınıfı destekleyen ek davranışlara sahiptir.

Öğeleri değiştirme

EntityTemel Entity sınıfına ait bir özellikte değişiklik yaptığınızda bu değişiklik, tüm alt öğelere yansıtılır. Örneğin, bir üst öğenin Pose ayarlandığında tüm alt öğeleri aynı şekilde ayarlanır.Entity Bir alt kuruluş biriminde yapılan değişiklikler üst kuruluş birimini etkilemez.Entity

Pose, öğenin 3D uzaydaki konumunu ve dönüşünü gösterir. Konum, x, y, z sayısal konumlarından oluşan bir Vector3'dir. Dönüş Quaternion ile gösterilir. Bir Entity öğesinin konumu her zaman üst öğesine göre belirlenir. Diğer bir deyişle, konumu (0, 0, 0) olan bir Entity, üst öğesinin başlangıç noktasına yerleştirilir.

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

Önemli: Bir Entity konumunu tartışırken Entity'in Sahne Grafiği'nde belirli bir noktada bulunabileceğini ve 3D uzayda da bir konumu olduğunu unutmayın.

Entity devre dışı bırakmak için setEnabled() kullanın. Bu işlem, öğeyi görünmez hale getirir ve üzerinde yapılan tüm işlemleri durdurur.

// Disable the entity.
entity.setEnabled(false)
Entities.kt

Entity şeklini genel şeklini koruyarak yeniden boyutlandırmak için setScale() simgesini kullanın.

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

Dikkat: Bir Entity öğesinin ölçeği, koordinat sisteminin birimlerini etkiler. Örneğin, ölçeği 2 olarak değiştirdiğinizde bu öğedeki her birim artık gerçek dünyada 1 metreyi değil, 2 metreyi temsil eder. Bu durum, tüzel kişinin alt öğeleri için de geçerlidir.

Varlıklara ortak davranış ekleme

Aşağıdaki bileşenleri kullanarak varlıklara ortak davranışlar ekleyebilirsiniz:

• MovableComponent: Kullanıcının öğeleri taşımasına olanak tanır.
• ResizableComponent: Kullanıcının, öğeleri tutarlı kullanıcı arayüzü kalıplarıyla yeniden boyutlandırmasına olanak tanır.
• InteractableComponent: Özel etkileşimler için giriş etkinliklerini yakalamanıza olanak tanır.

Bileşenlerin oluşturulması, Session sınıfındaki uygun oluşturma yöntemiyle yapılmalıdır. Örneğin, ResizableComponent oluşturmak için ResizableComponent.create()'ı arayın.

Önizleme: Şu anda tüm bileşenler her türden öğede kullanılamaz. Hangi öğelerin desteklendiğini görmek için ilgili bileşenin dokümanlarına bakın.

Belirli bileşen davranışını bir Entity öğesine eklemek için addComponent() yöntemini kullanın.

Bir varlığı kullanıcı tarafından taşınabilir hale getirmek için MovableComponent kullanma

MovableComponent, Entity öğesinin kullanıcı tarafından taşınmasına olanak tanır.

Süslemelerle etkileşimde bulunulduğunda hareket etkinlikleri bileşene gönderilir. MovableComponent.createSystemMovable() ile oluşturulan varsayılan sistem davranışı, süslemeler sürüklendiğinde Entity öğenizi hareket ettirir:

val movableComponent = MovableComponent.createSystemMovable(session)
entity.addComponent(movableComponent)
MovableComponent.kt

İsteğe bağlı scaleInZ parametresi (varsayılan olarak true olarak ayarlanır), kullanıcının yanından uzaklaştırıldığında Entity'nin ölçeğini otomatik olarak ayarlar. Bu, ev alanında panellerin sistem tarafından ölçeklenmesine benzer. Varlık bileşeni sisteminin "basamaklı" yapısı nedeniyle üst öğenin ölçeği tüm alt öğelerini etkiler.

Ayrıca öğenin yatay veya dikey yüzeyler gibi bir yüzey türüne ya da masa, duvar veya tavan gibi belirli semantik yüzeylere sabitlenip sabitlenemeyeceğini de belirtebilirsiniz. Sabitleme seçeneklerini belirtmek için MovableComponent oluştururken bir dizi AnchorPlacement belirtin. Bu örnekte, herhangi bir kata veya masa gibi yatay bir yüzeye taşınabilen ve sabitlenebilen öğe:

val anchorPlacement = AnchorPlacement.createForPlanes(
    anchorablePlaneOrientations = setOf(PlaneOrientation.VERTICAL),
    anchorablePlaneSemanticTypes = setOf(PlaneSemanticType.FLOOR, PlaneSemanticType.TABLE)
)

val movableComponent = MovableComponent.createAnchorable(
    session = session,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)
MovableComponent.kt

Not: Uzamsallaştırılmış kullanıcı arayüzünüzü XR için Jetpack Compose ile oluşturuyorsanız panellerinizin hareket etmesini sağlamak için movable alt alan değiştiricisini kullanabilirsiniz.

ResizableComponent kullanarak bir Varlık'ın boyutunu kullanıcı tarafından değiştirilebilir hale getirme

ResizableComponent, kullanıcıların Entity boyutunu değiştirmesine olanak tanır. ResizableComponent, kullanıcıyı Entity boyutunu değiştirmeye davet eden görsel etkileşim ipuçları içerir. ResizableComponent oluştururken minimum veya maksimum boyut (metre cinsinden) belirtebilirsiniz. Yeniden boyutlandırma sırasında sabit bir en boy oranı belirterek genişlik ve yüksekliğin birbirleriyle orantılı olarak yeniden boyutlandırılmasını da sağlayabilirsiniz.

ResizableComponent oluştururken güncelleme etkinliklerini işleyen bir resizeEventListener belirtin. RESIZE_STATE_ONGOING veya RESIZE_STATE_END gibi farklı ResizeState etkinliklerine yanıt verebilirsiniz.

ResizableComponent öğesini SurfaceEntity üzerinde sabit en boy oranıyla kullanma örneğini aşağıda bulabilirsiniz:

val resizableComponent = ResizableComponent.create(session) { event ->
    if (event.resizeState == ResizeEvent.ResizeState.RESIZE_STATE_END) {
        // update the Entity to reflect the new size
        surfaceEntity.canvasShape = SurfaceEntity.CanvasShape.Quad(event.newSize.width, event.newSize.height)
    }
}
resizableComponent.minimumEntitySize = FloatSize3d(177f, 100f, 1f)
resizableComponent.fixedAspectRatio = 16f / 9f // Specify a 16:9 aspect ratio

surfaceEntity.addComponent(resizableComponent)
ResizableComponent.kt

Not: Uzamsallaştırılmış kullanıcı arayüzünüzü XR için Jetpack Compose ile oluşturuyorsanız panellerinizin yeniden boyutlandırılmasını sağlamak için resizable alt alan değiştiricisini kullanabilirsiniz.

Kullanıcı girişi etkinliklerini yakalamak için InteractableComponent kullanın

InteractableComponent, kullanıcının giriş etkinliklerini (ör. kullanıcının bir Entity ile etkileşime girdiği veya imleci Entity'ın üzerine getirdiği zaman) yakalamanıza olanak tanır. InteractableComponent oluştururken giriş etkinliklerini alan bir dinleyici belirtin. Kullanıcı herhangi bir giriş işlemi gerçekleştirdiğinde, dinleyici InputEvent parametresinde sağlanan giriş bilgileriyle çağrılır.

• InputEvent.action, bir öğenin üzerine gelme veya dokunma gibi giriş türünü belirtir.
• InputEvent.source, girişin nereden geldiğini belirtir (ör. el veya kontrol cihazı girişi).
• InputEvent.pointerType, girişin sağ elden mi yoksa sol elden mi geldiğini belirtir.

Tüm InputEvent sabitlerinin tam listesi için referans belgelerine bakın.

Aşağıdaki kod snippet'inde, sağ elle bir öğenin boyutunu büyütmek ve sol elle küçültmek için InteractableComponent kullanma örneği gösterilmektedir.

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.SOURCE_HANDS && it.action == InputEvent.Action.ACTION_UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.Pointer.POINTER_TYPE_RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.Pointer.POINTER_TYPE_LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)
InteractableComponent.kt