Entidades

  • Artículo

Una entidad representa un objeto movible en el espacio y es el bloque de creación fundamental del contenido representado de forma remota.

Propiedades de entidad

Las entidades tienen una transformación definida por una posición, rotación y escala. Por sí mismas, las entidades no tienen ninguna funcionalidad observable. En su lugar, el comportamiento se agrega a través de los componentes, que están asociados a las entidades. Por ejemplo, al adjuntar un CutPlaneComponent se crea un plano de corte en la posición de la entidad.

El aspecto más importante de la propia entidad es la jerarquía y la transformación jerárquica resultante. Por ejemplo, cuando se asocian varias entidades como elementos secundarios a una entidad primaria compartida, todas estas entidades se pueden mover, girar y reducir horizontalmente al unísono cambiando la transformación de la entidad primaria. Además, se puede usar el estado enabled de la entidad para desactivar la visibilidad y las respuestas para las proyecciones de rayo de un subgráfico completo de la jerarquía.

Una entidad es propiedad exclusiva de su elemento primario, lo que significa que cuando el elemento primario se destruye con Entity.Destroy(), lo mismo ocurre con sus elementos secundarios y todos los componentes conectados. Por lo tanto, para quitar un modelo de la escena se realiza una llamada a Destroy en el nodo raíz de un modelo, devuelto por RenderingSession.Connection.LoadModelAsync() o su variante RenderingSession.Connection.LoadModelFromSasAsync() de SAS.

Las entidades se crean cuando el servidor carga el contenido o cuando el usuario desea agregar un objeto a la escena. Por ejemplo, si un usuario desea agregar un plano de corte para visualizar el interior de una malla, el usuario puede crear una entidad donde debe existir el plano y, a continuación, agregarle el componente de plano de corte.

Crear una entidad

Para agregar una nueva entidad a la escena, por ejemplo, para pasarla como un objeto raíz para cargar modelos o adjuntar componentes a ella, use el código siguiente:

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

Funciones de consulta

Hay dos tipos de funciones de consulta en entidades: llamadas sincrónicas y asincrónicas. Las consultas sincrónicas solo se pueden usar para los datos que están presentes en el cliente y no implican mucho cálculo. Algunos ejemplos son las consultas de componentes, las transformaciones de objetos relativos o las relaciones de elementos primarios y secundarios. Las consultas asincrónicas se utilizan para los datos que solo residen en el servidor o implican cálculos adicionales cuya ejecución resultaría demasiado cara en el cliente. Algunos ejemplos son las consultas de límites espaciales o las consultas de metadatos.

Consulta de componentes

Para buscar un componente de un 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>();

Consulta de transformaciones

Las consultas de transformación son llamadas sincrónicas en el objeto. Es importante tener en cuenta que las transformaciones almacenadas en la API son transformaciones de espacio local, en relación con el elemento primario del objeto. Las excepciones son objetos raíz, para los que el espacio local y el espacio global son 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();

En caso de que todos los componentes de transformación de árbol (posición, rotación y escala) se recuperen o establezcan simultáneamente, se recomienda usar la propiedad de LocalTransform la entidad:

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

También hay una función auxiliar para recuperar la transformación global (espacio mundial) de una entidad:

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

Cuando GlobalTransform se llama a , la transformación global se calcula sobre la marcha cruzando la jerarquía de entidades. Este recorrido implica un cálculo significativo, pero en comparación con realizar las mismas operaciones en el lado cliente a través de la clase Entity, la función integrada es más rápida. Aun así, llamar a GlobalTransform en un conjunto mayor de entidades podría imponer un cuello de botella de rendimiento.

LocalToGlobalMatrix es una variante de GlobalTransform que calcula la transformación global como una matriz, que es conveniente en el contexto de Unity:

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

Consulta de enlaces espaciales

Las consultas de límites son llamadas asincrónicas que operan en una jerarquía de objetos completa, utilizando una entidad como raíz. Vea el capítulo dedicado acerca de los Límites de objetos.

Consulta de metadatos

Los metadatos son datos adicionales almacenados en objetos que el servidor omite. Los metadatos de objeto son básicamente un conjunto de pares (nombre, valor), donde el valor puede ser de tipo numérico, booleano o de cadena. Los metadatos se pueden exportar con el modelo.

Las consultas de metadatos son llamadas asincrónicas en una entidad específica. La consulta solo devuelve los metadatos de una sola entidad, no la información combinada de un subgrafo.

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

        // ...
    }
});

La consulta se realiza correctamente incluso si el objeto no contiene ningún metadato.

Documentación de la API

Pasos siguientes