エンティティ

エンティティとは、領域内の移動可能なオブジェクトを表すもので、リモートでレンダリングされるコンテンツの基本的な構成要素です。

エンティティのプロパティ

エンティティには、位置、回転、および拡大縮小によって定義された変換機能があります。 それら単独では注目すべき機能はありません。 代わりに、エンティティにアタッチされるコンポーネントによって動作が追加されます。 たとえば、CutPlaneComponent をアタッチすると、エンティティの位置に切断面が作成されます。

エンティティ自体の最も重要な側面は、階層と、結果として生じる階層の変換です。 たとえば、共有されている 1 つの親エンティティに複数のエンティティが子としてアタッチされている場合、親エンティティの変換を変更することによって、これらのエンティティをすべて同時に移動、回転、および拡大縮小することができます。 また、エンティティの enabled 状態を使用して、階層内のサブ グラフ全体でレイ キャストへの応答と可視性を無効にできます。

エンティティはその親によって一意に所有されます。つまり、親が Entity.Destroy() で破棄されると、その子と、接続されているすべてのコンポーネントも破棄されます。 したがって、シーンからモデルを削除するには、RenderingSession.Connection.LoadModelAsync() またはその SAS バリアント RenderingSession.Connection.LoadModelFromSasAsync() によって返される、モデルのルート ノードに対して Destroy を呼び出します。

エンティティは、サーバーがコンテンツを読み込むとき、またはユーザーがオブジェクトをシーンに追加するときに作成されます。 たとえば、ユーザーがメッシュの内部を視覚化するために切断面を追加する場合は、その面が存在するはずのエンティティを作成して、それに切断面コンポーネントを追加できます。

エンティティの作成

シーンに新しいエンティティを追加する (たとえば、それをルート オブジェクトとして渡し、モデルを読み込むか、コンポーネントをアタッチする) には、次のコードを使用します。

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

クエリ関数

エンティティには、同期呼び出しと非同期呼び出しの 2 種類のクエリ関数があります。 同期クエリは、クライアント上に存在し、計算をあまり伴わないデータにのみ使用できます。 例として、コンポーネント、オブジェクトの相対変換、または親子関係のクエリがあります。 非同期クエリは、サーバー上に存在し、クライアントで実行するにはコストがかかりすぎる追加の計算を伴うデータにのみ使用されます。 例として、空間境界のクエリやメタデータの クエリがあります。

コンポーネントのクエリ

特定の種類のコンポーネントを検索するには、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);

空間境界のクエリ

境界のクエリは、1 つのエンティティをルートとして使用して、完全なオブジェクト階層で機能する非同期呼び出しです。 オブジェクトの境界に関する専用の章をご覧ください。

メタデータのクエリ

メタデータは、オブジェクトに格納されている追加データであり、サーバーによって無視されます。 オブジェクトのメタデータは、基本的に (名前と値の) ペアのセットです。値 には、数値型、ブール型、または文字列型を指定できます。 メタデータは、モデルと共にエクスポートできます。

メタデータのクエリは、特定のエンティティに対する非同期呼び出しです。 このクエリは、サブ グラフのマージされた情報ではなく、単一エンティティのメタデータのみを返します。

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

        // ...
    }
});

オブジェクトがメタデータを保持していない場合でも、クエリは成功します。

API ドキュメント

• C# Entity クラス
• C# RenderingConnection.CreateEntity()
• C++ Entity クラス
• C++ RenderingConnection::CreateEntity()

次のステップ

• コンポーネント
• オブジェクトの境界