Entity

Článek
10/26/2023

Entita představuje pohyblivý objekt v prostoru a je základním stavebním blokem vzdáleně vykresleného obsahu.

Vlastnosti entit

Entity mají transformaci definovanou polohou, otočením a měřítkem. Entity samy o sobě nemají žádné pozorovatelné funkce. Místo toho se chování přidává prostřednictvím komponent, které jsou připojené k entitám. Například připojení CutPlaneComponent vytvoří rovinu řezu na pozici entity.

Nejdůležitějším aspektem samotné entity je hierarchie a výsledná hierarchická transformace. Pokud je například k sdílené nadřazené entitě připojeno více entit jako podřízených entit, můžete všechny tyto entity přesunout, otočit a škálovat beze změny transformace nadřazené entity. Stav entity enabled lze také použít k vypnutí viditelnosti a odpovědí na paprskové přetypování pro úplný dílčí graf v hierarchii.

Entita je jedinečně vlastněna svým nadřazeným objektem, což znamená, že když je nadřazený objekt zničen s Entity.Destroy(), tak jsou jeho podřízené a všechny propojené komponenty. Odebrání modelu ze scény je tedy dosaženo voláním Destroy kořenového uzlu modelu vráceného nebo jeho variantou RenderingSession.Connection.LoadModelAsync()RenderingSession.Connection.LoadModelFromSasAsync()SAS .

Entity se vytvoří, když server načte obsah nebo když chce uživatel přidat objekt do scény. Pokud například chce uživatel přidat rovinu řezu pro vizualizaci interiéru sítě, může uživatel vytvořit entitu, ve které by rovina měla existovat, a pak do ní přidat komponentu roviny řezu.

Vytvoření entity

Pokud chcete do scény přidat novou entitu, například ji předat jako kořenový objekt pro načítání modelů nebo připojení komponent k ní, použijte následující kód:

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

Funkce dotazů

U entit existují dva typy funkcí dotazů: synchronní a asynchronní volání. Synchronní dotazy se dají použít jenom pro data, která jsou v klientovi přítomná, a nezahrnuje mnoho výpočtů. Příklady dotazování na komponenty, relativní transformace objektů nebo vztahy nadřazenosti/podřízenosti. Asynchronní dotazy se používají pro data, která se nacházejí pouze na serveru, nebo zahrnují další výpočty, které by byly příliš drahé ke spuštění v klientovi. Příklady jsou dotazy na prostorové hranice nebo dotazy na meta data.

Dotazování komponent

Chcete-li najít součást určitého typu, použijte 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>();

Dotazování transformací

Transformační dotazy jsou synchronní volání objektu. Je důležité si uvědomit, že transformace uložené na straně rozhraní API jsou transformace místního prostoru vzhledem k nadřazené objektu. Výjimky jsou kořenové objekty, pro které jsou místní prostor a svět identické.

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

V případě, že všechny komponenty transformace stromu (pozice, otočení a měřítko) musí být načítány nebo nastaveny současně, doporučujeme použít vlastnost entity 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;

K dispozici je také pomocná funkce pro načtení globální transformace entity (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;

Při GlobalTransform zavolání se globální transformace vypočítává průběžně procházením hierarchie entit. Tento procházení zahrnuje významné výpočty, ale ve srovnání s prováděním stejných operací na straně klienta prostřednictvím třídy Entity, integrovaná funkce je rychlejší. GlobalTransform Volání větší sady entit může přesto vyžadovat kritický bod výkonu.

LocalToGlobalMatrix je varianta GlobalTransform , která vypočítá globální transformaci jako matici, což je výhodné v kontextu Unity:

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

Dotazování prostorových hranic

Vázané dotazy jsou asynchronní volání, která pracují s úplnou hierarchií objektů a používají jednu entitu jako kořen. Podívejte se na vyhrazenou kapitolu o hranicích objektů.

Dotazování metadat

Metadata jsou další data uložená na objektech, které server ignoruje. Metadata objektu jsou v podstatě sada párů (název, hodnota), kde hodnota může být číselný, logický nebo řetězcový typ. Metadata je možné exportovat pomocí modelu.

Dotazy na metadata jsou asynchronní volání konkrétní entity. Dotaz vrátí pouze metadata jedné entity, nikoli sloučené informace dílčího grafu.

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

        // ...
    }
});

Dotaz bude úspěšný i v případě, že objekt neobsahuje žádná metadata.