mesh proxy attributes from andrecastelo
[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         @ivar materials: 
49         @type materials: list of L{KX_BlenderMaterial} or L{KX_PolygonMaterial} types
50
51         @ivar numPolygons:
52         @type numPolygons: integer
53
54         @ivar numMaterials:
55         @type numMaterials: integer
56         """
57         
58         def getNumMaterials():
59                 """
60                 Gets the number of materials associated with this object.
61                 
62                 @rtype: integer
63                 """
64         
65         def getMaterialName(matid):
66                 """
67                 Gets the name of the specified material.
68                 
69                 @type matid: integer
70                 @param matid: the specified material.
71                 @rtype: string
72                 @return: the attached material name.
73                 """
74         def getTextureName(matid):
75                 """
76                 Gets the name of the specified material's texture.
77                 
78                 @type matid: integer
79                 @param matid: the specified material
80                 @rtype: string
81                 @return: the attached material's texture name.
82                 """
83         def getVertexArrayLength(matid):
84                 """
85                 Gets the length of the vertex array associated with the specified material.
86                 
87                 There is one vertex array for each material.
88                 
89                 @type matid: integer
90                 @param matid: the specified material
91                 @rtype: integer
92                 @return: the number of verticies in the vertex array.
93                 """
94         def getVertex(matid, index):
95                 """
96                 Gets the specified vertex from the mesh object.
97                 
98                 @type matid: integer
99                 @param matid: the specified material
100                 @type index: integer
101                 @param index: the index into the vertex array.
102                 @rtype: L{KX_VertexProxy}
103                 @return: a vertex object.
104                 """
105         def getNumPolygons():
106                 """
107                 Returns the number of polygon in the mesh.
108                 
109                 @rtype: integer
110                 """
111         def getPolygon(index):
112                 """
113                 Gets the specified polygon from the mesh.
114                 
115                 @type index: integer
116                 @param index: polygon number
117                 @rtype: L{KX_PolyProxy}
118                 @return: a polygon object.
119                 """
120         def reinstancePhysicsMesh():
121                 """
122                 Updates the physics system with the changed mesh.
123                 
124                 A mesh must have only one material with collision flags, 
125                 and have all collision primitives in one vertex array (ie. < 65535 verts) and
126                 be either a polytope or polyheder mesh.  If you don't get a warning in the
127                 console when the collision type is polytope, the mesh is suitable for reinstance.
128                 
129                 @rtype: boolean
130                 @return: True if reinstance succeeded, False if it failed.
131                 """
132