cd90cb5fc8abd2c9951e7410a4a428e0fbd484aa
[blender.git] / source / blender / python / api2_2x / doc / Lamp.py
1 # Blender.Lamp module and the Lamp PyType object
2
3 """
4 The Blender.Lamp submodule.
5
6 B{New}: L{Lamp.clearScriptLinks} accepts a parameter now.
7
8 Lamp Data
9 =========
10
11 This module provides control over B{Lamp Data} objects in Blender.
12
13 Example::
14
15   from Blender import Lamp
16   l = Lamp.New('Spot')            # create new 'Spot' lamp data
17   l.setMode('square', 'shadow')   # set these two lamp mode flags
18   ob = Object.New('Lamp')         # create new lamp object
19   ob.link(l)                      # link lamp obj with lamp data
20
21 @type Types: read-only dictionary
22 @var Types: The lamp types.
23   - 'Lamp': 0
24   - 'Sun' : 1
25   - 'Spot': 2
26   - 'Hemi': 3
27   - 'Area': 4
28   - 'Photon': 5
29 @type Modes: read-only dictionary
30 @var Modes: The lamp modes.  Modes may be ORed together.
31   - 'Shadows'
32   - 'Halo'
33   - 'Layer'
34   - 'Quad'
35   - 'Negative'
36   - 'OnlyShadow'
37   - 'Sphere'
38   - 'Square'
39 """
40
41 def New (type = 'Lamp', name = 'LampData'):
42   """
43   Create a new Lamp Data object.
44   @type type: string
45   @param type: The Lamp type: 'Lamp', 'Sun', 'Spot', 'Hemi', 'Area', or 'Photon'.
46   @type name: string
47   @param name: The Lamp Data name.
48   @rtype: Blender Lamp
49   @return: The created Lamp Data object.
50   """
51
52 def Get (name = None):
53   """
54   Get the Lamp Data object(s) from Blender.
55   @type name: string
56   @param name: The name of the Lamp Data.
57   @rtype: Blender Lamp or a list of Blender Lamps
58   @return: It depends on the I{name} parameter:
59       - (name): The Lamp Data object with the given I{name};
60       - ():     A list with all Lamp Data objects in the current scene.
61   """
62
63 class Lamp:
64   """
65   The Lamp Data object
66   ====================
67     This object gives access to Lamp-specific data in Blender.
68
69   @ivar B:  Lamp color blue component.
70   Value is clamped to the range [0.0,1.0].
71   @type B:  float
72   @ivar G:  Lamp color green component.
73   Value is clamped to the range [0.0,1.0].
74   @type G:  float
75   @ivar R:  Lamp color red component.
76   Value is clamped to the range [0.0,1.0].
77   @type R:  float
78   @ivar bias:  Lamp shadow map sampling bias.
79   Value is clamped to the range [0.01,5.0].
80   @type bias:  float
81   @ivar bufferSize:  Lamp shadow buffer size.
82   Value is clamped to the range [512,5120].
83   @type bufferSize:  int
84   @ivar clipEnd:  Lamp shadow map clip end.
85   Value is clamped to the range [1.0,5000.0].
86   @type clipEnd:  float
87   @ivar clipStart:  Lamp shadow map clip start.
88   Value is clamped to the range [0.1,1000.0].
89   @type clipStart:  float
90   @ivar col:  Lamp RGB color triplet.
91   Components are clamped to the range [0.0,1.0].
92   @type col:  RGB tuple
93   @ivar dist:  Lamp clipping distance.
94   Value is clamped to the range [0.1,5000.0].
95   @type dist:  float
96   @ivar energy:  Lamp light intensity.
97   Value is clamped to the range [0.0,10.0].
98   @type energy:  float
99   @ivar haloInt:  Lamp spotlight halo intensity.
100   Value is clamped to the range [0.0,5.0].
101   @type haloInt:  float
102   @ivar haloStep:  Lamp volumetric halo sampling frequency.
103   Value is clamped to the range [0,12].
104   @type haloStep:  int
105   @ivar ipo:  Lamp Ipo.
106   Contains the Ipo if one is assigned to the object, B{None} otherwise.  Setting to B{None} clears the current Ipo..
107   @type ipo:  Blender Ipo
108   @ivar mode:  Lamp mode bitfield.  See L{Modes} for values.
109   @type mode:  int
110   @ivar name:  Lamp data name.
111   @type name:  str
112   @ivar quad1:  Quad lamp linear distance attenuation.
113   Value is clamped to the range [0.0,1.0].
114   @type quad1:  float
115   @ivar quad2:  Quad lamp quadratic distance attenuation.
116   Value is clamped to the range [0.0,1.0].
117   @type quad2:  float
118   @ivar samples:  Lamp shadow map samples.
119   Value is clamped to the range [1,16].
120   @type samples:  int
121   @ivar softness:  Lamp shadow sample area size.
122   Value is clamped to the range [1.0,100.0].
123   @type softness:  float
124   @ivar spotBlend:  Lamp spotlight edge softness.
125   Value is clamped to the range [0.0,1.0].
126   @type spotBlend:  float
127   @ivar spotSize:  Lamp spotlight beam angle (in degrees).
128   Value is clamped to the range [1.0,180.0].
129   @type spotSize:  float
130   @ivar type:  Lamp type.  See L{Types} for values.
131   @type type:  int
132   @ivar users:  Number of lamp users.
133   @type users:  int
134
135   @warning: Most member variables assume values in some [Min, Max] interval.
136       When trying to set them, the given parameter will be clamped to lie in
137       that range: if val < Min, then val = Min, if val > Max, then val = Max.
138   """
139
140   def getName():
141     """
142     Get the name of this Lamp Data object.
143     @rtype: string
144     """
145
146   def setName(name):
147     """
148     Set the name of this Lamp Data object.
149     @type name: string
150     @param name: The new name.
151     """
152
153   def getType():
154     """
155     Get this Lamp's type.
156     @rtype: int
157     """
158
159   def setType(type):
160     """
161     Set this Lamp's type.
162     @type type: string
163     @param type: The Lamp type: 'Lamp', 'Sun', 'Spot', 'Hemi', 'Area', or 'Photon'
164     """
165
166   def getMode():
167     """
168     Get this Lamp's mode flags.
169     @rtype: int
170     @return: B{OR'ed value}. Use the Modes dictionary to check which flags
171         are 'on'.
172
173         Example::
174           flags = mylamp.getMode()
175           if flags & mylamp.Modes['Shadows']:
176             print "This lamp produces shadows"
177           else:
178             print "The 'Shadows' flag is off"
179     """
180
181   def setMode(m = None, m2 = None, m3 = None, m4 = None,
182               m5 = None, m6 = None, m7 = None, m8 = None):
183     """
184     Set this Lamp's mode flags. Mode strings given are turned 'on'.
185     Those not provided are turned 'off', so lamp.setMode() -- without 
186     arguments -- turns off all mode flags for Lamp lamp.
187     @type m: string
188     @param m: A mode flag. From 1 to 8 can be set at the same time.
189     """
190
191   def getSamples():
192     """
193     Get this lamp's samples value.
194     @rtype: int
195     """
196
197   def setSamples(samples):
198     """
199     Set the samples value.
200     @type samples: int
201     @param samples: The new samples value.
202     """
203
204   def getBufferSize():
205     """
206     Get this lamp's buffer size.
207     @rtype: int
208     """
209
210   def setBufferSize(bufsize):
211     """
212     Set the buffer size value.
213     @type bufsize: int
214     @param bufsize: The new buffer size value.
215     """
216
217   def getHaloStep():
218     """
219     Get this lamp's halo step value.
220     @rtype: int
221     """
222
223   def setHaloStep(hastep):
224     """
225     Set the halo step value.
226     @type hastep: int
227     @param hastep: The new halo step value.
228     """
229
230   def getEnergy():
231     """
232     Get this lamp's energy intensity value.
233     @rtype: float
234     """
235
236   def setEnergy(energy):
237     """
238     Set the energy intensity value.
239     @type energy: float
240     @param energy: The new energy value.
241     """
242
243   def getDist():
244     """
245     Get this lamp's distance value.
246     @rtype: float
247     """
248
249   def setDist(distance):
250     """
251     Set the distance value.
252     @type distance: float
253     @param distance: The new distance value.
254     """
255
256   def getSpotSize():
257     """
258     Get this lamp's spot size value.
259     @rtype: float
260     """
261
262   def setSpotSize(spotsize):
263     """
264     Set the spot size value.
265     @type spotsize: float
266     @param spotsize: The new spot size value.
267     """
268
269   def getSpotBlend():
270     """
271     Get this lamp's spot blend value.
272     @rtype: float
273     """
274
275   def setSpotBlend(spotblend):
276     """
277     Set the spot blend value.
278     @type spotblend: float
279     @param spotblend: The new spot blend value.
280     """
281
282   def getClipStart():
283     """
284     Get this lamp's clip start value.
285     @rtype: float
286     """
287
288   def setClipStart(clipstart):
289     """
290     Set the clip start value.
291     @type clipstart: float
292     @param clipstart: The new clip start value.
293     """
294
295   def getClipEnd():
296     """
297     Get this lamp's clip end value.
298     @rtype: float
299     """
300
301   def setClipEnd(clipend):
302     """
303     Set the clip end value.
304     @type clipend: float
305     @param clipend: The new clip end value.
306     """ 
307
308   def getBias():
309     """
310     Get this lamp's bias value.
311     @rtype: float
312     """
313
314   def setBias(bias):
315     """
316     Set the bias value.
317     @type bias: float
318     @param bias: The new bias value.
319     """ 
320
321   def getSoftness():
322     """
323     Get this lamp's softness value.
324     @rtype: float
325     """
326
327   def setSoftness(softness):
328     """
329     Set the softness value.
330     @type softness: float
331     @param softness: The new softness value.
332     """ 
333
334   def getHaloInt():
335     """
336     Get this lamp's halo intensity value.
337     @rtype: float
338     """
339
340   def setHaloInt(haloint):
341     """
342     Set the halo intensity value.
343     @type haloint: float
344     @param haloint: The new halo intensity value.
345     """ 
346
347   def getQuad1():
348     """
349     Get this lamp's quad 1 value.
350     @rtype: float
351     @warning: this only applies to Lamps with the 'Quad' flag on.
352     """
353
354   def setQuad1(quad1):
355     """
356     Set the quad 1 value.
357     @type quad1: float
358     @warning: this only applies to Lamps with the 'Quad' flag on.
359     """ 
360
361   def getQuad2():
362     """
363     Get this lamp's quad 2 value.
364     @rtype: float
365     @warning: this only applies to Lamps with the 'Quad' flag on.
366     """
367
368   def setQuad2(quad2):
369     """
370     Set the quad 2 value.
371     @type quad2: float
372     @param quad2: The new quad 2 value.
373     @warning: this only applies to Lamps with the 'Quad' flag on.
374     """ 
375
376   def getScriptLinks (event):
377     """
378     Get a list with this Lamp's script links of type 'event'.
379     @type event: string
380     @param event: "FrameChanged", "Redraw" or "Render".
381     @rtype: list
382     @return: a list with Blender L{Text} names (the script links of the given
383         'event' type) or None if there are no script links at all.
384     """
385
386   def clearScriptLinks (links = None):
387     """
388     Delete script links from this Lamp.  If no list is specified, all
389     script links are deleted.
390     @type links: list of strings
391     @param links: None (default) or a list of Blender L{Text} names.
392     """
393
394   def addScriptLink (text, event):
395     """
396     Add a new script link to this Lamp.
397     @type text: string
398     @param text: the name of an existing Blender L{Text}.
399     @type event: string
400     @param event: "FrameChanged", "Redraw" or "Render".
401     """
402
403   def getIpo():
404     """
405     Get the Ipo associated with this Lamp object, if any.
406     @rtype: Ipo
407     @return: the wrapped ipo or None.
408     """
409
410   def setIpo(ipo):
411     """
412     Link an ipo to this Lamp object.
413     @type ipo: Blender Ipo
414     @param ipo: a "lamp data" ipo.
415     """
416
417   def clearIpo():
418     """
419     Unlink the ipo from this Lamp object.
420     @return: True if there was an ipo linked or False otherwise.
421     """
422     
423   def insertIpoKey(keytype):
424     """
425     Inserts keytype values in lamp ipo at curframe. Uses module constants.
426     @type keytype: Integer
427     @param keytype:
428            -RGB
429            -ENERGY
430            -SPOTSIZE
431            -OFFSET
432            -SIZE
433     @return: py_none
434     """