Entitäten

  • Artikel

Eine Entität stellt ein bewegliches Objekt im Raum dar und ist der grundlegende Baustein von remote gerendertem Inhalt.

Entitätseigenschaften

Entitäten verfügen über eine Transformation, die durch eine Position, eine Drehung und einen Maßstab definiert ist. Von sich selbst verfügen Entitäten nicht über eine feststellbare Funktionalität. Stattdessen wird Verhalten durch Komponenten hinzugefügt, die an Entitäten angefügt werden. Durch das Anfügen eines CutPlaneComponent-Elements wird beispielsweise eine Schnittebene an der Position der Entität erstellt.

Der wichtigste Aspekt der Entität selbst ist die Hierarchie und die sich ergebende hierarchische Transformation. Wenn mehrere Entitäten beispielsweise als untergeordnete Elemente einer freigegebenen übergeordneten Entität angefügt werden, können alle diese Entitäten durch Ändern der Transformation der übergeordneten Entität verschoben, gedreht und gemeinsam skaliert werden. Der Zustand enabled der Entität kann auch verwendet werden, um die Sichtbarkeit und die Reaktionen auf Raycasts für einen vollständigen Untergraphen in der Hierarchie zu deaktivieren.

Eine Entität befindet sich im Besitz ihres übergeordneten Elements. Wenn das übergeordnete Element mit Entity.Destroy() zerstört wird, gilt dies daher auch für die untergeordneten Elemente und alle verbundenen Komponenten. Daher wird das Entfernen eines Modells aus der Szene erreicht, indem Destroy für den Stammknoten eines Modells aufgerufen wird, das von RenderingSession.Connection.LoadModelAsync() oder dessen SAS-Variante RenderingSession.Connection.LoadModelFromSasAsync() zurückgegeben wird.

Entitäten werden erstellt, wenn der Server Inhalte lädt oder der Benutzer der Szene ein Objekt hinzufügen möchte. Wenn ein Benutzer beispielsweise eine Schnittebene hinzufügen möchte, um das Innere eines Gittermodells visuell darzustellen, kann der Benutzer eine Entität erstellen, in der die Ebene vorhanden sein sollte, und ihr dann die Schnittebenenkomponente hinzufügen.

Entität erstellen

Wenn Sie der Szene eine neue Entität hinzufügen möchten, z. B. um sie als Stammobjekt zum Laden von Modellen oder zum Anfügen von Komponenten zu übergeben, verwenden Sie den folgenden 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;
}

Abfragefunktionen

Es gibt zwei Arten von Abfragefunktionen für Entitäten: synchrone und asynchrone Aufrufe. Synchrone Abfragen können nur für Daten verwendet werden, die auf dem Client vorhanden sind und keine große Berechnung erfordern. Beispiele sind Abfragen für Komponenten, relative Objekttransformationen oder Beziehungen zwischen übergeordneten und untergeordneten Elementen. Asynchrone Abfragen werden für Daten verwendet, die nur auf dem Server vorhanden sind oder zusätzliche Berechnungen erfordern, deren Ausführung auf dem Client zu teuer ist. Beispiele hierfür sind Abfragen für räumliche Begrenzungen oder Metadatenabfragen.

Abfragen von Komponenten

Um eine Komponente eines bestimmten Typs zu suchen, verwenden Sie 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>();

Abfragen von Transformationen

Transformationsabfragen sind synchrone Aufrufe für das Objekt. Es ist wichtig zu beachten, dass transformationen, die auf der API-Seite gespeichert sind, lokale Raumtransformationen relativ zum übergeordneten Objekt sind. Ausnahmen sind Stammobjekte, für die der lokale Raum und der allgemeine Raum identisch sind.

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

Falls alle Strukturtransformationskomponenten (Position, Drehung und Skalierung) gleichzeitig abgerufen oder festgelegt werden müssen, empfiehlt es sich, die Eigenschaft der Entität LocalTransform zu verwenden:

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

Es gibt auch eine Hilfsfunktion zum Abrufen der globalen Transformation (Weltraum) einer Entität:

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

Wenn GlobalTransform die globale Transformation aufgerufen wird, wird die globale Transformation direkt berechnet, indem die Entitätshierarchie durchlaufen wird. Diese Durchquerung umfasst eine erhebliche Berechnung, aber im Vergleich zu den gleichen Vorgängen auf der Clientseite über die Klasse Entityist die integrierte Funktion schneller. Dennoch könnte das Aufrufen GlobalTransform einer größeren Gruppe von Entitäten einen Leistungsengpässe auferlegen.

LocalToGlobalMatrix ist eine Variante davon GlobalTransform , die die globale Transformation als Matrix berechnet, die im Kontext von Unity praktisch ist:

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

Abfragen räumlicher Begrenzungen

Begrenzungsabfragen sind asynchrone Aufrufe, die für eine vollständige Objekthierarchie ausgeführt werden und eine Entität als Stamm verwenden. Weitere Informationen finden Sie im speziellen Kapitel zu Objektbegrenzungen.

Abfragen von Metadaten

Metadaten sind zusätzliche Daten, die auf Objekten gespeichert sind, die vom Server ignoriert werden. Objektmetadaten sind im Wesentlichen ein Satz aus Name-Wert-Paaren, wobei der Wert vom Typ „numeric“ (numerisch), „boolean“ (boolesch) oder „string“ (Zeichenfolge) sein kann. Metadaten können mit dem Modell exportiert werden.

Metadatenabfragen sind asynchrone Aufrufe für eine bestimmte Entität. Die Abfrage gibt nur die Metadaten einer einzelnen Entität zurück, nicht die zusammengeführten Informationen eines Untergraphen.

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

        // ...
    }
});

Die Abfrage ist erfolgreich, auch wenn das Objekt keine Metadaten enthält.

API-Dokumentation

Nächste Schritte