C4 Engine
C4 Engine API Documentation


Defined in:  C4World.h
Detects a collision between world geometry and a swept sphere.

bool DetectCollision(const Point3D& p1, const Point3D& p2, float radius, uint32 kind,

CollisionData *collisionData, int32 threadIndex = ThreadMgr::kMaxWorkerThreadCount) const;

p1 The beginning of the line segment in world space.
p2 The end of the line segment in world space.
radius The radius of the sphere. This cannot be negative, but it can be zero.
kind The collision kind.
collisionData The returned collision data.
threadIndex The index of the Thread Manager worker thread that is calling this function.
The points specified by the parameters p1 and p2, combined with the radius specified by the radius parameter, define a directed swept sphere. The DetectCollision function detects the first collision between this swept sphere and all enabled Geometry nodes possessing collision information. If a collision is detected, then the function returns true; otherwise, it returns false.

The kind parameter can be used to invalidate certain types of collisions. When a candidate geometry is encountered in the collision detection process, its collision exclusion mask is logically ANDed with the value of the kind parameter. A collision can only occur if the result of this operation is zero. The collision mask associated with a geometry can be set using the GeometryObject::SetCollisionExclusionMask function. The collision kind can be a combination (through logical OR) of the following predefined values and application-defined values.
kCollisionRigidBody Any type of rigid body.
kCollisionCharacter A rigid body that represents a character.
kCollisionProjectile A rigid body that represents a projectile.
kCollisionVehicle A rigid body that represents a vehicle.
kCollisionCamera A type of camera.
kCollisionSightPath When used in an exclusion mask, does not obstruct sight.
kCollisionSoundPath When used in an exclusion mask, does not obstruct sound.
kCollisionBaseKind First application-defined collision kind.
kCollisionExcludeAll When used as a collision exclusion mask, this value prevents collisions with everything.
If a collision occurs, then the CollisionData structure pointed to by the collisionData parameter is filled out with information about the collision. The param field of this data structure represents the fraction of the distance that the sphere traveled from p1 to p2 before the collision occurred.

The threadIndex parameter specifies the index of the Thread Manager worker thread that has called the DetectCollision function. If the DetectCollision function is called from the main thread, then this parameter should not be specified so that the default value is used. If the DetectCollision function is called from a job, then the threadIndex parameter should be set to the value returned by the Job::GetThreadIndex function. The threadIndex parameter must be set correctly in order for multithreaded collision detection to work properly.
IMPORTANT. If the DetectCollision function is called from inside a Thread Manager worker thread, then the application code must ensure that the scene is not modified while the job is running.
The DetectCollision function works by intersecting a line segment with the Minkowski sum of a sphere and arbitrary polygon meshes. The algorithm is very precise and can determine when collisions occur with the expanded faces, edges, or vertices of the mesh referenced by a geometry node. If the value of the radius parameter is 0.0, then the collision detection reduces to a ray intersection with faces only.
See Also