Gazebo Gazebo

API Reference

6.16.0

The EntityComponentManager constructs, deletes, and returns components and entities. A component can be of any class which inherits from components::BaseComponent. More...

#include <ignition/gazebo/EntityComponentManager.hh>

Public Member Functions

 EntityComponentManager ()
 Constructor. More...
 
 ~EntityComponentManager ()
 Destructor. More...
 
msgs::SerializedState ChangedState () const
 Get a message with the serialized state of all entities and components that are changing in the current iteration. More...
 
void ChangedState (msgs::SerializedStateMap &_state) const
 Get a message with the serialized state of all entities and components that are changing in the current iteration. More...
 
template<typename ... ComponentTypeTs>
std::vector< EntityChildrenByComponents (Entity _parent, const ComponentTypeTs &..._desiredComponents) const
 Get all entities which match the value of all the given components and are immediate children of a given parent entity. For example, the following will return a child of entity parent which has an int component equal to 123, and a string component equal to "name": More...
 
Entity Clone (Entity _entity, Entity _parent, const std::string &_name, bool _allowRename)
 Clone an entity and its components. If the entity has any child entities, they will also be cloned. When cloning entities, the following rules apply: More...
 
template<typename ComponentTypeT >
ComponentTypeT * Component (const ComponentKey &_key)
 Get a mutable component based on a key. More...
 
template<typename ComponentTypeT >
const ComponentTypeT * Component (const ComponentKey &_key) const
 Get a component based on a key. More...
 
template<typename ComponentTypeT >
ComponentTypeT * Component (const Entity _entity)
 Get a mutable component assigned to an entity based on a component type. More...
 
template<typename ComponentTypeT >
const ComponentTypeT * Component (const Entity _entity) const
 Get a component assigned to an entity based on a component type. More...
 
template<typename ComponentTypeT >
std::optional< typename ComponentTypeT::Type > ComponentData (const Entity _entity) const
 Get the data from a component. More...
 
template<typename ComponentTypeT >
ComponentTypeT * ComponentDefault (Entity _entity, const typename ComponentTypeT::Type &_default=typename ComponentTypeT::Type())
 Get a mutable component assigned to an entity based on a component type. If the component doesn't exist, create it and initialize with the given default value. More...
 
gz::sim::ComponentState ComponentState (const Entity _entity, const ComponentTypeId _typeId) const
 Get a component's state. More...
 
std::unordered_set< ComponentTypeIdComponentTypes (Entity _entity) const
 Get the type IDs of all components attached to an entity. More...
 
std::unordered_set< ComponentTypeIdComponentTypesWithPeriodicChanges () const
 Get the components types that are marked as periodic changes. More...
 
template<typename ComponentTypeT >
ComponentTypeT * CreateComponent (const Entity _entity, const ComponentTypeT &_data)
 Create a component of a particular type. This will copy the _data parameter. More...
 
Entity CreateEntity ()
 Creates a new Entity. More...
 
std::unordered_set< EntityDescendants (Entity _entity) const
 Get all entities which are descendants of a given entity, including the entity itself. More...
 
