Initial revision
[blender.git] / intern / python / modules / Blender / Material.py
1 """The Blender Material module
2
3   This module provides access to *Material* datablocks
4
5   Example::
6
7     from Blender import Material, NMesh, Object, Scene
8     m = Material.New()                         # create free Material datablock
9     m.rgbCol = (1.0, 0.0, 0.3)                    # assign RGB values
10     mesh = NMesh.GetRaw()                      # get new mesh
11     mesh.addMaterial(m)                        # add material to mesh
12     object = Object.New('Mesh')                # create new object 
13     object.link(mesh)                          # link mesh data to object
14     Scene.getCurrent().link(ob)                # link object to current scene
15 """
16
17 import _Blender.Material as _Material
18 import shadow
19 #import Blender.Curve as Curve
20
21 # These are getters and setters needed for emulation
22
23 def _getRGB(obj):
24         return (obj.R, obj.G, obj.B)
25
26 def _getSpec(obj):
27         return (obj.specR, obj.specG, obj.specB)
28
29 def _getMir(obj):
30         return (obj.mirR, obj.mirG, obj.mirB)
31
32 def _setRGB(obj, rgb):
33         obj.R, obj.G, obj.B = rgb
34
35 def _setSpec(obj, rgb):
36         obj.specR, obj.specG, obj.specB = rgb
37
38 def _setMir(obj, rgb):
39         obj.mirR, obj.mirG, obj.mirB = rgb
40
41
42
43 class Material(shadow.hasIPO, shadow.hasModes):
44         """Material DataBlock object
45
46     See example in the Material module documentation on how to create
47     an instance of a Material object.
48
49   Attributes
50
51     The following attributes are colour vectors (r, g, b)
52         
53     rgbCol     -- The color vector (R, G, B).
54                       The RGB values can be accessed individually as .R, .G and .B 
55
56     specCol    -- Specularity color vector (specR, specG, specG)
57
58     mirCol     -- Mirror color vector (mirR, mirG, mirB)
59
60     The following are float values:
61         
62     alpha      -- The transparency
63
64     ref        -- Reflectivity float value
65
66     emit       -- Emit intensity value 
67
68     amb        -- Ambient intensity value 
69
70     spec       -- specularity value 
71
72     specTransp -- Specular transpareny 
73
74     haloSize   -- Halo size
75
76     mode       -- The material mode bit vector - see Material.ModeFlags
77
78     hard       -- The hardness value
79
80 """ 
81
82         _emulation = {'Mode'   : "mode",
83                       'Ref'    : "ref",
84                                   'HaSize' : "haloSize",
85                                   'SpTra'  : "specTransp",
86                                   'Alpha'  : "alpha",
87                                   'Spec'   : "spec",
88                                   'Emit'   : "emit",
89                                   'Hard'   : "hard",
90                                   'Amb'    : "amb",
91                                  } 
92
93         _getters   = {'rgbCol'  : _getRGB,
94                       'specCol' : _getSpec,
95                                   'mirCol'  : _getMir,
96                  } 
97
98         _setters   = {'rgbCol'  : _setRGB,
99                       'specCol' : _setSpec,
100                                   'mirCol'  : _setMir,
101                                   } 
102
103         t = _Material.Modes
104
105         Modes =         {'traceable' : t.TRACEABLE,
106                                          'shadow'    : t.SHADOW,
107                                          'shadeless' : t.SHADELESS,
108                                          'wire'      : t.WIRE,
109                                          'vcolLight' : t.VCOL_LIGHT,
110                                          'vcolPaint' : t.VCOL_PAINT,
111                                          'zTransp'   : t.ZTRANSP,
112                                          'zInvert'   : t.ZINVERT,
113                                          'onlyShadow': t.ONLYSHADOW,
114                                          'star'      : t.STAR,
115                                          'texFace'   : t.TEXFACE,
116                                          'noMist'    : t.NOMIST,
117                                         } 
118
119         t = _Material.HaloModes
120
121         HaloModes =     { "rings"   : t.RINGS,
122                                           "lines"   : t.LINES,
123                                           "tex"     : t.TEX,
124                                           "haloPuno": t.PUNO,
125                                           "shade"   : t.SHADE,
126                                           "flare"   : t.FLARE,
127                                         }
128
129
130         del t
131
132         def setMode(self, *args):
133                 """Set the mode of 'self'. This function takes a variable number
134 of string arguments of the types listed in self.Modes.
135
136   Example::
137
138     m = Material.New()
139     m.setMode('shadow', 'wire')
140 """
141                 flags = 0
142                 try:
143                         for a in args:
144                                 flags |= self.Modes[a]
145                 except:
146                         raise TypeError, "mode must be one of" % self.Modes.keys()
147                 self._object.mode = flags
148
149         def setHaloMode(self, *args):
150                 """Sets the material to Halo mode. 
151 This function takes a variable number of string arguments of the types 
152 listed in self.HaloModes"""
153                 flags = _Material.Modes.HALO
154
155                 try:
156                         for a in args:
157                                 flags |= self.HaloModes[a]
158                 except:
159                         raise TypeError, "mode must be one of" % self.HaloModes.keys()
160                 self._object.mode = flags
161
162         
163 class ModeFlags:
164         """Readonly dictionary
165
166 ...containing Material mode bitvectors:
167
168 |------------------------------------------|
169 | Name         |  Description              |
170 |==========================================|
171 | TRACEABLE    | visible for shadow lamps  |
172 |------------------------------------------|
173 | SHADOW       | cast shadow               |
174 |------------------------------------------|
175 | SHADELESS    | do not shade              |
176 |------------------------------------------|
177 | WIRE         | draw in wireframe         |
178 |------------------------------------------|
179 | VCOL_LIGHT   | use vertex colors         |
180 |              | with lighting             |
181 |------------------------------------------|
182 | VCOL_PAINT   | vertex colours            |
183 |------------------------------------------|
184 | HALO         | Halo material             |
185 |------------------------------------------|
186 | ZTRANSP      | Z transparency            |
187 |------------------------------------------|
188 | ZINVERT      | invert Z                  |
189 |------------------------------------------|
190 | ONLYSHADOW   | only shadow, but          |
191 |              | don't render              |
192 |------------------------------------------|
193 | STAR         |  ?                        |
194 |------------------------------------------|
195 | TEXFACE      | textured faces            |
196 |------------------------------------------|
197 | NOMIST       | disable mist              |
198 |------------------------------------------|
199
200 These mode flags directly represent the buttons in the Material parameters
201 window (EditButtons)
202
203 Example::
204
205   # be 'm' a material
206   from Blender.Material.Modes import *
207   m.mode |= (TRACEABLE + WIRE)    # Set 'wire' and 'traceable' flagsd
208   m.mode &= ~SHADELESS            # clear 'shadeless' flag
209 """
210         
211         t = _Material.Modes
212         TRACEABLE  = t.TRACEABLE
213         SHADOW     = t.SHADOW
214         SHADELESS  = t.SHADELESS
215         WIRE       = t.WIRE
216         VCOL_LIGHT = t.VCOL_LIGHT
217         VCOL_PAINT = t.VCOL_PAINT
218         HALO       = t.HALO
219         ZTRANSP    = t.ZTRANSP
220         ZINVERT    = t.ZINVERT
221         ONLYSHADOW = t.ONLYSHADOW
222         STAR       = t.STAR
223         TEXFACE    = t.TEXFACE
224         NOMIST     = t.NOMIST
225         del t
226         
227 # override:
228 ModeFlags = _Material.Modes
229
230 def get(name = None):
231         """If 'name' given, the Material 'name' is returned if existing, 'None' otherwise.
232 If no name is given, a list of all Materials is returned"""
233         if name:
234                 return Material(_Material.get(name))
235         else:
236                 return shadow._List(_Material.get(), Material)
237         
238 Get = get  # emulation
239
240 def New(name = None):
241         """Creates a new, empty Material and returns it. 
242
243 Example::
244
245   from Blender import Material
246   mat = Material.New()
247 """
248         mat = Material(_Material.New())
249         if name:
250                 mat.name = name
251         return mat