BPython:
[blender.git] / source / blender / python / api2_2x / doc / Material.py
1 # Blender.Material module and the Material PyObject
2
3 """
4 The Blender.Material submodule.
5
6 B{New}: scriptLink methods: L{Material.getScriptLinks}, ...
7
8 Material 
9 ========
10
11 This module provides access to B{Material} objects in Blender.
12
13 Example::
14   import Blender
15   from Blender import Material
16   mat = Material.New('newMat')          # create a new Material called 'newMat'
17   print mat.rgbCol                      # print its rgb color triplet
18   mat.rgbCol = [0.8, 0.2, 0.2]          # change its color
19   mat.setAlpha(0.2)                     # mat.alpha = 0.2 -- almost transparent
20   mat.emit = 0.7                        # equivalent to mat.setEmit(0.8)
21   mat.mode |= Material.Modes.ZTRANSP    # turn on Z-Buffer transparency
22   mat.setName('RedBansheeSkin')         # change its name
23   mat.setAdd(0.8)                       # make it glow
24   mat.setMode('Halo')                   # turn 'Halo' "on" and all others "off"
25
26 @type Modes: readonly dictionary
27 @var Modes: The available Material Modes.
28     - TRACEABLE    - Make Material visible for shadow lamps.
29     - SHADOW       - Enable Material for shadows.
30     - SHADELESS    - Make Material insensitive to light or shadow.
31     - WIRE         - Render only the edges of faces.
32     - VCOL_LIGHT   - Add vertex colors as extra light.
33     - VCOL_PAINT   - Replace basic colors with vertex colors.
34     - HALO         - Render as a halo.
35     - ZTRANSP      - Z-buffer transparent faces.
36     - ZINVERT      - Render with inverted Z-buffer.
37     - - HALORINGS  - Render rings over the basic halo.
38     - ENV          - Do not render Material.
39     - - HALOLINES  - Render star shaped lines over the basic halo.
40     - ONLYSHADOW   - Let alpha be determined on the degree of shadow.
41     - - HALOXALPHA - Use extreme alpha.
42     - TEXFACE      - UV-Editor assigned texture gives color and texture info
43         for faces.
44     - - HALOSTAR   - Render halo as a star.
45     - NOMIST       - Set the Material insensitive to mist.
46     - - HALOSHADED - Let halo receive light.
47     - HALOTEX      - Give halo a texture.
48     - HALOPUNO     - Use the vertex normal to specify the dimension of the halo.
49     - HALOFLARE    - Render halo as a lens flare.
50
51 @warn: Some Modes are only available when the 'Halo' mode is I{off} and
52     others only when it is I{on}.  But these two subsets of modes share the same
53     numerical values in their Blender C #defines. So, for example, if 'Halo' is
54     on, then 'NoMist' is actually interpreted as 'HaloShaded'.  We marked all
55     such possibilities in the Modes dict below: each halo-related mode that
56     uses an already taken value is preceded by "-" and appear below the normal
57     mode which also uses that value.
58 """
59
60 def New (name = 'Mat'):
61   """
62   Create a new Material object.
63   @type name: string
64   @param name: The Material name.
65   @rtype: Blender Material
66   @return: The created Material object.
67   """
68
69 def Get (name = None):
70   """
71   Get the Material object(s) from Blender.
72   @type name: string
73   @param name: The name of the Material.
74   @rtype: Blender Material or a list of Blender Materials
75   @return: It depends on the 'name' parameter:
76     - (name): The Material object with the given name;
77     - ():   A list with all Material objects in the current scene.
78   """
79
80 class Material:
81   """
82   The Material object
83   ===================
84    This object gives access to Materials in Blender.
85   @cvar name: Material's name.
86   @type mode: int
87   @cvar mode: Mode flags as an or'ed int value.  See the Modes dictionary keys
88       and descriptions in L{Modes}.
89   @cvar rgbCol: Material's RGB color triplet.
90   @cvar specCol: Specular color rgb triplet.
91   @cvar mirCol: Mirror color rgb triplet.
92   @cvar R: Red component of L{rgbCol} - [0.0, 1.0].
93   @cvar G: Green component of L{rgbCol} - [0.0, 1.0].
94   @cvar B: Blue component of L{rgbCol} - [0.0, 1.0].
95   @cvar alpha: Alpha (translucency) component of the Material - [0.0, 1.0].
96   @cvar amb: Ambient factor - [0.0, 1.0].
97   @cvar emit: Emitting light intensity - [0.0, 1.0].
98   @cvar ref:  Reflectivity - [0.0, 1.0].
99   @cvar spec: Specularity - [0.0, 2.0].
100   @cvar specTransp: Specular transparency - [0.0, 1.0].
101   @cvar add: Glow factor - [0.0, 1.0].
102   @cvar zOffset: Artificial Z offset for faces - [0.0, 10.0].
103   @cvar haloSize: Dimension of the halo - [0.0, 100.0].
104   @cvar flareSize: Factor the flare is larger than the halo - [0.1, 25.0].
105   @cvar flareBoost: Flare's extra strength - [0.1, 10.0].
106   @cvar haloSeed: To use random values for ring dimension and line location -
107      [0, 255].
108   @cvar flareSeed: Offset in the seed table - [0, 255].
109   @cvar subSize:  Dimension of subflares, dots and circles - [0.1, 25.0].
110   @cvar hard: Hardness of the specularity - [1, 255].
111   @cvar nFlares: Number of halo subflares - [1, 32].
112   @cvar nStars: Number of points on the halo stars - [3, 50].
113   @cvar nLines: Number of star shaped lines on each halo - [0, 250].
114   @cvar nRings: Number of halo rings - [0, 24].
115   @type ipo: Blender Ipo
116   @cvar ipo: This Material's ipo.
117   @warning: Most member variables assume values in some [Min, Max] interval.
118    When trying to set them, the given parameter will be clamped to lie in
119    that range: if val < Min, then val = Min, if val > Max, then val = Max.
120   """
121
122   def getName():
123     """
124     Get the name of this Material object.
125     @rtype: string
126     """
127
128   def setName(name):
129     """
130     Set the name of this Material object.
131     @type name: string
132     @param name: The new name.
133     """
134
135   def getIpo():
136     """
137     Get the Ipo associated with this material, if any.
138     @rtype: Ipo
139     @return: the wrapped ipo or None.
140     """
141
142   def setIpo(ipo):
143     """
144     Link an ipo to this material.
145     @type ipo: Blender Ipo
146     @param ipo: a material type ipo.
147     """
148
149   def clearIpo():
150     """
151     Unlink the ipo from this material.
152     @return: True if there was an ipo linked or False otherwise.
153     """
154
155   def getMode():
156     """
157     Get this Material's mode flags.
158     @rtype: int
159     @return: B{OR'ed value}. Use the Modes dictionary to check which flags
160         are 'on'.
161
162         Example::
163           import Blender
164           from Blender import Material
165           flags = mymat.getMode()
166           if flags & Material.Modes['HALO']:
167             print "This material is rendered as a halo"
168           else:
169             print "Not a halo"
170     """
171
172   def setMode(m = None, m2 = None, m3 = None, and_so_on = None,
173               up_to_21 = None):
174     """
175     Set this Material's mode flags. Mode strings given are turned 'on'.
176     Those not provided are turned 'off', so mat.setMode() -- without 
177     arguments -- turns off all mode flags for Material mat.
178     @type m: string
179     @param m: A mode flag. From 1 to 21 can be set at the same time.
180     """
181
182   def getRGBCol():
183     """
184     Get the rgb color triplet.
185     @rtype: list of 3 floats
186     @return: [r, g, b]
187     """
188
189   def setRGBCol(rgb = None):
190     """
191     Set the rgb color triplet.  If B{rgb} is None, set the color to black.
192     @type rgb: three floats or a list of three floats
193     @param rgb: The rgb color values in [0.0, 1.0] as:
194         - a list of three floats: setRGBCol ([r, g, b]) B{or}
195         - three floats as separate parameters: setRGBCol (r,g,b).
196     """
197  
198   def getSpecCol():
199     """
200     Get the specular color triplet.
201     @rtype: list of 3 floats
202     @return: [specR, specG, specB]
203     """
204
205   def setSpecCol(rgb = None):
206     """
207     Set the specular color triplet.  If B{rgb} is None, set the color to black.
208     @type rgb: three floats or a list of three floats
209     @param rgb: The rgb color values in [0.0, 1.0] as:
210         - a list of three floats: setSpecCol ([r, g, b]) B{or}
211         - three floats as separate parameters: setSpecCol (r,g,b).
212     """
213
214   def getMirCol():
215     """
216     Get the mirror color triplet.
217     @rtype: list of 3 floats
218     @return: [mirR, mirG, mirb]
219     """
220
221   def setMirCol(rgb = None):
222     """
223     Set the mirror color triplet.  If B{rgb} is None, set the color to black.
224     @type rgb: three floats or a list of three floats
225     @param rgb: The rgb color values in [0.0, 1.0] as:
226         - a list of three floats: setMirCol ([r, g, b]) B{or}
227         - three floats as separate parameters: setMirCol (r,g,b).
228     """
229
230   def getAlpha():
231     """
232     Get the alpha (transparency) value.
233     @rtype: float
234     """
235
236   def setAlpha(alpha):
237     """
238     Set the alpha (transparency) value.
239     @type alpha: float
240     @param alpha: The new value in [0.0, 1.0].
241     """
242
243   def getAmb():
244     """
245     Get the ambient color blend factor.
246     @rtype: float
247     """
248
249   def setAmb(amb):
250     """
251     Set the ambient color blend factor.
252     @type amb: float
253     @param amb:  The new value in [0.0, 1.0].
254     """
255
256   def getEmit():
257     """
258     Get the emitting light intensity.
259     @rtype: float
260     """
261
262   def setEmit(emit):
263     """
264     Set the emitting light intensity.
265     @type emit: float
266     @param emit: The new value in [0.0, 1.0].
267     """
268
269   def getRef():
270     """
271     Get the reflectivity value.
272     @rtype: float
273     """
274
275   def setRef(ref):
276     """
277     Set the reflectivity value.
278     @type ref: float
279     @param ref: The new value in [0.0, 1.0].
280     """
281
282   def getSpec():
283     """
284     Get the specularity value.
285     @rtype: float
286     """
287
288   def setSpec(spec):
289     """
290     Set the specularity value.
291     @type spec: float
292     @param spec: The new value in [0.0, 2.0].
293     """
294
295   def getSpecTransp():
296     """
297     Get the specular transparency.
298     @rtype: float
299     """
300
301   def setSpecTransp(spectransp):
302     """
303     Set the specular transparency.
304     @type spectransp: float
305     @param spectransp: The new value in [0.0, 1.0].
306     """
307
308   def getAdd():
309     """
310     Get the glow factor.
311     @rtype: float
312     """
313
314   def setAdd(add):
315     """
316     Set the glow factor.
317     @type add: float
318     @param add: The new value in [0.0, 1.0].
319     """
320
321   def getZOffset():
322     """
323     Get the artificial offset for faces with this Material.
324     @rtype: float
325     """
326
327   def setZOffset(zoffset):
328     """
329     Set the artificial offset for faces with this Material.
330     @type zoffset: float
331     @param zoffset: The new value in [0.0, 10.0].
332     """
333
334   def getHaloSize():
335     """
336     Get the halo size.
337     @rtype: float
338     """
339
340   def setHaloSize(halosize):
341     """
342     Set the halo size.
343     @type halosize: float
344     @param halosize: The new value in [0.0, 100.0].
345     """
346
347   def getHaloSeed():
348     """
349     Get the seed for random ring dimension and line location in halos.
350     @rtype: int
351     """
352
353   def setHaloSeed(haloseed):
354     """
355     Set the seed for random ring dimension and line location in halos.
356     @type haloseed: int
357     @param haloseed: The new value in [0, 255].
358     """
359
360   def getFlareSize():
361     """
362     Get the ratio: flareSize / haloSize.
363     @rtype: float
364     """
365
366   def setFlareSize(flaresize):
367     """
368     Set the ratio: flareSize / haloSize.
369     @type flaresize: float
370     @param flaresize: The new value in [0.1, 25.0].
371     """
372
373   def getFlareSeed():
374     """
375     Get flare's offset in the seed table.
376     @rtype: int
377     """
378
379   def setFlareSeed(flareseed):
380     """
381     Set flare's offset in the seed table.
382     @type flareseed: int
383     @param flareseed: The new value in [0, 255].
384     """
385
386   def getFlareBoost():
387     """
388     Get the flare's extra strength.
389     @rtype: float
390     """
391
392   def setFlareBoost(flareboost):
393     """
394     Set the flare's extra strength.
395     @type flareboost: float
396     @param flareboost: The new value in [0.1, 10.0].
397     """
398
399   def getSubSize():
400     """
401     Get the dimension of subflare, dots and circles.
402     @rtype: float
403     """
404
405   def setSubSize(subsize):
406     """
407     Set the dimension of subflare, dots and circles.
408     @type subsize: float
409     @param subsize: The new value in [0.1, 25.0].
410     """
411
412   def getHardness():
413     """
414     Get the hardness of the specularity.
415     @rtype: int
416     """
417
418   def setHardness(hardness):
419     """
420     Set the hardness of the specularity.
421     @type hardness: int
422     @param hardness: The new value in [1, 255].
423     """
424
425   def getNFlares():
426     """
427     Get the number of halo subflares.
428     @rtype: int
429     """
430
431   def setNFlares(nflares):
432     """
433     Set the number of halo subflares.
434     @type nflares: int
435     @param nflares: The new value in [1, 32].
436     """
437
438   def getNStars():
439     """
440     Get the number of points in the halo stars.
441     @rtype: int
442     """
443
444   def setNStars(nstars):
445     """
446     Set the number of points in the halo stars.
447     @type nstars: int
448     @param nstars: The new value in [3, 50].
449     """
450
451   def getNLines():
452     """
453     Get the number of star shaped lines on each halo.
454     @rtype: int
455     """
456
457   def setNLines(nlines):
458     """
459     Set the number of star shaped lines on each halo.
460     @type nlines: int
461     @param nlines: The new value in [0, 250].
462     """
463
464   def getNRings():
465     """
466     Get the number of rings on each halo.
467     @rtype: int
468     """
469
470   def setNRings(nrings):
471     """
472     Set the number of rings on each halo.
473     @type nrings: int
474     @param nrings: The new value in [0, 24].
475     """
476
477   def setTexture(index, texture, texco, mapto):
478     """
479     Assign a Blender Texture object to slot number 'number'.
480     @type index: int
481     @param index: material's texture index in [0, 7].
482     @type texture: Blender Texture
483     @param texture: a Blender Texture object.
484     @type texco: int
485     @param texco: optional or'ed bitflag -- defaults to TexCo.ORCO.  See TexCo var in L{Texture}.
486     @type mapto: int
487     @param mapto: optional or'ed bitflag -- defaults to MapTo.COL.  See MapTo var in L{Texture}.
488     """
489
490   def clearTexture(index):
491     """
492     Clear the ith (given by 'index') texture channel of this material.
493     @type index: int
494     @param index: material's texture channel index in [0, 7].
495     """
496
497   def getTextures ():
498     """
499     Get this Material's Texture list.
500     @rtype: list of MTex
501     @return: a list of Blender MTex objects.  None is returned for each empty
502         texture slot.
503     """
504
505   def getScriptLinks (event):
506     """
507     Get a list with this Material's script links of type 'event'.
508     @type event: string
509     @param event: "FrameChanged" or "Redraw".
510     @rtype: list
511     @return: a list with Blender L{Text} names (the script links of the given
512         'event' type) or None if there are no script links at all.
513     """
514
515   def clearScriptLinks ():
516     """
517     Delete all this Material's script links.
518     @rtype: bool
519     @return: 0 if some internal problem occurred or 1 if successful.
520     """
521
522   def addScriptLink (text, event):
523     """
524     Add a new script link to this Material.
525     @type text: string
526     @param text: the name of an existing Blender L{Text}.
527     @type event: string
528     @param event: "FrameChanged" or "Redraw".
529     """