template<typename ... ComponentTypeTs>
void Each (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
 Get all entities which contain given component types, as well as the mutable components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call. More...
 
template<typename ... ComponentTypeTs>
void Each (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
 Get all entities which contain given component types, as well as the components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call. More...
 
template<typename... ComponentTypeTs>
void EachNew (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
 Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. More...
 
template<typename... ComponentTypeTs>
void EachNew (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
 Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. This is the const version. More...
 
template<typename ... ComponentTypeTs>
void EachNoCache (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
 A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the mutable components. More...
 
template<typename ... ComponentTypeTs>
void EachNoCache (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
 A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the components. More...
 
template<typename ... ComponentTypeTs>
void EachRemoved (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
 Get all entities which contain given component types and are about to be removed, as well as the components. More...
 
const EntityGraphEntities () const
 Get a graph with all the entities. Entities are vertices and edges point from parent to children. More...
 
template<typename ... ComponentTypeTs>
std::vector< EntityEntitiesByComponents (const ComponentTypeTs &..._desiredComponents) const
 Get all entities which match the value of all the given components. For example, the following will return the entities which have a name component equal to "camera" and a sensor component: More...
 
template<typename ... ComponentTypeTs>
Entity EntityByComponents (const ComponentTypeTs &..._desiredComponents) const
 Get an entity which matches the value of all the given components. For example, the following will return the entity which has a name component equal to "name" and has a model component: More...
 
size_t EntityCount () const
 Get the number of entities on the server. More...
 
bool EntityHasComponent (const Entity _entity, const ComponentKey &_key) const
 Check whether an entity has a specific component. More...
 
bool EntityHasComponentType (const Entity _entity, const ComponentTypeId &_typeId) const
 Check whether an entity has a specific component type. More...
 
bool EntityMatches (Entity _entity, const std::set< ComponentTypeId > &_types) const
 Get whether an entity has all the given component types. More...
 
template<typename ComponentTypeT >
ComponentTypeT * First ()
 The first component instance of the specified type. This function is now deprecated, and will always return nullptr. More...
 
template<typename ComponentTypeT >
const ComponentTypeT * First () const
 The first component instance of the specified type. This function is now deprecated, and will always return nullptr. More...
 
bool HasComponentType (const ComponentTypeId _typeId) const
 Get whether a component type has ever been created. More...
 
bool HasEntitiesMarkedForRemoval () const
 Get whether there are any entities marked to be removed. More...
 
bool HasEntity (const Entity _entity) const
 Get whether an Entity exists. More...
 
bool HasNewEntities () const
 Get whether there are new entities. More...
 
bool HasOneTimeComponentChanges () const
 Get whether there are one-time component changes. These changes do not happen frequently and should be processed immediately. More...
 
bool HasPeriodicComponentChanges () const
 Get whether there are periodic component changes. These changes may happen frequently and are processed periodically. More...
 
bool HasRemovedComponents () const
 Return true if there are components marked for removal. More...
 
Entity ParentEntity (const Entity _entity) const
 Get the first parent of the given entity. More...
 
void PeriodicStateFromCache (msgs::SerializedStateMap &_state, const std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &_cache) const
 Populate a message with relevant changes to the state given a periodic change cache. More...
 
void PinEntity (const Entity _entity, bool _recursive=true)
 Prevent an entity and optionally its children from being removed. More...
 
void RebuildViews ()
 Rebuild all the views. This could be an expensive operation. More...
 
bool RemoveComponent (const Entity _entity, const ComponentKey &_key)
 Remove a component from an entity based on a key. More...
 
bool RemoveComponent (const Entity _entity, const ComponentTypeId &_typeId)
 Remove a component from an entity based on a type id. More...
 
template<typename ComponentTypeT >
bool RemoveComponent (Entity _entity)
 Remove a component from an entity based on a type. More...
 
void RequestRemoveEntities ()
 Request to remove all entities. This will insert the request into a queue. The queue is processed toward the end of a simulation update step. More...
 
void RequestRemoveEntity (const Entity _entity, bool _recursive=true)
 Request an entity deletion. This will insert the request into a queue. The queue is processed toward the end of a simulation update step. More...
 
void SetChanged (const Entity _entity, const ComponentTypeId _type, gz::sim::ComponentState _c=ComponentState::OneTimeChange)
 Set the changed state of a component. More...
 
template<typename ComponentTypeT >
bool SetComponentData (const Entity _entity, const typename ComponentTypeT::Type &_data)
 Set the data from a component. More...
 
void SetEntityCreateOffset (uint64_t _offset)
 All future entities will have an id that starts at _offset. This can be used to avoid entity id collisions, such as during log playback. More...
 
bool SetParentEntity (const Entity _child, const Entity _parent)
 Set the parent of an entity. More...
 
void SetState (const msgs::SerializedState &_stateMsg)
 Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state. More...
 
void SetState (const msgs::SerializedStateMap &_stateMsg)
 Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state. More...
 
msgs::SerializedState State (const std::unordered_set< Entity > &_entities={}, const std::unordered_set< ComponentTypeId > &_types={}) const
 Get a message with the serialized state of the given entities and components. More...
 
void State (msgs::SerializedStateMap &_state, const std::unordered_set< Entity > &_entities={}, const std::unordered_set< ComponentTypeId > &_types={}, bool _full=false) const
 Get a message with the serialized state of the given entities and components. More...
 
void UnpinAllEntities ()
 Allow all previously pinned entities to be removed. More...
 
void UnpinEntity (const Entity _entity, bool _recursive=true)
 Allow an entity, and optionally its children, previously marked as pinned to be removed. More...
 
void UpdatePeriodicChangeCache (std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &) const
 Get a cache of components with periodic changes. More...
 

Static Public Member Functions

template<class Function , class... ComponentTypeTs>
static void ForEach (Function _f, const ComponentTypeTs &... _components)
 Call a function for each parameter in a pack. More...
 

Protected Member Functions

void ClearNewlyCreatedEntities ()
 Clear the list of newly added entities so that a call to EachAdded after this will have no entities to iterate. This function is protected to facilitate testing. More...
 
void ClearRemovedComponents ()
 Clear the list of removed components so that a call to RemoveComponent doesn't make the list grow indefinitely. More...
 
void ProcessRemoveEntityRequests ()
 Process all entity remove requests. This will remove entities and their components. This function is protected to facilitate testing. More...
 
void SetAllComponentsUnchanged ()
 Mark all components as not changed. More...
 

Detailed Description

The EntityComponentManager constructs, deletes, and returns components and entities. A component can be of any class which inherits from components::BaseComponent.

Constructor & Destructor Documentation

◆ EntityComponentManager()

Constructor.

◆ ~EntityComponentManager()

Destructor.

Member Function Documentation

◆ ChangedState() [1/2]

msgs::SerializedState ChangedState ( ) const

Get a message with the serialized state of all entities and components that are changing in the current iteration.

This includes:

  • New entities and all of their components
  • Removed entities and all of their components
  • Entities which had a component added
  • Entities which had a component removed
  • Entities which had a component modified

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

◆ ChangedState() [2/2]

void ChangedState ( msgs::SerializedStateMap _state) const

Get a message with the serialized state of all entities and components that are changing in the current iteration.

This includes:

  • New entities and all of their components
  • Removed entities and all of their components
  • Entities which had a component added
  • Entities which had a component removed
  • Entities which had a component modified
Parameters
[in]_stateNew serialized state.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

◆ ChildrenByComponents()

std::vector<Entity> ChildrenByComponents ( Entity  _parent,
const ComponentTypeTs &...  _desiredComponents 
) const

Get all entities which match the value of all the given components and are immediate children of a given parent entity. For example, the following will return a child of entity parent which has an int component equal to 123, and a string component equal to "name":

auto entity = ChildrenByComponents(parent, 123, std::string("name"));

Component type must have inequality operator.

Parameters
[in]_parentEntity which should be an immediate parent of the returned entity.
[in]_desiredComponentsAll the components which must match.
Returns
All matching entities, or an empty vector if no child entity has the exact components.

◆ ClearNewlyCreatedEntities()

void ClearNewlyCreatedEntities ( )
protected

Clear the list of newly added entities so that a call to EachAdded after this will have no entities to iterate. This function is protected to facilitate testing.

◆ ClearRemovedComponents()

void ClearRemovedComponents ( )
protected

Clear the list of removed components so that a call to RemoveComponent doesn't make the list grow indefinitely.

◆ Clone()

Entity Clone ( Entity  _entity,
Entity  _parent,
const std::string _name,
bool  _allowRename 
)

Clone an entity and its components. If the entity has any child entities, they will also be cloned. When cloning entities, the following rules apply:

  1. The name component of a cloned entity will consist of a unique name, since all entities should have a unique name.
  2. Cloned entities that have a canonical link will have their canonical link set to the cloned canonical link, not the original canonical link.
  3. Child entities that are cloned will have their parent set to the cloned parent entity.
  4. Cloned joints with parent/child links will have their parent and child links set to the cloned parent/child links.
  5. Aside from the changes listed above, all other cloned components remain unchanged. Currently, cloning detachable joints is not supported.
    Parameters
    [in]_entityThe entity to clone.
    [in]_parentThe parent of the cloned entity. Set this to kNullEntity if the cloned entity should not have a parent.
    [in]_nameThe name that should be given to the cloned entity. Set this to an empty string if the cloned entity name should be auto-generated to something unique.
    [in]_allowRenameTrue if _name can be modified to be a unique name if it isn't already a unique name. False if _name cannot be modified to be a unique name. If _allowRename is set to False, and _name is not unique, _entity will not be cloned. If _name is an empty string, _allowRename is ignored since the cloned entity will have an auto-generated unique name.
    Returns
    The cloned entity, which will have a unique name. kNullEntity is returned if cloning failed. Failure could occur if _entity does not exist, or if a unique name could not be generated for the entity to be cloned.
    See also
    Clone

◆ Component() [1/4]

ComponentTypeT* Component ( const ComponentKey _key)

Get a mutable component based on a key.

Parameters
[in]_keyA key that uniquely identifies a component.
Returns
The component associated with the key, or nullptr if the component could not be found.

◆ Component() [2/4]

const ComponentTypeT* Component ( const ComponentKey _key) const

Get a component based on a key.

Parameters
[in]_keyA key that uniquely identifies a component.
Returns
The component associated with the key, or nullptr if the component could not be found.

◆ Component() [3/4]

ComponentTypeT* Component ( const Entity  _entity)

Get a mutable component assigned to an entity based on a component type.

Parameters
[in]_entityThe entity.
Returns
The component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

◆ Component() [4/4]

const ComponentTypeT* Component ( const Entity  _entity) const

Get a component assigned to an entity based on a component type.

Parameters
[in]_entityThe entity.
Returns
The component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

Referenced by ignition::gazebo::enableComponent(), and Pose3d::UpdateView().

◆ ComponentData()

std::optional<typename ComponentTypeT::Type> ComponentData ( const Entity  _entity) const

Get the data from a component.

  • If the component type doesn't hold any data, this won't compile.
  • If the entity doesn't have that component, it will return nullopt.
  • If the entity has the component, return its data.
    Parameters
    [in]_entityThe entity.
    Template Parameters
    ComponentTypeTComponent type
    Returns
    The data of the component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

◆ ComponentDefault()

ComponentTypeT* ComponentDefault ( Entity  _entity,
const typename ComponentTypeT::Type &  _default = typename ComponentTypeT::Type() 
)

Get a mutable component assigned to an entity based on a component type. If the component doesn't exist, create it and initialize with the given default value.

Parameters
[in]_entityThe entity.
[in]_defaultThe value that should be used to construct the component in case the component doesn't exist.
Returns
The component of the specified type assigned to the specified entity. If _entity does not exist, nullptr is returned.

◆ ComponentState()

gz::sim::ComponentState ComponentState ( const Entity  _entity,
const ComponentTypeId  _typeId 
) const

Get a component's state.

Parameters
[in]_entityEntity that contains the component.
[in]_typeIdComponent type ID.
Returns
Component's current state

◆ ComponentTypes()

std::unordered_set<ComponentTypeId> ComponentTypes ( Entity  _entity) const

Get the type IDs of all components attached to an entity.

Parameters
[in]_entityEntity to check.
Returns
All the component type IDs.

◆ ComponentTypesWithPeriodicChanges()

std::unordered_set<ComponentTypeId> ComponentTypesWithPeriodicChanges ( ) const

Get the components types that are marked as periodic changes.

Returns
All the components that at least one entity marked as periodic changes.

◆ CreateComponent()

ComponentTypeT* CreateComponent ( const Entity  _entity,
const ComponentTypeT &  _data 
)

Create a component of a particular type. This will copy the _data parameter.

Parameters
[in]_entityThe entity that will be associated with the component.
[in]_dataData used to construct the component.
Returns
A pointer to the component that was created. nullptr is returned if the component was not able to be created. If _entity does not exist, nullptr will be returned.

Referenced by ignition::gazebo::enableComponent().

◆ CreateEntity()

Entity CreateEntity ( )

Creates a new Entity.

Returns
An id for the Entity, or kNullEntity on failure.

◆ Descendants()

std::unordered_set<Entity> Descendants ( Entity  _entity) const

Get all entities which are descendants of a given entity, including the entity itself.

Parameters
[in]_entityEntity whose descendants we want.
Returns
All child entities recursively, including _entity. It will be empty if the entity doesn't exist.

◆ Each() [1/2]

void Each ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type  _f)

Get all entities which contain given component types, as well as the mutable components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired mutable component types.
Warning
This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ Each() [2/2]

void Each ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type  _f) const

Get all entities which contain given component types, as well as the components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired component types.
Warning
This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ EachNew() [1/2]

void EachNew ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type  _f)

Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired component types.
Warning
Since entity creation occurs during PreUpdate, this function should not be called in a System's PreUpdate callback (it's okay to call this function in the Update callback). If you need to call this function in a system's PostUpdate callback, you should use the const version of this method.

Referenced by CanonicalLinkModelTracker::AddNewModels().

◆ EachNew() [2/2]

void EachNew ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type  _f) const

Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. This is the const version.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired component types.
Warning
Since entity creation occurs during PreUpdate, this function should not be called in a System's PreUpdate callback (it's okay to call this function in the Update or PostUpdate callback).

◆ EachNoCache() [1/2]

void EachNoCache ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type  _f)

