Entiteiten

Artikel
10/26/2023

Een entiteit vertegenwoordigt een verplaatsbaar object in de ruimte en is de fundamentele bouwsteen van extern gerenderde inhoud.

Entiteitseigenschappen

Entiteiten hebben een transformatie die is gedefinieerd door een positie, rotatie en schaal. Entiteiten hebben zelf geen waarneembare functionaliteit. In plaats daarvan wordt gedrag toegevoegd via onderdelen die zijn gekoppeld aan entiteiten. Als u bijvoorbeeld een CutPlaneComponent koppelt, wordt een knipvlak gemaakt op de positie van de entiteit.

Het belangrijkste aspect van de entiteit zelf is de hiërarchie en de resulterende hiërarchische transformatie. Wanneer bijvoorbeeld meerdere entiteiten zijn gekoppeld als onderliggende entiteiten aan een gedeelde bovenliggende entiteit, kunnen al deze entiteiten worden verplaatst, geroteerd en geschaald in één eenheid door de transformatie van de bovenliggende entiteit te wijzigen. Daarnaast kan de status van enabled de entiteit worden gebruikt om zichtbaarheid en antwoorden op raycasts uit te schakelen voor een volledige subgrafiek in de hiërarchie.

Een entiteit is uniek eigendom van de bovenliggende entiteit, wat betekent dat wanneer het bovenliggende element wordt vernietigd, Entity.Destroy()dus de onderliggende elementen en alle verbonden onderdelen. Het verwijderen van een model uit de scène wordt dus bereikt door het hoofdknooppunt van een model aan te roepen Destroy , geretourneerd door RenderingSession.Connection.LoadModelAsync() of de SAS-variant RenderingSession.Connection.LoadModelFromSasAsync().

Entiteiten worden gemaakt wanneer de server inhoud laadt of wanneer de gebruiker een object aan de scène wil toevoegen. Als een gebruiker bijvoorbeeld een knipvlak wil toevoegen om het interieur van een mesh te visualiseren, kan de gebruiker een entiteit maken waarin het vliegtuig moet bestaan en vervolgens het snijvlakonderdeel eraan toevoegen.

Een entiteit maken

Als u een nieuwe entiteit wilt toevoegen aan de scène, bijvoorbeeld om deze als hoofdobject door te geven voor het laden van modellen of het koppelen van onderdelen aan de scène, gebruikt u de volgende code:

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

Queryfuncties

Er zijn twee typen queryfuncties voor entiteiten: synchrone en asynchrone aanroepen. Synchrone query's kunnen alleen worden gebruikt voor gegevens die aanwezig zijn op de client en er zijn niet veel berekeningen nodig. Voorbeelden zijn het uitvoeren van query's op onderdelen, relatieve objecttransformaties of bovenliggende/onderliggende relaties. Asynchrone query's worden gebruikt voor gegevens die zich alleen op de server bevinden of extra berekeningen uitvoeren die te duur zijn om op de client uit te voeren. Voorbeelden zijn query's voor ruimtelijke grenzen of metagegevensquery's.

Query's uitvoeren op onderdelen

Als u een onderdeel van een specifiek type wilt vinden, gebruikt u 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>();

Transformaties opvragen

Transformatiequery's zijn synchrone aanroepen voor het object. Het is belangrijk te weten dat transformaties die zijn opgeslagen aan de API-zijde lokale ruimtetransformaties zijn ten opzichte van het bovenliggende object. Uitzonderingen zijn hoofdobjecten, waarvoor lokale ruimte en wereldruimte identiek zijn.

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

Als alle onderdelen van de structuurtransformatie (positie, rotatie en schaal) tegelijkertijd moeten worden opgehaald of ingesteld, is het raadzaam om de eigenschap van LocalTransform de entiteit te gebruiken:

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

Er is ook een helperfunctie om de wereldwijde transformatie van een entiteit (wereldruimte) op te halen:

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

Wanneer GlobalTransform deze wordt aangeroepen, wordt de globale transformatie on-the-fly berekend door de entiteitshiërarchie te doorlopen. Deze doorkruising omvat aanzienlijke berekeningen, maar vergeleken met het uitvoeren van dezelfde bewerkingen aan de clientzijde via klasse Entity, is de ingebouwde functie sneller. Toch kan het aanroepen GlobalTransform van een grotere set entiteiten een prestatieknelpunt vormen.

LocalToGlobalMatrix is een variant van GlobalTransform die de wereldwijde transformatie berekent als een matrix, wat handig is in de context van Unity:

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

Query's uitvoeren op ruimtelijke grenzen

Afhankelijke query's zijn asynchrone aanroepen die worden uitgevoerd op een volledige objecthiërarchie, waarbij één entiteit als hoofdobject wordt gebruikt. Zie het speciale hoofdstuk over objectgrenzen.

Query's uitvoeren op metagegevens

Metagegevens zijn extra gegevens die zijn opgeslagen op objecten die door de server worden genegeerd. Objectmetagegevens zijn in wezen een set paren (naam, waarde), waarbij de waarde van numeriek, booleaans of tekenreekstype kan zijn. Metagegevens kunnen worden geëxporteerd met het model.

Metagegevensquery's zijn asynchrone aanroepen voor een specifieke entiteit. De query retourneert alleen de metagegevens van één entiteit, niet de samengevoegde gegevens van een subgrafiek.

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

        // ...
    }
});

De query slaagt zelfs als het object geen metagegevens bevat.