Defining a Collision Entity

Overview

To define a collision entity, the following steps are required:

Step	Action
1	Within the variable declaration, define some collision objects. These are the objects that will be added to the collision groups. `VAR //objects that will be added to group 1 fbSphere1 : COD.FB_Sphere; fbOBB1 : COD.FB_OBB; //objects that will be added to group 2 fbCapsule2 : COD.FB_Capsule; fbAABB2 : COD.FB_AABB; fbSphere2 : COD.FB_Sphere; END_VAR` In addition to these objects, some other support variables may be required.
2	Within the variable declaration, define some collision groups. These are the groups that will be added to the collision entity. `VAR … //collision groups instances fbGroup1 : COD.FB_CollisionGroup; fbGroup2 : COD.FB_CollisionGroup; END_VAR`
3	Within the variable declaration, define an instance of a collision entity object. `VAR … //a collision entity instance fbEntity : COD.FB_CollisionEntity; END_VAR`
4	It is possible to add the collision objects to the groups by calling AddCollisionObjects(…). Refer to Defining a Collision Group.
5	Call the method fbEntity.AddCollisionGroup (…) of the entity to add the desired collision groups; it is possible to save the index of a group added to the entity reading the return value of AddCollisionGroup. `//add the first group to the entity udiGroup1Index := fbEntity.AddCollisionGroup( i_ifCollisionGroup := fbGroup1, q_xError => xError, q_etResult => etResult, q_sResultMsg=> sResultMsg ); //check diagnostics here IF xError THEN //do something to handle the error … END_IF //add the second group to the entity udiGroup2Index := fbEntity.AddCollisionGroup( i_ifCollisionGroup := fbGroup2, q_xError => xError, q_etResult => etResult, q_sResultMsg=> sResultMsg ); //check diagnostics here …` NOTE: If all the calls of AddCollisionGroup are successful, the property fbEntity.udiNumberOfCollisionGroups shows the correct number of groups stored within the entity. In this example, it is fbEntity.udiNumberOfCollisionGroups = 2. The collision groups do not need to be updated (for example fbGroup1.xUpdated = TRUE) at the time they are added to a collision entity. Each collision group added to the list is then accessible from the property fbEntity.raifCollisionGroups as a COD.IF_CollisionGroup interface according to the order of insertion in the entity. It is possible to use the index value returned on a call of AddCollisionGroup to access the right interface from fbEntity.raifCollisionGroups.
6	If there is the need of reconfiguring an entity, you can use the method fbEntity.Reset(…) of the collision entity to remove all the groups from the entity and then start a new configuration.

Using the Entity in a Collision or Distance Query

Update the entity before using the entity in a collision or distance query. For this purpose, the following steps must be followed:

Step	Action
1	If required, reconfigure the single collision objects and verify that they are properly configured. This means that xConfigured = TRUE for each object in the list.
2	Perform one of the following steps: Make sure that all the objects in the added groups are properly configured; that means that xConfigured = TRUE for each object in the groups. If this condition is met, it is then possible to call fbEntity.Update(…) as follows: `fbEntity.Update( i_xUpdateGroups := TRUE, q_xError => xError, q_etResult => etResult, q_sResultMsg=> sResultMsg );` Since the input i_xUpdateGroups is set to TRUE, the entity will automatically try to update all the groups that have been added to it. This is a way to avoid doing a manual update of each individual group and then perform the update of the entity. If required, update the groups in the entity, making sure that xUpdated = TRUE for each of them. A group needs to be updated if one or more of its configured objects has been reconfigured. If this condition is met, it is then possible to call fbEntity.Update(…) as follows: `fbEntity.Update( i_xUpdateGroups := FALSE, q_xError => xError, q_etResult => etResult, q_sResultMsg=> sResultMsg );` Since the input i_xUpdateGroups is set to FALSE, the entity will expect that all the groups in the list are already updated, meaning that it must be xUpdated = TRUE for each group before the Update method is called. Setting i_xUpdateGroups = TRUE does not cause an error if the groups have already been updated, but it can cause additional calculations.
3	It is possible to verify that fbEntity.xUpdated = TRUE to make sure that the last Update call has been successful. This is a mandatory condition in order to be able to perform a collision or distance query on an entity.

Step

Action

If required, reconfigure the single collision objects and verify that they are properly configured. This means that xConfigured = TRUE for each object in the list.

Perform one of the following steps:

Make sure that all the objects in the added groups are properly configured; that means that xConfigured = TRUE for each object in the groups. If this condition is met, it is then possible to call fbEntity.Update(…) as follows:
```
   fbEntity.Update(
      i_xUpdateGroups := TRUE,			
      q_xError => xError, 
      q_etResult => etResult, 
      q_sResultMsg=> sResultMsg
	);
```
Since the input i_xUpdateGroups is set to TRUE, the entity will automatically try to update all the groups that have been added to it. This is a way to avoid doing a manual update of each individual group and then perform the update of the entity.
If required, update the groups in the entity, making sure that xUpdated = TRUE for each of them. A group needs to be updated if one or more of its configured objects has been reconfigured. If this condition is met, it is then possible to call fbEntity.Update(…) as follows:
```
   fbEntity.Update(
      i_xUpdateGroups := FALSE,			
      q_xError => xError, 
      q_etResult => etResult, 
      q_sResultMsg=> sResultMsg
);
```
Since the input i_xUpdateGroups is set to FALSE, the entity will expect that all the groups in the list are already updated, meaning that it must be xUpdated = TRUE for each group before the Update method is called. Setting i_xUpdateGroups = TRUE does not cause an error if the groups have already been updated, but it can cause additional calculations.

It is possible to verify that fbEntity.xUpdated = TRUE to make sure that the last Update call has been successful. This is a mandatory condition in order to be able to perform a collision or distance query on an entity.

NOTE:

If at least one successful update has been performed and no modifications have been performed on the listed groups and on the objects within such groups, there is no need to perform a new Update call.
It is possible to define overlapping groups within the same entity. This does not generate the detection of a self-collision while calling the collision and distance query functions.
The same collision group instance can be added to multiple entities. In the same way, it is possible to get a group from an existing entity and use it individually for the collision and distance queries.