Dela via

Entiteter

  • Artikel

En entitet representerar ett flyttbart objekt i rymden och är det grundläggande byggblocket för fjärrrenderade innehåll.

Entitetsegenskaper

Entiteter har en transformering som definieras av en position, rotation och skala. Entiteter har i sig inga observerbara funktioner. I stället läggs beteendet till via komponenter som är kopplade till entiteter. Om du till exempel kopplar ett CutPlaneComponent skapas ett klippt plan på entitetens position.

Den viktigaste aspekten av själva entiteten är hierarkin och den resulterande hierarkiska transformeringen. När till exempel flera entiteter är kopplade som underordnade till en delad överordnad entitet kan alla dessa entiteter flyttas, roteras och skalas unisont genom att ändra transformering av den överordnade entiteten. Dessutom kan entitetens enabled tillstånd användas för att inaktivera synlighet och svar på ray casts för ett fullständigt underdiagram i hierarkin.

En entitet ägs unikt av dess överordnade, vilket innebär att när överordnad förstörs med Entity.Destroy(), så är dess underordnade och alla anslutna komponenter. Därför kan du ta bort en modell från scenen genom att anropa Destroy på rotnoden i en modell, som returneras av RenderingSession.Connection.LoadModelAsync() eller dess SAS-variant RenderingSession.Connection.LoadModelFromSasAsync().

Entiteter skapas när servern läser in innehåll eller när användaren vill lägga till ett objekt i scenen. Om en användare till exempel vill lägga till ett klippt plan för att visualisera det inre av ett nät kan användaren skapa en entitet där planet ska finnas och sedan lägga till komponenten klippt plan till det.

Skapa en entitet

Om du vill lägga till en ny entitet i scenen, till exempel för att skicka den som ett rotobjekt för att läsa in modeller eller koppla komponenter till den, använder du följande kod:

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;
}

Frågefunktioner

Det finns två typer av frågefunktioner på entiteter: synkrona och asynkrona anrop. Synkrona frågor kan bara användas för data som finns på klienten och som inte omfattar mycket beräkning. Exempel är frågor för komponenter, relativa objekttransformeringar eller överordnade/underordnade relationer. Asynkrona frågor används för data som endast finns på servern eller som innebär extra beräkning som skulle vara för dyr för att köras på klienten. Exempel är spatial bounds-frågor eller metadatafrågor.

Köra frågor mot komponenter

Om du vill hitta en komponent av en viss typ använder du 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>();

Köra frågor mot transformeringar

Transformeringsfrågor är synkrona anrop på objektet. Observera att transformeringar som lagras på API-sidan är lokala utrymmestransformeringar i förhållande till objektets överordnade objekt. Undantag är rotobjekt, för vilka lokalt utrymme och världsutrymme är identiska.

// 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();

Om alla trädtransformeringskomponenter (position, rotation och skalning) måste hämtas eller ställas in samtidigt rekommenderar vi att du använder entitetens LocalTransform egenskap:

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

Det finns också en hjälpfunktion för att hämta en entitets globala transformering (world space):

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

När GlobalTransform anropas beräknas den globala transformeringen direkt genom att bläddra uppåt i entitetshierarkin. Den här bläddringsfunktionen innebär betydande beräkning, men jämfört med att utföra samma åtgärder på klientsidan via klassen Entityär den inbyggda funktionen snabbare. Att anropa GlobalTransform en större uppsättning entiteter kan dock medföra en flaskhals för prestanda.

LocalToGlobalMatrix är en variant av GlobalTransform som beräknar den globala transformeringen som en matris, vilket är praktiskt i samband med Unity:

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

Köra frågor mot rumsliga gränser

Bounds-frågor är asynkrona anrop som körs i en fullständig objekthierarki med en entitet som rot. Se det dedikerade kapitlet om objektgränsen.

Köra frågor mot metadata

Metadata är extra data som lagras på objekt som ignoreras av servern. Objektmetadata är i huvudsak en uppsättning (namn, värde) par, där värdet kan vara av numerisk, boolesk eller strängtyp. Metadata kan exporteras med modellen.

Metadatafrågor är asynkrona anrop på en specifik entitet. Frågan returnerar endast metadata för en enskild entitet, inte den sammanfogade informationen i ett underdiagram.

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();

        // ...
    }
});

Frågan lyckas även om objektet inte innehåller några metadata.

API-dokumentation

Nästa steg