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