Added the docs & use Python booleans for physics reinstance.
[blender.git] / source / gameengine / PyDoc / KX_MeshProxy.py
1 # $Id$
2 # Documentation for KX_MeshProxy
3
4 class KX_MeshProxy:
5         """
6         A mesh object.
7         
8         You can only change the vertex properties of a mesh object, not the mesh topology.
9         
10         To use mesh objects effectively, you should know a bit about how the game engine handles them.
11                 1. Mesh Objects are converted from Blender at scene load.
12                 2. The Converter groups polygons by Material.  This means they can be sent to the
13                    renderer efficiently.  A material holds:
14                         1. The texture.
15                         2. The Blender material.
16                         3. The Tile properties
17                         4. The face properties - (From the "Texture Face" panel)
18                         5. Transparency & z sorting
19                         6. Light layer
20                         7. Polygon shape (triangle/quad)
21                         8. Game Object
22                 3. Verticies will be split by face if necessary.  Verticies can only be shared between
23                    faces if:
24                         1. They are at the same position
25                         2. UV coordinates are the same
26                         3. Their normals are the same (both polygons are "Set Smooth")
27                         4. They are the same colour
28                    For example: a cube has 24 verticies: 6 faces with 4 verticies per face.
29                    
30         The correct method of iterating over every L{KX_VertexProxy} in a game object::
31                 import GameLogic
32                 
33                 co = GameLogic.getcurrentController()
34                 obj = co.getOwner()
35                 
36                 m_i = 0
37                 mesh = obj.getMesh(m_i) # There can be more than one mesh...
38                 while mesh != None:
39                         for mat in range(mesh.getNumMaterials()):
40                                 for v_index in range(mesh.getVertexArrayLength(mat)):
41                                         vertex = mesh.getVertex(mat, v_index)
42                                         # Do something with vertex here...
43                                         # ... eg: colour the vertex red.
44                                         vertex.colour = [1.0, 0.0, 0.0, 1.0]
45                         m_i += 1
46                         mesh = obj.getMesh(m_i)
47         
48                         
49         """
50         
51         def getNumMaterials():
52                 """
53                 Gets the number of materials associated with this object.
54                 
55                 @rtype: integer
56                 """
57         
58         def getMaterialName(matid):
59                 """
60                 Gets the name of the specified material.
61                 
62                 @type matid: integer
63                 @param matid: the specified material.
64                 @rtype: string
65                 @return: the attached material name.
66                 """
67         def getTextureName(matid):
68                 """
69                 Gets the name of the specified material's texture.
70                 
71                 @type matid: integer
72                 @param matid: the specified material
73                 @rtype: string
74                 @return: the attached material's texture name.
75                 """
76         def getVertexArrayLength(matid):
77                 """
78                 Gets the length of the vertex array associated with the specified material.
79                 
80                 There is one vertex array for each material.
81                 
82                 @type matid: integer
83                 @param matid: the specified material
84                 @rtype: integer
85                 @return: the number of verticies in the vertex array.
86                 """
87         def getVertex(matid, index):
88                 """
89                 Gets the specified vertex from the mesh object.
90                 
91                 @type matid: integer
92                 @param matid: the specified material
93                 @type index: integer
94                 @param index: the index into the vertex array.
95                 @rtype: L{KX_VertexProxy}
96                 @return: a vertex object.
97                 """
98         def reinstancePhysicsMesh():
99                 """
100                 Updates the physics system with the changed mesh.
101                 
102                 A mesh must have only one material with collision flags, 
103                 and have all collision primitives in one vertex array (ie. < 65535 verts) and
104                 be either a polytope or polyheder mesh.  If you don't get a warning in the
105                 console when the collision type is polytope, the mesh is suitable for reinstance.
106                 
107                 @rtype: boolean
108                 @return: True if reinstance succeeded, False if it failed.
109                 """
110