Entidades

Artigo
10/26/2023

Uma Entidade representa um objeto móvel no espaço e é o bloco de construção fundamental do conteúdo renderizado remotamente.

Propriedades da entidade

As entidades têm uma transformação definida por uma posição, rotação e escala. Por si só, as entidades não têm qualquer funcionalidade observável. Em vez disso, o comportamento é adicionado por meio de componentes, que são anexados a entidades. Por exemplo, anexar um CutPlaneComponent cria um plano de corte na posição da entidade.

O aspeto mais importante da própria entidade é a hierarquia e a transformação hierárquica resultante. Por exemplo, quando várias entidades são anexadas como filhos a uma entidade pai compartilhada, todas essas entidades podem ser movidas, giradas e dimensionadas em uníssono alterando a transformação da entidade pai. Além disso, o estado da enabled entidade pode ser usado para desativar a visibilidade e as respostas a ray casts para um subgráfico completo na hierarquia.

Uma entidade é de propriedade exclusiva de sua empresa-mãe, o que significa que, quando a controladora é destruída com Entity.Destroy(), seus filhos e todos os componentes conectados também são. Assim, a remoção de um modelo da cena é realizada chamando Destroy o nó raiz de um modelo, retornado por RenderingSession.Connection.LoadModelAsync() ou sua variante RenderingSession.Connection.LoadModelFromSasAsync()SAS.

As entidades são criadas quando o servidor carrega conteúdo ou quando o usuário deseja adicionar um objeto à cena. Por exemplo, se um usuário quiser adicionar um plano de corte para visualizar o interior de uma malha, o usuário pode criar uma entidade onde o plano deve existir e, em seguida, adicionar o componente de plano de corte a ele.

Criar uma entidade

Para adicionar uma nova entidade à cena, por exemplo, para passá-la como um objeto raiz para carregar modelos ou anexar componentes a ela, use o seguinte código:

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

Funções de consulta

Existem dois tipos de funções de consulta em entidades: chamadas síncronas e assíncronas. As consultas síncronas só podem ser usadas para dados que estão presentes no cliente e não envolvem muita computação. Exemplos são a consulta de componentes, transformações de objeto relativas ou relações pai/filho. As consultas assíncronas são usadas para dados que residem apenas no servidor ou envolvem computação extra que seria muito cara para ser executada no cliente. Exemplos são consultas de limites espaciais ou consultas de metadados.

Consultando componentes

Para localizar um componente de um tipo específico, use 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>();

Consultando transformações

As consultas de transformação são chamadas síncronas no objeto. É importante observar que as transformações armazenadas no lado da API são transformações de espaço local, relativas ao pai do objeto. As exceções são objetos raiz, para os quais o espaço local e o espaço mundial são idênticos.

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

Caso todos os componentes da transformação em árvore (posição, rotação e escala) precisem ser recuperados ou definidos simultaneamente, recomenda-se usar a propriedade da LocalTransform entidade:

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

Há também uma função auxiliar para recuperar a transformação global (espaço mundial) de uma entidade:

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

Quando GlobalTransform é chamada, a transformação global é calculada em tempo real, percorrendo a hierarquia da entidade. Esta travessia envolve computação significativa, mas em comparação com fazer as mesmas operações no lado do cliente através da classe Entity, a função integrada é mais rápida. Ainda assim, recorrer a GlobalTransform um conjunto maior de entidades pode impor um estrangulamento de desempenho.

LocalToGlobalMatrix é uma variante que GlobalTransform calcula a transformação global como uma matriz, o que é conveniente no contexto da Unidade:

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

Consultando limites espaciais

As consultas de limites são chamadas assíncronas que operam em uma hierarquia de objetos completa, usando uma entidade como raiz. Consulte o capítulo dedicado sobre limites de objetos.

Consultando metadados

Metadados são dados extras armazenados em objetos que são ignorados pelo servidor. Os metadados do objeto são essencialmente um conjunto de pares (nome, valor), onde o valor pode ser do tipo numérico, booleano ou string. Os metadados podem ser exportados com o modelo.

As consultas de metadados são chamadas assíncronas em uma entidade específica. A consulta retorna apenas os metadados de uma única entidade, não as informações mescladas de um subgráfico.

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

        // ...
    }
});

A consulta será bem-sucedida mesmo se o objeto não contiver metadados.