A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the mutable components.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired mutable component types.
Warning
This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ EachNoCache() [2/2]

void EachNoCache ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type  _f) const

A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the components.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired component types.
Warning
This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ EachRemoved()

void EachRemoved ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type  _f) const

Get all entities which contain given component types and are about to be removed, as well as the components.

Parameters
[in]_fCallback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.
Template Parameters
ComponentTypeTsAll the desired component types.
Warning
This function should not be called outside of System's PostUpdate callback.

◆ Entities()

const EntityGraph& Entities ( ) const

Get a graph with all the entities. Entities are vertices and edges point from parent to children.

Returns
Entity graph.

◆ EntitiesByComponents()

std::vector<Entity> EntitiesByComponents ( const ComponentTypeTs &...  _desiredComponents) const

Get all entities which match the value of all the given components. For example, the following will return the entities which have a name component equal to "camera" and a sensor component:

auto entities = EntitiesByComponents(components::Name("camera"), components::Sensor());

Component type must have inequality operator.

Parameters
[in]_desiredComponentsAll the components which must match.
Returns
All matching entities, or an empty vector if no child entity has the exact components.

◆ EntityByComponents()

Entity EntityByComponents ( const ComponentTypeTs &...  _desiredComponents) const

Get an entity which matches the value of all the given components. For example, the following will return the entity which has a name component equal to "name" and has a model component:

