EntityView#
Fully qualified name: isaacsim::physics::tensors::EntityView
-
class EntityView : public isaacsim::physics::tensors::IEntityView#
Dispatches named tensor operations for an engine-specific collection of physics entities.
Engine implementations register read, write, and metadata callbacks together with tensor specifications. Consumers discover the registered operations by name and invoke them through the uniform data-access methods. The view stores callback objects by value.
Registration accepts empty callback objects. Invoking an empty registered callback throws
std::bad_function_call. Other exceptions raised by provider callbacks propagate to the caller.Public Functions
-
EntityView()#
Constructs an entity view without path patterns.
-
explicit EntityView(std::vector<std::string> primPathPatterns)#
Constructs an entity view from prim-path patterns.
- Parameters:
primPathPatterns – [in] Prim-path patterns or explicit prim paths represented by the view.
-
~EntityView() override#
Destroys the entity view and its registered callbacks.
-
EntityView(const EntityView&) = delete#
Entity views cannot be copied.
-
EntityView &operator=(const EntityView&) = delete#
Entity views cannot be copy-assigned.
- bool registerImplementation(
- const std::string &operationName,
- ImplementationKind kind,
- GetImplementationFunction callback,
- TensorSpecification specification,
Registers a single-buffer read operation.
Registering the same name and operation kind again replaces the existing callback and specification. A read operation name cannot be registered as both single-buffer and multi-buffer.
- Parameters:
operationName – [in] Name used to discover and invoke the operation.
kind – [in] Operation kind, which must be
ImplementationKind::eGet.callback – [in] Read callback to store.
specification – [in] Tensor capabilities and layout advertised by the callback.
- Throws:
std::invalid_argument – If
kindis notImplementationKind::eGetoroperationNameis already registered as a multi-buffer read operation.- Returns:
truefor a new registration;falsewhen an existing registration was replaced.
- bool registerImplementation(
- const std::string &operationName,
- ImplementationKind kind,
- SetImplementationFunction callback,
- TensorSpecification specification,
Registers a single-buffer write operation.
Registering the same name and operation kind again replaces the existing callback and specification. A write operation name cannot be registered as both single-buffer and multi-buffer.
- Parameters:
operationName – [in] Name used to discover and invoke the operation.
kind – [in] Operation kind, which must be
ImplementationKind::eSet.callback – [in] Write callback to store.
specification – [in] Tensor capabilities and layout advertised by the callback.
- Throws:
std::invalid_argument – If
kindis notImplementationKind::eSetoroperationNameis already registered as a multi-buffer write operation.- Returns:
truefor a new registration;falsewhen an existing registration was replaced.
- bool registerImplementation(
- const std::string &operationName,
- ImplementationKind kind,
- GetMultiImplementationFunction callback,
- TensorSpecification specification,
Registers a multi-buffer read operation with one aggregate specification.
Registering the same name and operation kind again replaces the existing callback and specification. A read operation name cannot be registered as both single-buffer and multi-buffer.
- Parameters:
operationName – [in] Name used to discover and invoke the operation.
kind – [in] Operation kind, which must be
ImplementationKind::eGet.callback – [in] Multi-buffer read callback to store.
specification – [in] Aggregate tensor capabilities advertised by the callback.
- Throws:
std::invalid_argument – If
kindis notImplementationKind::eGetoroperationNameis already registered as a single-buffer read operation.- Returns:
truefor a new registration;falsewhen an existing registration was replaced.
- bool registerImplementation(
- const std::string &operationName,
- ImplementationKind kind,
- SetMultiImplementationFunction callback,
- TensorSpecification specification,
Registers a multi-buffer write operation.
Registering the same name and operation kind again replaces the existing callback and specification. A write operation name cannot be registered as both single-buffer and multi-buffer.
- Parameters:
operationName – [in] Name used to discover and invoke the operation.
kind – [in] Operation kind, which must be
ImplementationKind::eSet.callback – [in] Multi-buffer write callback to store.
specification – [in] Aggregate tensor capabilities advertised by the callback.
- Throws:
std::invalid_argument – If
kindis notImplementationKind::eSetoroperationNameis already registered as a single-buffer write operation.- Returns:
truefor a new registration;falsewhen an existing registration was replaced.
- bool registerMetadata(
- const std::string &operationName,
- MetadataImplementationFunction callback,
Registers a metadata provider.
- Parameters:
operationName – [in] Name used to retrieve the metadata.
callback – [in] Metadata callback to store.
- Returns:
truefor a new registration;falsewhen an existing callback was replaced.
- bool registerImplementation(
- const std::string &operationName,
- ImplementationKind kind,
- GetMultiImplementationFunction callback,
- std::vector<TensorSpecification> outputSpecifications,
Registers a multi-buffer read operation with a specification for each output.
The first output specification supplies the aggregate support, data type, shape, indexed-read, and host-data properties used to gate the operation. Registering the same name again replaces the existing multi-buffer read callback and specifications. An empty
outputSpecificationsvector registers the operation with aggregatesupportsset tofalse.- Parameters:
operationName – [in] Name used to discover and invoke the operation.
kind – [in] Operation kind, which must be
ImplementationKind::eGet.callback – [in] Multi-buffer read callback to store.
outputSpecifications – [in] Tensor specification for each returned buffer.
- Throws:
std::invalid_argument – If
kindis notImplementationKind::eGetoroperationNameis already registered as a single-buffer read operation.- Returns:
truefor a new registration;falsewhen an existing registration was replaced.
- std::vector<std::string> listImplementations(
- ImplementationKind kind,
Lists registered operation names for a read or write kind.
The order of returned names is unspecified. The list includes operations whose tensor specification has
supportsset tofalse.- Parameters:
kind – [in]
ImplementationKind::eGetto list read operations orImplementationKind::eSetto list write operations.- Returns:
Names of registered single-buffer and multi-buffer operations for
kind.
- bool hasImplementation(
- const std::string &operationName,
- ImplementationKind kind,
Checks whether a supported operation is registered.
- Parameters:
operationName – [in] Operation name to query.
kind – [in] Read or write operation kind to query.
- Returns:
trueif the operation is registered and its specification hassupportsset totrue; otherwise,false.
- TensorSpecification getImplementationSpecification(
- const std::string &operationName,
- ImplementationKind kind,
Gets the aggregate tensor specification for an operation.
- Parameters:
operationName – [in] Operation name to query.
kind – [in] Read or write operation kind to query.
- Throws:
std::out_of_range – If no matching operation is registered.
- Returns:
The operation’s tensor specification.
- std::vector<TensorSpecification> getMultiImplementationSpecifications(
- const std::string &operationName,
- ImplementationKind kind,
Gets per-output specifications for a multi-buffer read operation.
- Parameters:
operationName – [in] Operation name to query.
kind – [in] Operation kind, expected to be
ImplementationKind::eGet.
- Returns:
Per-output specifications, or an empty vector if the operation was registered with one aggregate specification, is not a multi-buffer read operation, or is not registered.
-
Metadata getMetadata(const std::string &operationName) const#
Gets metadata from a registered provider.
Note
Exceptions raised by the metadata callback propagate to the caller.
- Parameters:
operationName – [in] Metadata-provider name to query.
- Throws:
std::bad_function_call – If the registered metadata callback is empty.
- Returns:
The provider’s metadata, or a default-constructed
Metadatavalue if no provider is registered.
- TensorDescription getData(
- const std::string &operationName,
- const TensorDescription &indices,
- const TensorDescription &output,
Invokes a registered single-buffer read operation.
Note
Other exceptions raised by the provider callback propagate to the caller.
- Parameters:
operationName – [in] Read-operation name.
indices – [in] Operation-defined selector or query descriptor. An empty descriptor requests all entities only when the registered operation defines that convention.
output – [inout] Optional destination tensor descriptor supplied to the provider. The provider may write to its referenced backing memory but does not modify the descriptor object.
- Throws:
std::out_of_range – If no matching single-buffer read operation is registered.
std::runtime_error – If the operation is registered but not supported by the provider.
std::invalid_argument – If
indicesis nonempty and the operation does not support indexed reads.std::bad_function_call – If the registered provider callback is empty.
- Returns:
Descriptor for the resulting tensor. It may reference storage supplied by
outputor other provider-selected storage. A nonemptykeepAlivemember retains that storage’s owner.
- std::vector<TensorDescription> getDataMulti(
- const std::string &operationName,
- const TensorDescription &indices,
- const std::vector<TensorDescription> &output,
Invokes a registered multi-buffer read operation.
Note
Other exceptions raised by the provider callback propagate to the caller.
- Parameters:
operationName – [in] Read-operation name.
indices – [in] Operation-defined selector or query descriptor. An empty descriptor requests all entities only when the registered operation defines that convention.
output – [inout] Optional destination tensor descriptors supplied to the provider. The provider may write to their referenced backing memory but does not modify the descriptor objects.
- Throws:
std::out_of_range – If no matching multi-buffer read operation is registered.
std::runtime_error – If the operation is registered but not supported by the provider.
std::invalid_argument – If
indicesis nonempty and the operation does not support indexed reads.std::bad_function_call – If the registered provider callback is empty.
- Returns:
Descriptors for the resulting tensors. They may reference storage supplied by
outputor other provider-selected storage. A nonemptykeepAlivemember retains the corresponding storage owner.
- void setData(
- const std::string &operationName,
- const TensorDescription &data,
- const TensorDescription &indices,
Invokes a registered single-buffer write operation.
Note
Other exceptions raised by the provider callback propagate to the caller.
- Parameters:
operationName – [in] Write-operation name.
data – [in] Source tensor descriptor.
indices – [in] Operation-defined selector descriptor. An empty descriptor selects all entities only when the registered operation defines that convention.
- Throws:
std::out_of_range – If no matching single-buffer write operation is registered.
std::runtime_error – If the operation is registered but not supported by the provider.
std::invalid_argument – If
indicesis nonempty and the operation does not support indexed writes.std::bad_function_call – If the registered provider callback is empty.
- void setDataMulti(
- const std::string &operationName,
- const std::vector<TensorDescription> &data,
- const TensorDescription &indices,
Invokes a registered multi-buffer write operation.
Note
Other exceptions raised by the provider callback propagate to the caller.
- Parameters:
operationName – [in] Write-operation name.
data – [in] Source tensor descriptors.
indices – [in] Operation-defined selector descriptor. An empty descriptor selects all entities only when the registered operation defines that convention.
- Throws:
std::out_of_range – If no matching multi-buffer write operation is registered.
std::runtime_error – If the operation is registered but not supported by the provider.
std::invalid_argument – If
indicesis nonempty and the operation does not support indexed writes.std::bad_function_call – If the registered provider callback is empty.
- inline const std::vector<std::string> &getPrimPathPatterns(
Gets the prim-path patterns supplied at construction.
- Returns:
A reference to the stored path patterns. The reference remains valid until a derived class modifies the stored vector or the view is destroyed.
- inline virtual std::vector<std::string> getResolvedPrimPaths(
Gets the prim paths resolved by the engine.
The base implementation returns the construction paths without expanding patterns.
- Returns:
Resolved prim paths, or the original construction paths when the provider does not override this method.
-
inline virtual int64_t getUsdStageId() const noexcept#
Gets the USD stage-cache identifier associated with the view.
- Returns:
The USD stage-cache identifier, or
0if none was set.
-
inline int64_t getEntityCount() const noexcept#
Gets the entity count resolved by the engine.
- Returns:
The resolved entity count.
-
inline void setEntityCount(int64_t count) noexcept#
Sets the number of entities resolved by the engine.
- Parameters:
count – [in] Resolved entity count.
- Pre:
countis nonnegative.
-
inline virtual int getDeviceOrdinal() const noexcept#
Gets the ordinal of the device on which this view’s tensors reside.
Consumers read this on every access rather than caching it, because an engine may select its device after the view is created. An engine that resolves its device later overrides this to report the current one; the base implementation returns the stored value.
- Returns:
The device ordinal, or
-1for host memory.
-
inline void setDeviceOrdinal(int ordinal) noexcept#
Sets the ordinal of the device on which this view’s tensors reside.
- Parameters:
ordinal – [in] Device ordinal, or
-1to indicate host memory.
Protected Functions
- bool _setImplementationOutputShapeHints(
- const std::string &operationName,
- ImplementationKind kind,
- const std::vector<std::vector<int64_t>> &shapeHints,
Rewrites the declared output shapes of a registered multi-buffer read operation.
Engine views whose extent is chosen by the caller keep the declared shapes tracking the buffers they read into. Only the shape hints change; the registered callback is untouched, so this may be called from within that callback.
- Parameters:
operationName – [in] Operation name to update.
kind – [in] Operation kind, expected to be
ImplementationKind::eGet.shapeHints – [in] One shape per registered output, in registration order.
- Throws:
std::invalid_argument – If
shapeHintsdoes not have one entry per registered output.- Returns:
trueif the operation was found and updated;falseif it is not a registered multi-buffer read.
- bool _setImplementationShapeHint(
- const std::string &operationName,
- ImplementationKind kind,
- const std::vector<int64_t> &shapeHint,
Rewrites the declared shape of a registered single-buffer operation.
The single-buffer counterpart of _setImplementationOutputShapeHints, with the same guarantee: only the shape hint changes, so it is safe to call from within the registered callback.
- Parameters:
operationName – [in] Operation name to update.
kind – [in] Operation kind to update.
shapeHint – [in] The replacement shape.
- Returns:
trueif the operation was found and updated;falseif it is not registered forkind.
-
EntityView()#