實體

發行項
10/26/2023

實體代表空間中的可移動物件，是遠端轉譯內容的基本建置組塊。

實體屬性

實體具有位置、旋轉和縮放比例所定義的轉換。本身的實體沒有任何可觀察的功能。相反地，行為會透過附加至實體的元件來新增。例如，附加 CutPlaneComponent 會在實體的位置建立剪下平面。

實體本身最重要的層面是階層和產生的階層式轉換。例如，當多個實體附加為共用父實體的子系時，這些實體都可以藉由變更父實體的轉換，以一致方式移動、旋轉和縮放。此外，實體 enabled 的狀態可以用來關閉階層中完整子圖形之光線轉換的可見度和回應。

實體是由其父系獨一無二的，這表示當父系被終結 Entity.Destroy() 時，其子系和所有連接的元件也是如此。因此，從場景移除模型是藉由呼叫 Destroy 模型根節點，或由或其 SAS 變體 RenderingSession.Connection.LoadModelFromSasAsync() 傳回 RenderingSession.Connection.LoadModelAsync() 來完成。

當伺服器載入內容或使用者想要將物件新增至場景時，就會建立實體。例如，如果使用者想要新增切割平面來視覺化網格的內部，使用者可以建立平面應該存在的實體，然後將切割平面元件加入其中。

建立實體

若要將新實體新增至場景，例如，若要將它當做根物件傳遞，以載入模型或附加元件至場景，請使用下列程式碼：

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

查詢函式

實體上有兩種類型的查詢函式：同步和非同步呼叫。同步查詢只能用於用戶端上存在的資料，而且不會牽涉到太多計算。範例包括查詢元件、相對物件轉換或父/子關聯性。非同步查詢用於只位於伺服器上的資料，或牽涉到在用戶端上執行的成本太高的額外計算。範例包括空間界限查詢或中繼資料查詢。

查詢元件

若要尋找特定類型的元件，請使用 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>();

查詢轉換

轉換查詢是物件上的同步呼叫。請務必注意，儲存在 API 端的轉換是相對於物件父系的本機空間轉換。例外狀況是根物件，其中本機空間和世界空間相同。

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

如果所有樹狀結構轉換元件（位置、旋轉和縮放比例）都必須同時擷取或設定，建議您使用實體的 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;

還有協助程式函式可擷取實體的全域（世界空間）轉換：

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

呼叫時 GlobalTransform ，會透過周遊實體階層來即時計算全域轉換。此周遊牽涉到大量計算，但相較于透過類別 Entity 在用戶端上執行相同作業，內建函式的速度較快。不過，呼叫 GlobalTransform 一組較大的實體可能會造成效能瓶頸。

LocalToGlobalMatrix 是的 GlobalTransform 變體，會將全域轉換計算為矩陣，這在 Unity 的內容中很方便：

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

查詢空間界限

界限查詢是在完整物件階層上運作的非同步呼叫，使用一個實體做為根目錄。請參閱有關物件界限的專用章節。

查詢中繼資料

中繼資料是儲存在伺服器忽略之物件上的額外資料。物件中繼資料基本上是一組（name， value）組，其中 value 可以是數值、布林值或字串類型。中繼資料可以使用模型匯出。

中繼資料查詢是特定實體上的非同步呼叫。查詢只會傳回單一實體的中繼資料，而不是子圖形的合併資訊。

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

        // ...
    }
});

即使物件未保存任何中繼資料，查詢仍會成功。

實體