Partilhar via


Class Entity

An entity represents an object in space.

Entities have a transform, meaning a position, rotation and scale. By themselves entities don't have any observable functionality. Instead behavior is added through components (see ComponentBase), which are attached to entities. For instance attaching a MeshComponent will make a mesh appear at the position of the entity.

The most important aspect of the entity itself is the hierarchy and the resulting hierarchical transform. For example, when multiple entities are attached as children to a shared parent entity, all of these entities can be moved, rotated and scaled in unison by changing the transform of the parent entity.

class Microsoft::Azure::RemoteRendering::Entity final : public Microsoft::Azure::RemoteRendering::ObjectBase

Methods

Destroy

Destroys the entity.

Destroying an entity will also destroy all of its components and child entities. Once Destroy() has been called, Entity.Valid returns false.

auto Destroy() noexcept -> Microsoft::Azure::RemoteRendering::Status;

See also

FindByPath

Returns a list of entities that are under this entity and that match the exact search path. A path is a sequence of entity names, separated by a special path delimiter character/string. For instance, a path string could be "house/table/leg4". In that example, this function would search for direct child entities named "house", from there recursively search for child entities named "table" and so on. It only returns those entities that match the full path.

The path separator should be chosen carefully, so it's not a potential character sequence in entity names.

auto FindByPath(std::string const& path, Microsoft::Azure::RemoteRendering::StringComparison comparison, std::string const& pathSeparator, int32_t maxResultCount, std::vector<ApiHandle<Microsoft::Azure::RemoteRendering::Entity>> & out) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Parameters

Name Type Description
path string The path string relative to this entity. The path separator character/string can be passed separately.
comparison StringComparison A pre-defined string comparison method to compare each path segment against an entity's name. See .
pathSeparator string A single character (or non-empty string) that denotes a delimiter in the path string. For instance, use "/" or "".
maxResultCount int The maximum number of entities to find. Use 1 to return the first result only, or a negative number for all results.

Returns

Type Description
System.Collections.Generic.IReadOnlyList<Microsoft.Azure.RemoteRendering.Entity> The list of result entities that match the input path.

FindComponentOfType

Tries to find a component of the given type that is attached to this entity.

Only one instance of each component type can be attached to each entity. Therefore this function either returns a single result, or null, if none is found. If you need to search the full entity sub-tree for components, use the Entity.FindComponentsOfTypeInHierarchy(ObjectType,System.Int32) function.

auto FindComponentOfType(Microsoft::Azure::RemoteRendering::ObjectType type) noexcept -> Expected<ApiHandle<Microsoft::Azure::RemoteRendering::ComponentBase>, Microsoft::Azure::RemoteRendering::Status>;

Parameters

Name Type Description
type ObjectType Component type to search for, for instance .

Returns

Type Description
ComponentBase

FindComponentsOfTypeInHierarchy

Traverses the entity's sub graph (including this entity) and returns a list of all components of certain type found in the graph.

If you only need the first result, then maxResultCount should be set to 1, so the search function can return early.

auto FindComponentsOfTypeInHierarchy(Microsoft::Azure::RemoteRendering::ObjectType type, int32_t maxResultCount, std::vector<ApiHandle<Microsoft::Azure::RemoteRendering::ComponentBase>> & out) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Parameters

Name Type Description
type ObjectType The component type to search for, for instance .
maxResultCount int If larger than 0, this value specifies the maximum number of returned elements. For negative values or 0, no size limit is imposed.

Returns

Type Description
System.Collections.Generic.IReadOnlyList<Microsoft.Azure.RemoteRendering.ComponentBase> The array of found elements, or an empty array.

FindEntitiesByNameInHierarchy

Traverses the entity's sub graph (including this entity) and returns a list of entities that have a matching name.

If you only need the first result, then maxResultCount should be set to 1, so the search function can return early.

auto FindEntitiesByNameInHierarchy(std::string const& name, Microsoft::Azure::RemoteRendering::StringComparison comparison, int32_t maxResultCount, std::vector<ApiHandle<Microsoft::Azure::RemoteRendering::Entity>> & out) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Parameters

Name Type Description
name string The name to compare against.
comparison StringComparison A pre-defined string comparison method, see .
maxResultCount int If larger than 0, this value specifies the maximum number of returned elements. For negative values or 0, no size limit is imposed.

Returns

Type Description
System.Collections.Generic.IReadOnlyList<Microsoft.Azure.RemoteRendering.Entity> The array of found elements, or an empty array.

GetRootPath

Returns the path string to this entity, starting at the root entity. A path is a sequence of entity names, separated by a special path delimiter character/string. A possible path may look like this: "root/house/table/leg4".

The path separator should be chosen carefully, so it's not a potential character sequence in entity names. To describe the relative path between a parent and an entity underneath it, just take the root path of both and trim the start of the path string of the child by the length of the parent's path plus separator length.

auto GetRootPath(std::string const& pathSeparator, std::string & out) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Parameters

Name Type Description
pathSeparator string A single character (or non-empty string) that is inserted between the entity names. For instance, use "/" or "".

Returns

Type Description
string The string that describes the path.

QueryLocalBoundsAsync

Queries the local-space bounding box from the server.

QueryLocalBoundsAsync is an asynchronous call. The computation of the bounds is performed on the server and returned when available.

auto QueryLocalBoundsAsync(std::function<void(Status, Microsoft::Azure::RemoteRendering::Bounds)> callback) -> void;

Parameters

Name Type Description
  • callback

Returns

Type Description
void

QueryMetadataAsync

Queries for any available metadata on a single entity.