auto entity = EntityByComponents(components::Name("name"), components::Model());

Component type must have inequality operator.

Parameters
[in]_desiredComponentsAll the components which must match.
Returns
Entity or kNullEntity if no entity has the exact components.

◆ EntityCount()

size_t EntityCount ( ) const

Get the number of entities on the server.

Returns
Entity count.

◆ EntityHasComponent()

bool EntityHasComponent ( const Entity  _entity,
const ComponentKey _key 
) const

Check whether an entity has a specific component.

Parameters
[in]_entityThe entity to check.
[in]_keyThe component to check.
Returns
True if the component key belongs to the entity.

◆ EntityHasComponentType()

bool EntityHasComponentType ( const Entity  _entity,
const ComponentTypeId _typeId 
) const

Check whether an entity has a specific component type.

Parameters
[in]_entityThe entity to check.
[in]_typeIdComponent type id to check.
Returns
True if the entity exists and has at least one component with the provided type.

◆ EntityMatches()

bool EntityMatches ( Entity  _entity,
const std::set< ComponentTypeId > &  _types 
) const

Get whether an entity has all the given component types.

Parameters
[in]_entityThe entity to check.
[in]_typesComponent types to check that the Entity has.
Returns
True if the given entity has all the given types.

◆ First() [1/2]

