FC_DistanceQuery – General Information

Overview

Type:	Function
Available as of:	V1.0.0.0
Versions:	Current version

This chapter provides information on:

Description
Interface
Diagnostic Messages
Examples

Description

This function requires any combination of collision objects, collision groups or collision entities as inputs.

As a result, it returns:

The minimum distance between the inputs
If i_xEvaluateClosestPoints is set to TRUE, the function will evaluate the closest points between the two inputs

Interface

Input	Data type	Description
i_ifQueryInterface1	IF_CollisionQueryInterface	A first object implementing IF_CollisionQueryInterface. This can be a collision object, a collision group or a collision entity.
i_ifQueryInterface2	IF_CollisionQueryInterface	A second object implementing IF_CollisionQueryInterface. This can be a collision object, a collision group or a collision entity.
i_xEvaluateClosestPoints	BOOL	If TRUE, the closest points between the two inputs are evaluated.

Output	Data type	Description
q_xError	BOOL	The output is set to TRUE if an error has been detected during the execution.
q_etResult	ET_Result	POU-specific output on the diagnostic; q_xError = FALSE -> Status message; q_xError = TRUE -> Diagnostic message.
q_sResultMsg	String	Event-triggered message that gives additional information on the diagnostic state.
q_xCollision	BOOL	TRUE if there is a collision detected between the two inputs.
q_lrDistance	LREAL	The minimum distance between the two inputs. This is zero if q_xCollision = TRUE.
q_udiCollisionGroupIndex1	UDINT	Index of the colliding group of i_ifQueryInterface1. This has a zero value if i_ifQueryInterface1 is referring to a collision object or a collision group.
q_udiCollisionObjectIndex1	UDINT	Index of the closest object in the group with index q_udiCollisionGroupIndex1 of i_ifQueryInterface1. This has a zero value if i_ifQueryInterface1 is referring to a collision object.
q_udiCollisionGroupIndex2	UDINT	Index of the closest group of i_ifQueryInterface2. This has a zero value if i_ifQueryInterface2 is referring to a collision object or a collision group.
q_udiCollisionObjectIndex2	UDINT	Index of the closest object in the group with index q_udiCollisionGroupIndex2 of i_ifQueryInterface2. This has a zero value if i_ifQueryInterface2 is referring to a collision object.
q_stClosestPoint1	SE_Math.ST_Vector3D	Closest point for i_ifQueryInterface1. This is only evaluated if i_xEvaluateClosestPoint = TRUE; otherwise, it will return a null vector.

Diagnostic Messages

q_xError	q_etResult	Enumeration value	Description
FALSE	OK	0	Success
TRUE	NoCollisionGroupsEnabled	36	No collision groups enabled.
TRUE	InterfaceInvalid	11	The provided interface is invalid (null).
TRUE	CollisionEntityNotUpdated	34	The collision entity has not been updated.
TRUE	CollisionGroupNotUpdated	21	A collision group is not updated.
TRUE	CollisionObjectTypeInvalid	16	The provided collision object type is invalid.
TRUE	CollisionObjectNotConfigured	12	The object is not configured.
TRUE	CollisionQueryInterfaceTypeInvalid	52	The provided collision query interface is referring to an invalid type.

OK

Enumeration name:	Ok
Enumeration value:	0
Description:	Success

NoCollisionGroupsEnabled

Enumeration name:	NoCollisionGroupsEnabled
Enumeration value:	36
Description:	No collision groups enabled.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 refers to a collision entity. All the configured collision groups of that entity are disabled, meaning that the relative elements of raxEnableCollisionGroups are set to FALSE.	Make sure to enable the groups of the entity that you want to query for collision.
Not possible to make a collision query.	i_ifQueryInterface2 refers to a collision entity. All the configured collision groups of that entity are disabled, meaning that the relative elements of raxEnableCollisionGroups are set to FALSE.	Make sure to enable the groups of the entity that you want to query for collision.

InterfaceInvalid

