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

Jetpack XR SDK'sı, 3D modeller, stereoskopik video ve PanelEntity gibi Entity örneklerini oluşturmak, kontrol etmek ve yönetmek için Jetpack SceneCore'u kullanmanıza olanak tanır.

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

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

3D uzayda nesne oluşturmak ve kontrol etmek için sahne grafiğine erişmek üzere Jetpack SceneCore'un Oturum API'sini kullanmanız gerekir. Sahne grafiği, kullanıcının gerçek dünyasıyla uyumlu hale gelir 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ştikten sonra, sahne grafiğinde mekansal kullanıcı arayüzü (ör. SpatialPanel ve Orbiter'ler) oluşturmak için XR için Jetpack Compose'daki API'leri kullanabilirsiniz. 3D modeller gibi 3D içerikler için doğrudan oturuma erişebilirsiniz. Daha fazla bilgi için bu sayfadaki ActivitySpace hakkında başlıklı makaleyi inceleyin.

Varlık bileşen sistemi

Varlık bileşeni sistemi, devralma yerine derleme ilkesini izler. Davranış tanımlayan bileşenler ekleyerek varlıkların davranışını genişletebilirsiniz. Bu bileşenler, aynı davranışı farklı varlık türlerine uygulamanıza olanak tanır. Daha fazla bilgi için bu sayfadaki Öğelere ortak davranış ekleme bölümüne göz atın.

ActivitySpace hakkında

Her Session için Session ile otomatik olarak oluşturulan bir ActivitySpace vardır. ActivitySpace, sahne grafiğindeki üst düzey Entity öğesidir.

ActivitySpace, sağ el koordinasyon sistemine (x ekseni sağa, y ekseni yukarı ve z ekseni orijine göre geriye doğru bakar) ve gerçek dünyayla eşleşen birimler için metrelere sahip 3 boyutlu bir alanı temsil eder. ActivitySpace için başlangıç noktası biraz keyfidir (kullanıcılar ActivitySpace'ün konumunu gerçek dünyada sıfırlayabileceğinden). Bu nedenle, içeriğin başlangıç noktasına göre değil, birbirine göre konumlandırılması önerilir.

Varlıklarla çalışma

Varlıklar, SceneCore'un merkezinde yer alır. Kullanıcının gördüğü ve etkileşimde bulunduğu her şeyin çoğu, 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'i çağırarak öğeleri sahne grafiğinde yeniden konumlandırabilirsiniz.

Öğeler, konum, rotasyon veya görünürlük gibi tüm öğeler için geçerli olan bazı varsayılan davranışlara sahiptir. GltfEntity gibi belirli Entityalt sınıflar, alt sınıfı destekleyen ek davranışlara sahiptir.

Varlıkları değiştirme

Temel Entity sınıfına ait bir Entity mülkünde yaptığınız değişiklik, tüm alt öğelerine de uygulanır. Örneğin, Entity üst öğesinin Pose değerini ayarlamak, tüm alt öğelerinin aynı ayara sahip olmasına neden olur. Alt Entity bölümünde yapılan bir değişiklik, üst öğeyi etkilemez.

Pose, öğenin 3D uzayda konumunu ve dönüşünü temsil eder. Konum, x, y, z sayısal konumlarından oluşan bir Vector3 bağımsız değişkenidir. Döndürme, Quaternion ile gösterilir. Bir Entity öğesinin konumu her zaman üst öğesine göredir. Diğer bir deyişle, konumu (0, 0, 0) olan bir Entity, üst öğesinin orijinine yerleştirilir.

//place the entity forward 2 meters
val modelPosition = 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))

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

//hide the entity
entity.setHidden(true)

Genel şeklini korurken bir Entity'ü yeniden boyutlandırmak için setScale simgesini kullanın.

//double the size of the entity
entity.setScale(2f)

Varlıklara ortak davranış ekleme

Öğelere ortak davranış eklemek için aşağıdaki bileşenleri kullanabilirsiniz:

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

Bileşenlerin örneklenmesi, Session sınıfındaki uygun oluşturma yöntemi aracılığıyla yapılmalıdır. Örneğin, ResizableComponent oluşturmak için session.createResizableComponent() işlevini çağırın.

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

Bir öğeyi kullanıcı tarafından taşınabilir hale getirmek için MovableComponent'i kullanın

MovableComponent, Entity'ın kullanıcı tarafından taşınmasına olanak tanır. Öğ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 AnchorPlacement grubu belirtin.

Aşağıda, herhangi bir dikey yüzeye ve yalnızca zemin ve tavan yatay yüzeylerine taşınıp sabitlenebilecek bir öğe örneği verilmiştir.

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

val movableComponent = xrSession.createMovableComponent(
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)

Bir öğeyi kullanıcı tarafından yeniden boyutlandırılabilir hale getirmek için ResizableComponent'i kullanın.

ResizableComponent, kullanıcıların Entity'ı yeniden boyutlandırmasına olanak tanır. ResizableComponent, kullanıcıyı bir Entity'ı yeniden boyutlandırmaya davet eden görsel etkileşim ipuçları içerir. ResizeableComponent'ü oluştururken minimum veya maksimum boyutu (metre cinsinden) belirtebilirsiniz. Ayrıca, yeniden boyutlandırırken sabit bir en boy oranı belirterek genişlik ve yüksekliğin birbirine orantılı olarak yeniden boyutlandırılmasını sağlayabilirsiniz.

ResizableComponent öğesinin sabit en boy oranında kullanıldığı bir örneği aşağıda bulabilirsiniz:

val resizableComponent = xrSession.createResizableComponent()
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f )
resizableComponent.fixedAspectRatio = 16f / 9f //Specify a 16:9 aspect ratio
entity.addComponent(resizableComponent)

Kullanıcı girişi etkinliklerini yakalamak için InteractableComponent'i kullanma

InteractableComponent, kullanıcının etkileşime geçtiği veya imleci bir Entity'ın üzerine getirdiği gibi giriş etkinliklerini yakalamanızı sağlar. InteractableComponent oluştururken giriş etkinliklerini almak için bir InputEventListener belirtmeniz gerekir. Kullanıcı herhangi bir giriş işlemi gerçekleştirdiğinde onInputEvent yöntemi, InputEvent parametresinde sağlanan belirli giriş bilgileriyle çağrılır.

Tüm InputEvent sabitlerinin tam listesi için referans dokümanlarına bakın.

Aşağıdaki kod snippet'inde, bir öğenin boyutunu sağ el ile artırmak ve sol el ile azaltmak için InteractableComponent kullanımıyla ilgili bir örnek gösterilmektedir.

private val executor by lazy { Executors.newSingleThreadExecutor() }
val interactableComponent = xrSession.createInteractableComponent(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)