blender/source/gameengine/PyDoc/KX_MeshProxy.py

126 lines
3.5 KiB
Python
Raw Normal View History

# $Id$
# Documentation for KX_MeshProxy
class KX_MeshProxy:
"""
A mesh object.
You can only change the vertex properties of a mesh object, not the mesh topology.
2004-06-07 11:03:12 +00:00
To use mesh objects effectively, you should know a bit about how the game engine handles them.
1. Mesh Objects are converted from Blender at scene load.
2. The Converter groups polygons by Material. This means they can be sent to the
renderer efficiently. A material holds:
1. The texture.
2. The Blender material.
3. The Tile properties
4. The face properties - (From the "Texture Face" panel)
5. Transparency & z sorting
6. Light layer
7. Polygon shape (triangle/quad)
8. Game Object
3. Verticies will be split by face if necessary. Verticies can only be shared between
faces if:
1. They are at the same position
2. UV coordinates are the same
3. Their normals are the same (both polygons are "Set Smooth")
4. They are the same colour
For example: a cube has 24 verticies: 6 faces with 4 verticies per face.
The correct method of iterating over every L{KX_VertexProxy} in a game object::
import GameLogic
co = GameLogic.getcurrentController()
obj = co.getOwner()
m_i = 0
mesh = obj.getMesh(m_i) # There can be more than one mesh...
while mesh != None:
for mat in range(mesh.getNumMaterials()):
for v_index in range(mesh.getVertexArrayLength(mat)):
vertex = mesh.getVertex(mat, v_index)
# Do something with vertex here...
# ... eg: colour the vertex red.
vertex.colour = [1.0, 0.0, 0.0, 1.0]
m_i += 1
mesh = obj.getMesh(m_i)
"""
2004-06-07 11:03:12 +00:00
def getNumMaterials():
"""
Gets the number of materials associated with this object.
@rtype: integer
"""
2004-06-07 11:03:12 +00:00
def getMaterialName(matid):
"""
Gets the name of the specified material.
@type matid: integer
@param matid: the specified material.
@rtype: string
@return: the attached material name.
"""
2004-06-07 11:03:12 +00:00
def getTextureName(matid):
"""
Gets the name of the specified material's texture.
@type matid: integer
@param matid: the specified material
@rtype: string
@return: the attached material's texture name.
"""
2004-06-07 11:03:12 +00:00
def getVertexArrayLength(matid):
"""
Gets the length of the vertex array associated with the specified material.
There is one vertex array for each material.
@type matid: integer
@param matid: the specified material
@rtype: integer
@return: the number of verticies in the vertex array.
"""
2004-06-07 11:03:12 +00:00
def getVertex(matid, index):
"""
Gets the specified vertex from the mesh object.
@type matid: integer
@param matid: the specified material
@type index: integer
@param index: the index into the vertex array.
@rtype: L{KX_VertexProxy}
@return: a vertex object.
"""
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.
2008-08-27 19:34:19 +00:00
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.
A mesh must have only one material with collision flags,
and have all collision primitives in one vertex array (ie. < 65535 verts) and
be either a polytope or polyheder mesh. If you don't get a warning in the
console when the collision type is polytope, the mesh is suitable for reinstance.
@rtype: boolean
@return: True if reinstance succeeded, False if it failed.
"""