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.
- A Result.NoConnection error occurs no connection was found.
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.
- A Result.NoConnection error occurs if no connection was found.
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.
- A Result.NoConnection error occurs no connection was found.
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.
- A Result.CyclicReference error occurs, if the new parent is a descendant of this object.
- A Result.InvalidId error occurs, if an invalid entity is set as the 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;