ComponentTypeT* First ( )

The first component instance of the specified type. This function is now deprecated, and will always return nullptr.

Returns
nullptr.

◆ First() [2/2]

const ComponentTypeT* First ( ) const

The first component instance of the specified type. This function is now deprecated, and will always return nullptr.

Returns
nullptr.

◆ ForEach()

static void ForEach ( Function  _f,
const ComponentTypeTs &...  _components 
)
static

Call a function for each parameter in a pack.

Parameters
[in]_fFunction to be called.
[in]_componentsParameters which should be passed to the function.

◆ HasComponentType()

bool HasComponentType ( const ComponentTypeId  _typeId) const

Get whether a component type has ever been created.

Parameters
[in]_typeIdID of the component type to check.
Returns
True if the provided _typeId has been created.

◆ HasEntitiesMarkedForRemoval()

bool HasEntitiesMarkedForRemoval ( ) const

Get whether there are any entities marked to be removed.

Returns
True if there are entities marked to be removed.

◆ HasEntity()

bool HasEntity ( const Entity  _entity) const

Get whether an Entity exists.

Parameters
[in]_entityEntity to confirm.
Returns
True if the Entity exists.

◆ HasNewEntities()

bool HasNewEntities ( ) const

Get whether there are new entities.

Returns
True if there are new entities.