auto QueryMetadataAsync(std::function<void(Status, ApiHandle<Microsoft::Azure::RemoteRendering::ObjectMetadata>)> callback) -> void;

Parameters

Name Type Description
  • callback

Returns

Type Description
void

QueryWorldBoundsAsync

Queries the world-space bounding box from the server.

The bounding box represents the volume that this entity, all its child entities, and attached meshes take up.

QueryWorldBoundsAsync is an asynchronous call. The computation of the bounds is performed on the server and returned when available.

auto QueryWorldBoundsAsync(std::function<void(Status, Microsoft::Azure::RemoteRendering::Bounds)> callback) -> void;

Parameters

Name Type Description
  • callback

Returns

Type Description
void

See also

Properties

Children

Read-only list of all the entities that are attached as children to this one.

To make an entity the child of another entity, use the Entity.Parent property.

auto GetChildren(std::vector<ApiHandle<Microsoft::Azure::RemoteRendering::Entity>> & out) const noexcept -> void;

Components

Read-only list of all the components that are attached to this entity.

auto GetComponents(std::vector<ApiHandle<Microsoft::Azure::RemoteRendering::ComponentBase>> & out) const noexcept -> void;

Enabled

Enables or disables the entity and all its components and children.

Disabling an entity is similar to deleting it, except that it can be enabled again easily. All components on a disabled entity are disabled as well, and so are all child entities.

auto GetEnabled() const noexcept -> bool;
auto SetEnabled(bool value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

GlobalTransform

Computes the transform of this entity in global space, as used for rendering.

The client-side API stores only local transform data, so internally this function needs to compute the global position by traversing up the hierarchy. Accordingly, this is a computational intensive function that should only be called when needed for a selected set of entities. However, this function is still much faster than traversing the entity hierarchy manually in client code. There is no way to set the global transform of an entity.

auto GetGlobalTransform() const noexcept -> Microsoft::Azure::RemoteRendering::Transform;

LocalToGlobalMatrix

Similar to Entity.GlobalTransform but converted to a 4x4 matrix.

auto GetLocalToGlobalMatrix() const noexcept -> Microsoft::Azure::RemoteRendering::Matrix4x4;

LocalTransform

Get or set the local transform of this entity. The same can be achieved through getting/setting Entity.Position, Entity.Rotation, and Entity.Scale individually.

A Result.InvalidParam error occurs if the given transform contains any NaN or infinite. If the full local transform needs to be set or be retrieved, Entity.LocalTransform is faster than individual calls to Entity.Position, Entity.Rotation, and Entity.Scale.

auto GetLocalTransform() const noexcept -> Microsoft::Azure::RemoteRendering::Transform;
auto SetLocalTransform(Microsoft::Azure::RemoteRendering::Transform const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Name

Optional name property.

A Result.StringTooLong error occurs if the given string is excessively long.

auto GetName(std::string & out) const noexcept -> void;
auto SetName(std::string const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Parent

The entity that acts as this entity's parent.

Top level entities don't have a parent, in which case this returns null. Setting a new parent automatically adds this entity to the list of children of the provided parent.

auto GetParent() const noexcept -> ApiHandle<Microsoft::Azure::RemoteRendering::Entity>;
auto SetParent(ApiHandle<Microsoft::Azure::RemoteRendering::Entity> const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Position

Position, relative to the parent node.

A Result.InvalidParam error occurs if the given value is NaN or infinite. If the full local transform needs to be set or be retrieved, Entity.LocalTransform is faster than individual calls to Entity.Position, Entity.Rotation, and Entity.Scale.

auto GetPosition() const noexcept -> Microsoft::Azure::RemoteRendering::Double3;
auto SetPosition(Microsoft::Azure::RemoteRendering::Double3 const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Root

The topmost parent entity in this hierarchy. If this entity is a root entity itself (i.e. Entity.Parent is invalid) then this returns this entity.

auto GetRoot() const noexcept -> ApiHandle<Microsoft::Azure::RemoteRendering::Entity>;

Rotation

Rotation, relative to the parent node.

A Result.InvalidParam error occurs if the given value is NaN or infinite. If the full local transform needs to be set or be retrieved, Entity.LocalTransform is faster than individual calls to Entity.Position, Entity.Rotation, and Entity.Scale.

auto GetRotation() const noexcept -> Microsoft::Azure::RemoteRendering::Quaternion;
auto SetRotation(Microsoft::Azure::RemoteRendering::Quaternion const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Scale

Scale, relative to the parent node.

A Result.InvalidParam error occurs if the given value is NaN or infinite. If the full local transform needs to be set or be retrieved, Entity.LocalTransform is faster than individual calls to Entity.Position, Entity.Rotation, and Entity.Scale.

auto GetScale() const noexcept -> Microsoft::Azure::RemoteRendering::Float3;
auto SetScale(Microsoft::Azure::RemoteRendering::Float3 const& value) noexcept -> Microsoft::Azure::RemoteRendering::Status;

Static

Indicates whether this object originates from a model conversion that used the 'SceneGraphMode=static' parameter for conversion. These objects cannot be transformed individually or re-parented. Calling transform or re-parenting on a static object will return the 'ObjectStatic' error code.

auto GetStatic() const noexcept -> bool;

Type

The exact type of this object.

auto GetType() const noexcept -> Microsoft::Azure::RemoteRendering::ObjectType;

Valid

Whether this entity is still valid.

An entity is invalid if it has been destroyed or if the connection has been lost. It is an error to call any other function on an invalid object.

auto GetValid() const noexcept -> bool;

See also