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

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

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 varlık-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 Jetpack SceneCore'un Session API'sini kullanarak sahne grafiğine erişebilirsiniz. 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 en ü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 çağrısını yaparak öğ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 Entity alt 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 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

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

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

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

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 ResizableComponent.create() 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 = MovableComponent.create(
    session = session,
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)
Entities.kt

Kullanıcı öğeyi hareket ettirirken scaleInZ parametresi, kullanıcıdan uzaklaştıkça öğenin ölçeğini otomatik olarak ayarlar. Bu, ana alanda panellerin sistem tarafından ölçeklendirilmesine benzer. Öğe bileşeni sisteminin "basamaklandırılmış" yapısı nedeniyle, üst öğenin ölçeği tüm alt öğelerini etkiler.

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ı belirleyerek genişlik ve yüksekliğin birbirine orantılı olarak yeniden boyutlandırılmasını sağlayabilirsiniz.

ResieableComponent kullanırken onResizeUpdate veya onResizeEnd gibi belirli yeniden boyutlandırma etkinliklerine yanıt vermek için bir ResizeListener belirtmeniz gerekir.

SurfaceEntity üzerinde sabit en boy oranına sahip ResizableComponent 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

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.

• InputEvent.action, bir öğenin üzerine gelme veya dokulama gibi giriş türlerini belirtir.
• InputEvent.source, girişin nereden geldiğini belirtir (ör. el veya denetleyici 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 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.

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