◆ HasOneTimeComponentChanges()

bool HasOneTimeComponentChanges ( ) const

Get whether there are one-time component changes. These changes do not happen frequently and should be processed immediately.

Returns
True if there are any components with one-time changes.

◆ HasPeriodicComponentChanges()

bool HasPeriodicComponentChanges ( ) const

Get whether there are periodic component changes. These changes may happen frequently and are processed periodically.

Returns
True if there are any components with periodic changes.

◆ HasRemovedComponents()

bool HasRemovedComponents ( ) const

Return true if there are components marked for removal.

Returns
True if there are components marked for removal.

◆ ParentEntity()

Entity ParentEntity ( const Entity  _entity) const

Get the first parent of the given entity.

Entities are not expected to have multiple parents. TODO(louise) Either prevent multiple parents or provide full support for multiple parents.

Parameters
[in]_entityEntity.
Returns
The parent entity or kNullEntity if there's none.

◆ PeriodicStateFromCache()

void PeriodicStateFromCache ( msgs::SerializedStateMap _state,
const std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &  _cache 
) const

Populate a message with relevant changes to the state given a periodic change cache.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use. Additionally, changes such as addition or removal will not be populated.

Parameters
[in,out]_stateThe serialized state message to populate.
[in]_cacheA map of entities and components to serialize.
See also
EntityComponenetManager::UpdatePeriodicChangeCache

◆ PinEntity()

void PinEntity ( const Entity  _entity,
bool  _recursive = true 
)

Prevent an entity and optionally its children from being removed.

This function can be useful when seek operations during log playback are used in conjunction with spawned entities. For example, you may want to record a video based on a log file using a headless simulation instance. This requires a camera sensor which would be spawned during log playback. If a seek backward in time is performed during log playback, then the spawned camera would be removed. Use this function to prevent the camera from automatic removal.

Parameters
[in]_entityEntity to be pinned.
[in]_recursiveWhether to recursively pin all child entities. True by default.

◆ ProcessRemoveEntityRequests()

void ProcessRemoveEntityRequests ( )
protected

Process all entity remove requests. This will remove entities and their components. This function is protected to facilitate testing.

◆ RebuildViews()

void RebuildViews ( )

Rebuild all the views. This could be an expensive operation.

◆ RemoveComponent() [1/3]

bool RemoveComponent ( const Entity  _entity,
const ComponentKey _key 
)

Remove a component from an entity based on a key.

Parameters
[in]_entityThe entity.
[in]_keyA key that uniquely identifies a component.
Returns
True if the entity and component existed and the component was removed.

Referenced by ignition::gazebo::enableComponent().

◆ RemoveComponent() [2/3]

bool RemoveComponent ( const Entity  _entity,
const ComponentTypeId _typeId 
)

Remove a component from an entity based on a type id.

Parameters
[in]_entityThe entity.
[in]_typeIdComponent's type Id.
Returns
True if the entity and component existed and the component was removed.

◆ RemoveComponent() [3/3]

bool RemoveComponent ( Entity  _entity)

Remove a component from an entity based on a type.

Parameters
[in]_entityThe entity.
Template Parameters
Componenttype.
Returns
True if the entity and component existed and the component was removed.

◆ RequestRemoveEntities()

void RequestRemoveEntities ( )

Request to remove all entities. This will insert the request into a queue. The queue is processed toward the end of a simulation update step.

◆ RequestRemoveEntity()

void RequestRemoveEntity ( const Entity  _entity,
bool  _recursive = true 
)

Request an entity deletion. This will insert the request into a queue. The queue is processed toward the end of a simulation update step.

It is recommended that systems don't call this function directly, and instead use the sim::SdfEntityCreator class to remove entities.

