From becd467be8613b1f71278d8a58337186a3f79170 Mon Sep 17 00:00:00 2001 From: Benoit Bolsee Date: Wed, 27 Aug 2008 19:34:19 +0000 Subject: 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. --- source/gameengine/PyDoc/KX_GameObject.py | 33 +++++++--- source/gameengine/PyDoc/KX_MeshProxy.py | 15 +++++ source/gameengine/PyDoc/KX_PolyProxy.py | 100 +++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 7 deletions(-) create mode 100644 source/gameengine/PyDoc/KX_PolyProxy.py (limited to 'source/gameengine/PyDoc') diff --git a/source/gameengine/PyDoc/KX_GameObject.py b/source/gameengine/PyDoc/KX_GameObject.py index 033b2864351..2136ce54e30 100644 --- a/source/gameengine/PyDoc/KX_GameObject.py +++ b/source/gameengine/PyDoc/KX_GameObject.py @@ -300,10 +300,11 @@ class KX_GameObject: @rtype: L{KX_GameObject} @return: the first object hit or None if no object or object does not match prop """ - def rayCast(to,from,dist,prop): + def rayCast(to,from,dist,prop,face,xray,poly): """ Look from a point/object to another point/object and find first object hit within dist that matches prop. - Returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit. + if poly is 0, 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 L{KX_PolyProxy} as 4th element. Ex: # shoot along the axis gun-gunAim (gunAim should be collision-free) ob,point,normal = gun.rayCast(gunAim,None,50) @@ -312,9 +313,18 @@ class KX_GameObject: Notes: The ray ignores the object on which the method is called. - If is casted from/to object center or explicit [x,y,z] points. - The ray does not have X-Ray capability: the first object hit (other than self object) stops the ray - If a property was specified and the first object hit does not have that property, there is no hit + It is casted from/to object center or explicit [x,y,z] points. + The face paremeter determines the orientation of the normal: + 0 => 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. + The L{KX_PolyProxy} 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray. + If there is no hit or the hit object is not a static mesh, None is returned as 4th element. The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects. @param to: [x,y,z] or object to which the ray is casted @@ -325,8 +335,17 @@ class KX_GameObject: @type dist: float @param prop: property name that object must have; can be omitted => detect any object @type prop: string - @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) - @return: (object,hitpoint,hitnormal) or (None,None,None) + @param face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin + @type face: int + @param xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object + @type xray: int + @param poly: polygon option: 1=>return value is a 4-tuple and the 4th element is a L{KX_PolyProxy} + @type poly: int + @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) + or 4-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), L{KX_PolyProxy)) + @return: (object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon) + If no hit, returns (None,None,None) or (None,None,None,None) + If the object hit is not a static mesh, polygon is None """ diff --git a/source/gameengine/PyDoc/KX_MeshProxy.py b/source/gameengine/PyDoc/KX_MeshProxy.py index e43fa3598f0..03bc36b6ac1 100644 --- a/source/gameengine/PyDoc/KX_MeshProxy.py +++ b/source/gameengine/PyDoc/KX_MeshProxy.py @@ -95,6 +95,21 @@ class KX_MeshProxy: @rtype: L{KX_VertexProxy} @return: a vertex object. """ + def getNumPolygons(): + """ + Returns the number of polygon in the mesh. + + @rtype: integer + """ + def getPolygon(index): + """ + Gets the specified polygon from the mesh. + + @type index: integer + @param index: polygon number + @rtype: L{KX_PolyProxy} + @return: a polygon object. + """ def reinstancePhysicsMesh(): """ Updates the physics system with the changed mesh. diff --git a/source/gameengine/PyDoc/KX_PolyProxy.py b/source/gameengine/PyDoc/KX_PolyProxy.py new file mode 100644 index 00000000000..45ae30a13dd --- /dev/null +++ b/source/gameengine/PyDoc/KX_PolyProxy.py @@ -0,0 +1,100 @@ +# $Id$ +# Documentation for the polygon proxy class + +class KX_PolyProxy: + """ + A polygon holds the index of the vertex forming the poylgon. + + Note: + The polygon attributes are read-only, you need to retrieve the vertex proxy if you want + to change the vertex settings. + + @ivar matname: The name of polygon material, empty if no material. + @type matname: string + @ivar material: The material of the polygon + @type material: L{KX_PolygonMaterial} or KX_BlenderMaterial + @ivar texture: The texture name of the polygon. + @type texture: string + @ivar matid: The material index of the polygon, use this to retrieve vertex proxy from mesh proxy + @type matid: integer + @ivar v1: vertex index of the first vertex of the polygon, use this to retrieve vertex proxy from mesh proxy + @type v1: integer + @ivar v2: vertex index of the second vertex of the polygon, use this to retrieve vertex proxy from mesh proxy + @type v2: integer + @ivar v3: vertex index of the third vertex of the polygon, use this to retrieve vertex proxy from mesh proxy + @type v3: integer + @ivar 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 + @type v4: integer + @ivar visible: visible state of the polygon: 1=visible, 0=invisible + @type visible: integer + @ivar collide: collide state of the polygon: 1=receives collision, 0=collision free. + @type collide: integer + """ + + def getMaterialName(): + """ + Returns the polygon material name with MA prefix + + @rtype: string + @return: material name + """ + def getMaterial(): + """ + Returns the polygon material + + @rtype: L{KX_PolygonMaterial} or KX_BlenderMaterial + """ + def getTextureName(): + """ + Returns the polygon texture name + + @rtype: string + @return: texture name + """ + def getMaterialIndex(): + """ + Returns the material bucket index of the polygon. + This index and the ones returned by getVertexIndex() are needed to retrieve the vertex proxy from L{KX_MeshProxy}. + + @rtype: integer + @return: the material index in the mesh + + def getNumVertex(): + """ + Returns the number of vertex of the polygon. + + @rtype: integer + @return: number of vertex, 3 or 4. + """ + def isVisible(): + """ + Returns whether the polygon is visible or not + + @rtype: integer + @return: 0=invisible, 1=visible + """ + def isCollider(): + """ + Returns whether the polygon is receives collision or not + + @rtype: integer + @return: 0=collision free, 1=receives collision + """ + def getVertexIndex(vertex): + """ + Returns the mesh vertex index of a polygon vertex + This index and the one returned by getMaterialIndex() are needed to retrieve the vertex proxy from L{KX_MeshProxy}. + + @type vertex: integer + @param vertex: index of the vertex in the polygon: 0->3 + @rtype: integer + @return: mesh vertex index + """ + def getMesh(): + """ + Returns a mesh proxy + + @rtype: L{KX_MeshProxy} + @return: mesh proxy + """ -- cgit v1.2.3