Jednostki

Jednostka reprezentuje obiekt wymienny w przestrzeni i jest podstawowym blokiem konstrukcyjnym zawartości renderowanej zdalnie.

Właściwości jednostki

Jednostki mają transformację zdefiniowaną przez położenie, rotację i skalę. Same jednostki nie mają żadnych zauważalnych funkcji. Zamiast tego zachowanie jest dodawane za pośrednictwem składników, które są dołączone do jednostek. Na przykład dołączenie elementu CutPlaneComponent spowoduje utworzenie płaszczyzny wycinania na pozycji jednostki.

Najważniejszym aspektem samej jednostki jest hierarchia i wynikowa transformacja hierarchiczna. Jeśli na przykład wiele jednostek jest dołączonych jako elementy podrzędne do udostępnionej jednostki nadrzędnej, wszystkie te jednostki można przenosić, obracać i skalować w sposób jednoszonowy, zmieniając przekształcenie jednostki nadrzędnej. Ponadto stan jednostki enabled może służyć do wyłączania widoczności i odpowiedzi na rzutowania promieni dla pełnego wykresu podrzędnego w hierarchii.

Jednostka jest unikatowo własnością jej elementu nadrzędnego, co oznacza, że gdy element nadrzędny zostanie zniszczony z elementem , są więc jego elementami Entity.Destroy()podrzędnymi i wszystkimi połączonymi składnikami. W związku z tym usunięcie modelu ze sceny odbywa się przez wywołanie Destroy węzła głównego modelu, zwróconego przez RenderingSession.Connection.LoadModelAsync() lub jego wariant RenderingSession.Connection.LoadModelFromSasAsync()SAS.

Jednostki są tworzone, gdy serwer ładuje zawartość lub gdy użytkownik chce dodać obiekt do sceny. Jeśli na przykład użytkownik chce dodać płaszczyznę wycinania w celu wizualizacji wnętrza siatki, użytkownik może utworzyć jednostkę, w której powinna istnieć płaszczyzna, a następnie dodać do niej składnik płaszczyzny wycinania.

Tworzenie jednostki

Aby dodać nową jednostkę do sceny, na przykład przekazać ją jako obiekt główny do ładowania modeli lub dołączyć do niego składniki, użyj następującego kodu:

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

Funkcje zapytań

Istnieją dwa typy funkcji zapytań dla jednostek: synchroniczne i asynchroniczne wywołania. Zapytania synchroniczne mogą być używane tylko w przypadku danych obecnych na kliencie i nie wymagają dużej ilości obliczeń. Przykładami są zapytania dotyczące składników, przekształceń obiektów względnych lub relacji nadrzędnych/podrzędnych. Zapytania asynchroniczne są używane w przypadku danych, które znajdują się tylko na serwerze lub obejmują dodatkowe obliczenia, które byłyby zbyt kosztowne do uruchomienia na kliencie. Przykłady to zapytania dotyczące granic przestrzennych lub zapytania dotyczące metadanych.

Wykonywanie zapytań dotyczących składników

Aby znaleźć składnik określonego typu, użyj polecenia 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>();

Wykonywanie zapytań dotyczących przekształceń

Zapytania przekształcania to synchroniczne wywołania obiektu. Należy pamiętać, że przekształcenia zapytane za pośrednictwem interfejsu API to przekształcenia przestrzeni lokalnej względem elementu nadrzędnego obiektu. Wyjątki to obiekty główne, dla których przestrzeń lokalna i przestrzeń światowa są identyczne.

Uwaga

Nie ma dedykowanego interfejsu API do wykonywania zapytań dotyczących transformacji przestrzeni świata dowolnych obiektów.

// local space transform of the entity
Double3 translation = entity.Position;
Quaternion rotation = entity.Rotation;
// local space transform of the entity
Double3 translation = entity->GetPosition();
Quaternion rotation = entity->GetRotation();

Wykonywanie zapytań dotyczących granic przestrzennych

Zapytania dotyczące granic to asynchroniczne wywołania, które działają w pełnej hierarchii obiektów przy użyciu jednej jednostki jako katalogu głównego. Zobacz dedykowany rozdział dotyczący granic obiektów.

Wykonywanie zapytań dotyczących metadanych

Metadane są dodatkowymi danymi przechowywanymi w obiektach, które są ignorowane przez serwer. Metadane obiektu to zasadniczo zestaw par (nazwa, wartość), w których wartość może być typu liczbowego, logicznego lub ciągu. Metadane można wyeksportować za pomocą modelu.

Zapytania metadanych to asynchroniczne wywołania określonej jednostki. Zapytanie zwraca tylko metadane pojedynczej jednostki, a nie scalone informacje o wykresie podrzędnym.

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

        // ...
    }
});

Zapytanie powiedzie się, nawet jeśli obiekt nie przechowuje żadnych metadanych.

Dokumentacja interfejsu API

Następne kroki