Entitas

Artikel
10/26/2023

Entitas mewakili objek bergerak di ruang dan merupakan blok penyusun dasar konten yang dirender dari jarak jauh.

Properti entitas

Entitas memiliki transformasi yang ditentukan oleh posisi, rotasi, dan skala. Dengan sendirinya entitas tidak memiliki fungsionalitas yang dapat diamati. Sebaliknya, perilaku ditambahkan melalui komponen, yang melekat pada entitas. Misalnya, melampirkan CutPlaneComponent membuat bidang potong pada posisi entitas.

Aspek terpenting dari entitas itu sendiri adalah hierarki dan transformasi hierarki yang dihasilkan. Misalnya, saat beberapa entitas dilampirkan sebagai anak ke entitas induk bersama, semua entitas ini dapat dipindahkan, diputar, dan diskalakan serempak dengan mengubah transformasi entitas induk. Selain itu, status enabled entitas dapat digunakan untuk menonaktifkan visibilitas dan respons terhadap transmisi sinar untuk sub grafik penuh dalam hierarki.

Entitas dimiliki secara unik oleh induknya, yang berarti bahwa saat induk dihancurkan dengan Entity.Destroy(), begitu juga anak-anaknya dan semua komponen yang terhubung. Dengan demikian, menghapus model dari adegan dicapai dengan memanggil Destroy pada simpul akar model, yang ditampilkan oleh RenderingSession.Connection.LoadModelAsync() atau RenderingSession.Connection.LoadModelFromSasAsync() varian SAS.

Entitas dibuat saat server memuat konten atau saat pengguna ingin menambahkan objek ke adegan. Misalnya, jika pengguna ingin menambahkan bidang potong untuk memvisualisasikan interior jala, pengguna dapat membuat entitas saat bidang harus ada dan kemudian menambahkan komponen bidang potong ke dalamnya.

Membuat entitas

Untuk menambahkan entitas baru ke adegan, misalnya untuk meneruskannya sebagai objek akar untuk memuat model atau melampirkan komponen ke dalamnya, gunakan kode berikut:

Entity CreateNewEntity(RenderingSession session)
{
    Entity entity = session.Connection.CreateEntity();
    entity.Position = new LocalPosition(1, 2, 3);
    return entity;
}

ApiHandle<Entity> CreateNewEntity(ApiHandle<RenderingSession> session)
{
    ApiHandle<Entity> entity(nullptr);
    if (auto entityRes = session->Connection()->CreateEntity())
    {
        entity = entityRes.value();
        entity->SetPosition(Double3{ 1, 2, 3 });
        return entity;
    }
    return entity;
}

Fungsi kueri

Ada dua jenis fungsi kueri pada entitas: panggilan sinkron dan asinkron. Kueri sinkron hanya dapat digunakan untuk data yang ada pada klien dan tidak melibatkan banyak komputasi. Contohnya adalah kueri untuk komponen, transformasi objek relatif, atau hubungan induk/anak. Kueri asinkron digunakan untuk data yang hanya berada di server atau melibatkan komputasi ekstra yang akan terlalu mahal untuk dijalankan pada klien. Contohnya adalah kueri batas spasial atau kueri data meta.

Komponen kueri

Untuk menemukan komponen dari jenis tertentu, gunakan FindComponentOfType:

CutPlaneComponent cutplane = (CutPlaneComponent)entity.FindComponentOfType(ObjectType.CutPlaneComponent);

// or alternatively:
CutPlaneComponent cutplane = entity.FindComponentOfType<CutPlaneComponent>();

ApiHandle<CutPlaneComponent> cutplane = entity->FindComponentOfType(ObjectType::CutPlaneComponent)->as<CutPlaneComponent>();

// or alternatively:
ApiHandle<CutPlaneComponent> cutplane = entity->FindComponentOfType<CutPlaneComponent>();

Mengkueri transformasi

Kueri transformasi adalah panggilan sinkron pada objek. Penting untuk dicatat bahwa transformasi yang disimpan di sisi API adalah transformasi ruang lokal, relatif terhadap induk objek. Pengecualian adalah objek akar, yang mana ruang lokal dan ruang dunia identik.

// local space transform of the entity
Double3 translation = entity.Position;
Quaternion rotation = entity.Rotation;
Float3 scale = entity.Scale;

// local space transform of the entity
Double3 translation = entity->GetPosition();
Quaternion rotation = entity->GetRotation();
Float3 scale = entity->GetScale();

Jika semua komponen transformasi pohon (posisi, rotasi, dan skala) perlu diambil atau diatur secara bersamaan, disarankan untuk menggunakan properti entitas LocalTransform :

// local space transform of the entity
Transform localTransform = entity.LocalTransform;
Double3 translation = localTransform.Position;
Quaternion rotation = localTransform.Rotation;
Float3 scale = localTransform.Scale;

// local space transform of the entity
Transform localTransform = entity->GetLocalTransform();
Double3& translation = localTransform.Position;
Quaternion& rotation = localTransform.Rotation;
Float3& scale = localTransform.Scale;

Ada juga fungsi pembantu untuk mengambil transformasi global (ruang dunia) entitas:

// global space transform of the entity
Transform globalTransform = entity.GlobalTransform;
Double3 translation = globalTransform.Position;

// global space transform of the entity
Transform globalTransform = entity->GetGlobalTransform();
Double3& translation = globalTransform.Position;

Ketika GlobalTransform dipanggil, transformasi global dihitung secara on-the-fly dengan melintas ke hierarki entitas. Traversal ini melibatkan komputasi yang signifikan, tetapi dibandingkan dengan melakukan operasi yang sama di sisi klien melalui kelas Entity, fungsi bawaan lebih cepat. Namun, memanggil GlobalTransform sekumpulan entitas yang lebih besar mungkin memberlakukan penyempitan performa.

LocalToGlobalMatrix adalah varian GlobalTransform yang menghitung transformasi global sebagai matriks, yang nyaman dalam konteks Unity:

UnityEngine.Matrix4x4 globalMatrix = entity.LocalToGlobalMatrix.toUnity();
UnityEngine.Vector3 localPos = new UnityEngine.Vector3(0, 0, 0);
UnityEngine.Vector3 globalPos = globalMatrix.MultiplyPoint(localPos);

Mengkueri batas spasial

Kueri batas adalah panggilan asinkron yang beroperasi pada hierarki objek penuh, menggunakan satu entitas sebagai akar. Lihat bab khusus tentang batas objek.

Mengkueri metadata

Metadata adalah data tambahan yang disimpan pada objek yang diabaikan oleh server. Metadata objek pada dasarnya adalah sekumpulan pasangan (nama, nilai), yang mana nilai dapat berupa jenis numerik, boolean, atau string. Metadata dapat diekspor dengan model.

Kueri metadata adalah panggilan asinkron pada entitas tertentu. Kueri hanya menampilkan metadata entitas tunggal, bukan informasi gabungan dari sub grafik.

Task<ObjectMetadata> metaDataQuery = entity.QueryMetadataAsync();
ObjectMetadata metaData = await metaDataQuery;
ObjectMetadataEntry entry = metaData.GetMetadataByName("MyInt64Value");
System.Int64 intValue = entry.AsInt64;
// ...

entity->QueryMetadataAsync([](Status status, ApiHandle<ObjectMetadata> metaData) 
{
    if (status == Status::OK)
    {
        ApiHandle<ObjectMetadataEntry> entry = *metaData->GetMetadataByName("MyInt64Value");
        int64_t intValue = *entry->GetAsInt64();

        // ...
    }
});

Kueri berhasil meskipun objek tidak menyimpan metadata apa pun.

Bagikan melalui