Öğ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, kalıtım 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. setParent() veya addChild()'ı çağırarak varlıkları sahne grafiği boyunca yeniden konumlandırabilirsiniz.

Öğelerin konumunu, dönüşünü veya görünürlüğünü değiştirmek gibi tüm öğeler için geçerli olan bazı varsayılan davranışları vardır. 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.

Bir Entity öğesinin görünürlüğünü değiştirmek için setHidden() simgesini kullanın.

// Hide the entity
entity.setHidden(true)
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, tutarlı kullanıcı arayüzü desenleriyle öğeleri 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. 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.

Herhangi bir dikey yüzeye ve yalnızca zemin ile tavan gibi yatay yüzeylere taşınıp sabitlenebilen bir öğe örneğini burada bulabilirsiniz.

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

Kullanıcı öğeyi hareket ettirdikçe scaleInZ parametresi, öğenin ölçeğini kullanıcıdan uzaklaştıkça 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, alt öğelerinin tümünü etkiler.

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

ResizableComponent kullanarak bir Varlığı yeniden boyutlandırılabilir 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 kullanırken onResizeUpdate veya onResizeEnd gibi belirli yeniden boyutlandırma etkinliklerine yanıt vermek için ResizeListener belirtmeniz gerekir.

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

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

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 almak için bir InputEventListener belirtmeniz gerekir. Kullanıcı herhangi bir giriş işlemi yaptığında onInputEvent yöntemi, InputEvent parametresinde sağlanan giriş bilgileriyle birlikte ç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_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