Enumeration name:	InterfaceInvalid
Enumeration value:	11
Description:	The provided interface is invalid (null).

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 contains an invalid interface.	Make sure that i_ifQueryInterface1 is not null.
Not possible to make a collision query.	i_ifQueryInterface2 contains an invalid interface.	Make sure that i_ifQueryInterface2 is not null.

CollisionEntityNotUpdated

Enumeration name:	CollisionEntityNotUpdated
Enumeration value:	34
Description:	The collision entity has not been updated.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 refers to a collision entity that is not updated, meaning that its property xUpdated = FALSE.	Make sure that an entity is updated before providing it as input of this function.
Not possible to make a collision query.	i_ifQueryInterface2 refers to a collision entity that is not updated, meaning that its property xUpdated = FALSE.	Make sure that an entity is updated before providing it as input of this function.

CollisionGroupNotUpdated

Enumeration name:	CollisionGroupNotUpdated
Enumeration value:	21
Description:	A collision group is not updated.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 refers to a collision group that is not updated, meaning that its property xUpdated = FALSE.	Make sure that a group is updated before providing it as input of this function.
Not possible to make a collision query.	i_ifQueryInterface2 refers to a collision group that is not updated, meaning that its property xUpdated = FALSE.	Make sure that a group is updated before providing it as input of this function.

CollisionObjectTypeInvalid

Enumeration name:	CollisionObjectTypeInvalid
Enumeration value:	16
Description:	The provided collision object type is invalid.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 refers to a collision object with an invalid collision object type.	Make sure that i_ifQueryInterface1 refers to a collision object with a valid collision object type. The valid types are: ET_CollisionObjectType.AABB ET_CollisionObjectType.OBB ET_CollisionObjectType.Sphere ET_CollisionObjectType.Capsule
Not possible to make a collision query.	i_ifQueryInterface2 refers to a collision object with an invalid collision object type.	Make sure that i_ifQueryInterface2 refers to a collision object with a valid collision object type. The valid types are: ET_CollisionObjectType.AABB ET_CollisionObjectType.OBB ET_CollisionObjectType.Sphere ET_CollisionObjectType.Capsule

CollisionObjectNotConfigured

Enumeration name:	CollisionObjectNotConfigured
Enumeration value:	12
Description:	The object is not configured.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 refers to a collision object that is not configured, meaning that its property xConfigured = FALSE.	Make sure that an object is configured before providing it as input of this function.
Not possible to make a collision query.	i_ifQueryInterface2 refers to a collision object that is not configured, meaning that its property xConfigured = FALSE	Make sure that an object is configured before providing it as input of this function.

CollisionQueryInterfaceTypeInvalid

Enumeration name:	CollisionQueryInterfaceTypeInvalid
Enumeration value:	52
Description:	The provided collision query interface is referring to an invalid type.

Issue	Cause	Solution
Not possible to make a collision query.	i_ifQueryInterface1 is referring to an invalid object type.	Make sure that i_ifQueryInterface1 is referring to a collision object, group or entity.
Not possible to make a collision query.	i_ifQueryInterface2 is referring to an invalid object type.	Make sure that i_ifQueryInterface2 is referring to a collision object, group or entity

Examples

Example of distance query between i_ifQueryInterface1 (object) and i_ifQueryInterface2 (group). In this case, q_udiCollisionObjectIndex2 = 4 that is the index of the closest object within the group:

Example of distance query between i_ifQueryInterface1 (entity) and i_ifQueryInterface2 (object). In this case, q_udiCollisionGroupIndex1 = 1 and q_udiCollisionObjectIndex1 = 1 since the closest object inside the entity is in group 1 and has index 1:

Example of distance query between i_ifQueryInterface1 (entity) and i_ifQueryInterface2 (entity). In this case, q_udiCollisionGroupIndex1 = 2 and q_udiCollisionObjectIndex1 = 3 for the first entity and q_udiCollisionGroupIndex2 = 1 and q_udiCollisionObjectIndex2 = 2 for the second entity.