Parameters
[in]_entityEntity to be removed.
[in]_recursiveWhether to recursively delete all child entities. True by default.

◆ SetAllComponentsUnchanged()

void SetAllComponentsUnchanged ( )
protected

Mark all components as not changed.

◆ SetChanged()

void SetChanged ( const Entity  _entity,
const ComponentTypeId  _type,
gz::sim::ComponentState  _c = ComponentState::OneTimeChange 
)

Set the changed state of a component.

Parameters
[in]_entityThe entity.
[in]_typeType of the component.
[in]_cChanged state value, defaults to one-time-change.

◆ SetComponentData()

bool SetComponentData ( const Entity  _entity,
const typename ComponentTypeT::Type &  _data 
)

Set the data from a component.

  • If the component type doesn't hold any data, this won't compile.
  • If the entity doesn't have that component, the component will be created.
  • If the entity has the component, its data will be updated.
    Parameters
    [in]_entityThe entity.
    [in]_dataNew component data
    Template Parameters
    ComponentTypeTComponent type
    Returns
    True if data has changed. It will always be true if the data type doesn't have an equality operator.

◆ SetEntityCreateOffset()

void SetEntityCreateOffset ( uint64_t  _offset)

All future entities will have an id that starts at _offset. This can be used to avoid entity id collisions, such as during log playback.

Parameters
[in]_offsetOffset value.

◆ SetParentEntity()

bool SetParentEntity ( const Entity  _child,
const Entity  _parent 
)

Set the parent of an entity.

It is recommended that systems don't call this function directly, and instead use the sim::SdfEntityCreator class to create entities that have the correct parent-child relationship.

Parameters
[in]_childEntity to set the parent
[in]_parentEntity which should be an immediate parent _child entity.
Returns
True if successful. Will fail if entities don't exist.

◆ SetState() [1/2]

void SetState ( const msgs::SerializedState _stateMsg)

Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state.

The header of the message will not be handled, it is the responsibility of the caller to use the timestamp.

Parameters
[in]_stateMsgMessage containing state to be set.

◆ SetState() [2/2]

void SetState ( const msgs::SerializedStateMap _stateMsg)

Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state.

The header of the message will not be handled, it is the responsibility of the caller to use the timestamp.

Parameters
[in]_stateMsgMessage containing state to be set.

◆ State() [1/2]

msgs::SerializedState State ( const std::unordered_set< Entity > &  _entities = {},
const std::unordered_set< ComponentTypeId > &  _types = {} 
) const

Get a message with the serialized state of the given entities and components.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

Parameters
[in]_entitiesEntities to be serialized. Leave empty to get all entities.
[in]_typesType ID of components to be serialized. Leave empty to get all components.

◆ State() [2/2]

void State ( msgs::SerializedStateMap _state,
const std::unordered_set< Entity > &  _entities = {},
const std::unordered_set< ComponentTypeId > &  _types = {},
bool  _full = false 
) const

Get a message with the serialized state of the given entities and components.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

Parameters
[out]_stateThe serialized state message to populate.
[in]_entitiesEntities to be serialized. Leave empty to get all entities.
[in]_typesType ID of components to be serialized. Leave empty to get all components.
[in]_fullTrue to get all the entities and components. False will get only components and entities that have changed.

◆ UnpinAllEntities()

void UnpinAllEntities ( )

Allow all previously pinned entities to be removed.

See also
void PinEntity(const Entity, bool)

◆ UnpinEntity()

void UnpinEntity ( const Entity  _entity,
bool  _recursive = true 
)

Allow an entity, and optionally its children, previously marked as pinned to be removed.

Parameters
[in]_entityEntity to be unpinned.
[in]_recursiveWhether to recursively unpin all child entities. True by default.
See also
void PinEntity(const Entity, bool)

◆ UpdatePeriodicChangeCache()

void UpdatePeriodicChangeCache ( std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &  ) const

Get a cache of components with periodic changes.

Parameters
[in,out]_changesA list of components with the latest periodic changes. If a component has a periodic change, it is added to the hash map. It the component or entity was removed, it is removed from the hashmap. This way the hashmap stores a list of components and entities which have had periodic changes in the past and still exist within the ECM.
See also
EntityComponentManager::PeriodicStateFromCache

The documentation for this class was generated from the following file: