BGE patch: KX_GameObject::rayCast() improvements to have X-Ray option, return true face normal and hit polygon information.

rayCast(to,from,dist,prop,face,xray,poly):

The face paremeter determines the orientation of the normal: 
  0 or omitted => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
  1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
The prop and xray parameters interact as follow:
    prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
    prop off, xray on : idem.
    prop on,  xray off: return closest hit if it matches prop, no hit otherwise.
    prop on,  xray on : return closest hit matching prop or no hit if there is no object matching prop on the full extend of the ray.
if poly is 0 or omitted, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
if poly is 1, returns a 4-tuple with in addition a KX_PolyProxy as 4th element.

The KX_PolyProxy object holds information on the polygon hit by the ray: the index of the vertex forming the poylgon, material, etc.

Attributes (read-only):
 matname: The name of polygon material, empty if no material.
 material: The material of the polygon
 texture: The texture name of the polygon.
 matid: The material index of the polygon, use this to retrieve vertex proxy from mesh proxy
 v1: vertex index of the first vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
 v2: vertex index of the second vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
 v3: vertex index of the third vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
 v4: vertex index of the fourth vertex of the polygon, 0 if polygon has only 3 vertex
     use this to retrieve vertex proxy from mesh proxy
 visible: visible state of the polygon: 1=visible, 0=invisible
 collide: collide state of the polygon: 1=receives collision, 0=collision free.
Methods:
 getMaterialName(): Returns the polygon material name with MA prefix
 getMaterial(): Returns the polygon material
 getTextureName(): Returns the polygon texture name
 getMaterialIndex(): Returns the material bucket index of the polygon. 
 getNumVertex(): Returns the number of vertex of the polygon.
 isVisible(): Returns whether the polygon is visible or not
 isCollider(): Returns whether the polygon is receives collision or not
 getVertexIndex(vertex): Returns the mesh vertex index of a polygon vertex
 getMesh(): Returns a mesh proxy

New methods of KX_MeshProxy have been implemented to retrieve KX_PolyProxy objects:
 getNumPolygons(): Returns the number of polygon in the mesh.
 getPolygon(index): Gets the specified polygon from the mesh.

More details in PyDoc.

1 files changed, 45 insertions, 2 deletions

diff --git a/source/gameengine/Physics/common/PHY_IPhysicsEnvironment.h b/source/gameengine/Physics/common/PHY_IPhysicsEnvironment.h
index 5b275066665..98496fb7f9e 100644
--- a/source/gameengine/Physics/common/PHY_IPhysicsEnvironment.h
+++ b/source/gameengine/Physics/common/PHY_IPhysicsEnvironment.h
@@ -33,6 +33,50 @@
 #include <vector>
 #include "PHY_DynamicTypes.h"
 class PHY_IVehicle;
+class RAS_MeshObject;
+class PHY_IPhysicsController;
+
+/**
+ * pass back information from rayTest
+ */
+struct PHY_RayCastResult
+{
+	PHY_IPhysicsController* m_controller;	
+	PHY__Vector3			m_hitPoint;
+	PHY__Vector3			m_hitNormal;
+	const RAS_MeshObject*	m_meshObject;	// !=NULL for mesh object (only for Bullet controllers) 
+	int						m_polygon;		// index of the polygon hit by the ray,
+											// only if m_meshObject != NULL
+};
+
+/**
+ * This class replaces the ignoreController parameter of rayTest function. 
+ * It allows more sophisticated filtering on the physics controller before computing the ray intersection to save CPU. 
+ * It is only used to its full extend by the Ccd physics environement (Bullet).
+ */
+class PHY_IRayCastFilterCallback
+{
+public:
+	PHY_IPhysicsController* m_ignoreController;
+	bool					m_faceNormal;
+
+	virtual		~PHY_IRayCastFilterCallback()
+	{
+	}
+
+	virtual	bool needBroadphaseRayCast(PHY_IPhysicsController* controller)
+	{
+		return true;
+	}
+
+	virtual void reportHit(PHY_RayCastResult* result) = 0;
+
+	PHY_IRayCastFilterCallback(PHY_IPhysicsController* ignoreController, bool faceNormal=false) 
+		:m_ignoreController(ignoreController),
+		m_faceNormal(faceNormal)
+	{
+	}
+};
 
 /**
 *	Physics Environment takes care of stepping the simulation and is a container for physics entities (rigidbodies,constraints, materials etc.)
@@ -94,8 +138,7 @@ class PHY_IPhysicsEnvironment
 		//complex constraint for vehicles
 		virtual PHY_IVehicle*	getVehicleConstraint(int constraintId) =0;
 
-		virtual PHY_IPhysicsController* rayTest(PHY_IPhysicsController* ignoreClient, float fromX,float fromY,float fromZ, float toX,float toY,float toZ, 
-										float& hitX,float& hitY,float& hitZ,float& normalX,float& normalY,float& normalZ)=0;
+		virtual PHY_IPhysicsController* rayTest(PHY_IRayCastFilterCallback &filterCallback, float fromX,float fromY,float fromZ, float toX,float toY,float toZ)=0;
 
 
 		//Methods for gamelogic collision/physics callbacks