===Python API===
[blender.git] / source / blender / python / api2_2x / doc / Ipo.py
1 # Blender.Ipo module and the Ipo PyType object
2
3 """
4 The Blender.Ipo submodule
5
6 B{New}: 
7   -  Ipo updates to both the program and Bpython access.
8   -  access to Blender's new Ipo driver capabilities.
9   -  Ipo now supports the mapping operator [] to access IpoCurves
10
11 This module provides access to the Ipo Data in Blender. An Ipo is composed of
12 several IpoCurves, and an IpoCurve are composed of several BezTriples.
13
14 Example::
15   from Blender import Ipo
16
17   ob = Ipo.Get('ObIpo')          # retrieves an Ipo object
18   ob.name = 'ipo1'                               # change the Ipo's name
19   icu = ipo[Ipo.OB_LOCX]         # request X Location Ipo curve object
20   if icu != None and len(icu.bezierPoints) > 0: # if curve exists and has BezTriple points
21      val = icu[2.5]              # get the curve's value at time 2.5
22      icu[Ipo.OB_lOCX] = None     # delete the ipo curve
23   
24 Each type of Ipo has different types Ipocurves.  With the exception of Shape
25 Key Ipos, constants are used to specify all Ipocurves.  There are two ways
26 to tell which Ipo curves go with which Ipo type:
27   - all constants start with a two-character identifier for their Ipo type;
28   for example, "OB_LOCX" is the LocX curve for an Object Ipo
29   - each Ipo now has a read-only attribute L{Ipo.curveConsts}, which returns 
30   the valid Ipo curve types for that specific Ipo
31
32 The valid IpoCurve constants are:
33       1. Material Ipo: MA_R, MA_G, MA_B, MA_SPECR, MA_SPECG, MA_SPECB,
34       MA_MIRR, MA_MIRG, MA_MIRB, MA_REF, MA_ALPHA, MA_EMIT, MA_AMB,
35       MA_SPEC, MA_HARD, MA_SPTRA, MA_IOR, MA_MODE, MA_HASIZE, MA_TRANSLU,
36       MA_RAYMIR, MA_FRESMIR, MA_FRESMIRI, MA_FRESTRA, MA_FRESTRAI,
37       MA_TRAGLOW, MA_OFSX, MA_OFSY, MA_OFSZ, MA_SIZEX, MA_SIZEY, MA_SIZEZ,
38       MA_TEXR, MA_TEXG, MA_TEXB, MA_DEFVAR, MA_COL, MA_NOR, MA_VAR, MA_DISP
39       2. Lamp Ipo: LA_ENERG, LA_R, LA_G, LA_B, LA_DIST, LA_SPOSI, LA_SPOBL,
40       LA_QUAD1, LA_QUAD2, LA_HAINT, LA_OFSX, LA_OFSY, LA_OFSZ, LA_SIZEX,
41       LA_SIZEY, LA_SIZEZ, LA_TEXR, LA_TEXG, LA_TEXB, LA_DEFVAR, LA_COL
42       3. World Ipo: WO_HORR, WO_HORG, WO_HORB, WO_ZENR, WO_ZENG, WO_ZENB,
43       WO_EXPOS, WO_MISI, WO_MISDI, WO_MISSTA, WO_MISHI, WO_STARR,
44       WO_STARB, WO_STARG, WO_STARDI, WO_STARSI, WO_OFSX, WO_OFSY,
45       WO_OFSZ, WO_SIZEX, WO_SIZEY, WO_SIZEZ, WO_TEXR, WO_TEXG,
46       WO_TEXB, WO_DEFVAR, WO_COL, WO_NOR, WO_VAR
47       4. Camera Ipo: CA_LENS, CA_CLSTA, CA_CLEND, CA_APERT, CA_FDIST
48       5. Object Ipo: OB_LOCX, OB_LOCY, OB_LOCZ, OB_DLOCX, OB_DLOCY, OB_DLOCZ,
49       OB_ROTX, OB_ROTY, OB_ROTZ, OB_DROTX, OB_DROTY, OB_DROTZ,
50       OB_SIZEX, OB_SIZEY, OB_SIZEZ, OB_DSIZEX, OB_DSIZEY, OB_DSIZEZ,
51       OB_LAYER, OB_TIME, OB_COLR, OB_COLG, OB_COLB, OB_COLA,
52       OB_FSTRENG, OB_FFALL, OB_RDAMP, OB_DAMPING, OB_PERM
53       6. Curve Ipo: CU_SPEED
54       7. Constraint Ipo: CO_INF
55       8. Texture Ipo: TE_NSIZE, TE_NDEPTH, TE_NTYPE, TE_TURB, TE_VNW1, TE_VNW2,
56       TE_VNW3, TE_VNW4, TE_MINKMEXP, TE_DISTM, TE_COLT, TE_ISCALE,
57       TE_DISTA, TE_MGTYPE, TE_MGH, TE_LACU, TE_OCT, TE_MGOFF,
58       TE_MGGAIN, TE_NBASE1, TE_NBASE2, TE_COLR, TE_COLG, TE_COLB,
59       TE_BRIGHT, TE_CONTRAS
60       9. Pose/Action Ipo: PO_LOCX, PO_LOCY, PO_LOCZ, PO_SIZEX, PO_SIZEY,
61       PO_SIZEZ, PO_QUATW, PO_QUATX, PO_QUATY, PO_QUATZ
62       10. Sequence Ipo: SQ_FAC
63
64 Shape Key Ipos are handled differently from other Ipos.  The user can rename
65 the curves, so string are used to access them instead of constants.  The
66 L{Ipo.curveConsts} attribute for Shape Key Ipos returns a list of all defined
67 key names.
68 """
69
70 def New (type, name):
71   """
72   Creates a new Ipo.
73   @type type: string
74   @type name: string
75   @param type: The Ipo's blocktype. Depends on the object the Ipo will be
76       linked to. Currently supported types are Object, Camera, World,
77       Material, Texture, Lamp, Action, Constraint, Sequence, Curve, Key.
78   @param name: The name for this Ipo.
79   @rtype: Blender Ipo
80   @return: The created Ipo.
81   """
82
83 def Get (name = None):
84   """
85   Get the Ipo from Blender.
86   @type name: string
87   @param name: The name of the requested Ipo, or nothing.
88   @rtype: Blender Ipo or a list of Blender Ipos
89   @return: It depends on the 'name' parameter:
90       - (name): The Ipo with the given name;
91       - (): A list with all Ipos in the current scene.
92   """
93
94 class Ipo:
95   """
96   The Ipo object
97   ==============
98   This object gives access to Ipo data from all objects in Blender.
99   @Note: Blender Materials, Lamps and Worlds have I{texture channels} which
100   allow the user to assign textures to them.  The Blender Ipo Window allows
101   the user to access the IpoCurves for these channels by specifying a number
102   between 0 and 9 (the number appears next to the Ipo type in the window
103   header).  Prior to Version 2.42, the BPy API did not allow users to access
104   these texture channels in a predictable manner.  A new attribute named
105   L{channel} was added to the API in Version 2.42 to correct this problem.
106
107   The current channel setting has an effect on the operators B{[]}, B{len()} 
108   and others.  For example, suppose a Material has three IpoCurves 
109   (R, G, and B), and two texture channels (numbered 0 and 1), and furthermore
110   channel 0 has one Ipocurve (Col).  The IpoCurve Col can only be
111   "seen" through the API when B{ipo.channel} is 0.  Setting B{ipo.channel} to
112   1 will cause this curve to be ignored by B{len(ipo)}::
113
114     from Blender import Ipo
115
116     ipo = Ipo.Get('MatIpo')
117     for channel in xrange(2):
118         ipo.channel = channel
119         print 'channel is',channel
120             print ' len is',len(ipo)
121         names = dict([(x[1],x[0]) for x in ipo.curveConsts.items()])
122         for curve in [Ipo.MA_R,Ipo.MA_COL]:
123             print ' ',names[curve],'is',curve in ipo
124
125   will output::
126     channel is 0
127     len is 4
128       MA_R is True
129       MA_COL is True
130     channel is 1
131     len is 3
132       MA_R is True
133       MA_COL is False
134
135   @ivar name: The Ipo datablock's name
136   @type name: string
137   @ivar curves: Ipo curves currently defined for the Ipo.
138   @type curves: list of Ipocurves.
139   @ivar curveConsts: The valid Ipo curves for this Ipo.  These can be used
140   by the [] mapping operator.  The value 
141   depends on the Ipo curve type.  If the Ipo is any type other than a Key or
142   Shape Ipo, this attribute returns a set of constants that can be
143   used to specify a particular curve.  For Key or Shape Ipos, the attribute
144   returns a list of all defined keys by name.  
145   @type curveConsts: constant or list of strings. Read-only.
146   @ivar channel: the current texture channel for Blender object which support
147   textures (materials, lamps and worlds).  Returns None if the Ipo does
148   not support texture channels. Value must be in the range [0,9].
149   @type channel: int or None
150   """
151
152   def __contains__():
153     """
154     The "in" operator for Ipos. It returns B{True} if the specified 
155     IpoCurve exists for the Ipo.  This operator B{should not} be used to 
156     test for whether a curve constant is valid for a particular Ipo type.
157     Many constants for different Ipo types have the same value, and it is
158     the constant's value used internally.
159     No exceptions are raised if the argument is not a valid curve constant or
160     or string, nor does the operator return B{True} when the curve
161     constant is valid but does not currently exist.  As such, it should only be
162     used to test for specific curves when the Ipo type is known::
163       ipo = Object.Get('Cube').ipo # get Object-type Ipo 
164       if ipo:
165         print Ipo.OB_LOCX in ipo # prints "True" if 'LocX' curve exists
166         print Ipo.MA_R in ipo    # also prints "True" since MA_R and OB_LOCX are have the same value
167         print 'hiccup' in ipo    # always prints "False" since argument is not a constant
168
169     @return: see above.
170     @rtype: Boolean
171     """
172
173   def __getitem__():
174     """
175     This operator is similar to the Python dictionary mapping operator [],
176     except that the user cannot assign arbitrary keys.  Each Ipo type has
177     a pre-defined set of IpoCurves which may or may not exist at a given time.      This operator
178     will either return an IpoCurve object if the specified curve exists,
179     return None if the curve does not exists, or throws a KeyError exception
180     if the curve is not valid for this Ipo type.
181     @return: an IpoCurve object if it exists
182     @rtype: IpoCurve or None
183     @raise KeyError: an undefined IpoCurve was specified for the Ipo
184     """
185
186   def __iter__():
187     """
188     Iterator for Ipos.  It returns all the defined IpoCurve objects associated 
189     with the Ipo.  For example::
190        from Blender import Ipo
191
192        ipo = Ipo.Get()
193        if len(ipo) > 0:
194          ipo = ipo[0]
195          print 'ipo name is',ipo.name
196          for icu in ipo:
197            print ' curve name is',icu.name
198     might result in::
199        ipo name is ObIpo
200          curve name is LocX
201          curve name is LocY
202          curve name is LocZ
203
204     @return: an IpoCurve object
205     @rtype: IpoCurve
206     """
207
208   def __len__():
209     """
210     Returns the number of curves defined for the Ipo.
211     @return: number of defined IpoCurves
212     @rtype: int
213     """
214
215   def getName():
216     """
217     Gets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
218     @rtype: string
219     @return: the name of the Ipo.
220     """
221
222   def setName(newname):
223     """
224     Sets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
225     @type newname: string
226     @rtype: None
227     @return: None
228     """
229
230   def getCurves():
231     """
232     Gets all the IpoCurves of the Ipo (B{deprecated}).  Use the
233     L{iterator operator []<__iter__>} instead.
234     @rtype: list of IpoCurves
235     @return: A list (possibly empty) containing all the IpoCurves associated
236     to the Ipo object.
237     """
238
239   def getCurve(curve):
240     """
241     Return the specified IpoCurve (B{deprecated}).  Use the L{mapping
242     operator B{[]}<__getitem__>} instead.
243     If the curve does not exist in the Ipo,
244     None is returned.  I{curve} can be either a string or an integer,
245     denoting either the name of the Ipo curve or its internal adrcode.
246     The possible Ipo curve names are:
247     
248       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
249       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
250       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
251       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
252       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
253       Disp.
254       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
255       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
256       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
257       RDamp, Perm.
258       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
259       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
260       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
261       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
262       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
263       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
264       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
265       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
266       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
267       MgOff, MgGain, NBase1, NBase2.
268       7. Curve Ipo: Speed.
269       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
270       QuatZ, QuatW.
271       9. Sequence Ipo: Fac.
272       10. Constraint Ipo: Inf.
273
274     The adrcode for the Ipo curve can also be given; this is useful for
275     accessing curves for Shape Key Ipos.  The adrcodes for Shape Key Ipo are
276     numbered consecutively starting at 0.
277     @type curve : string or int
278     @rtype: IpoCurve object
279     @return: the corresponding IpoCurve, or None.
280     @raise ValueError: I{curve} is not a valid name or adrcode for this Ipo
281     type.
282     """
283
284   def addCurve(curvename):
285     """
286     Add a new curve to the Ipo object. The possible values for I{curvename} are:
287       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
288       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
289       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
290       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
291       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
292       Disp.
293       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
294       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
295       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
296       RDamp, Perm.
297       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
298       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
299       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
300       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
301       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
302       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
303       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
304       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
305       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
306       MgOff, MgGain, NBase1, NBase2.
307       7. Curve Ipo: Speed.
308       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
309       QuatZ, QuatW.
310       9. Sequence Ipo: Fac.
311       10. Constraint Ipo: Inf.
312
313     @type curvename : string
314     @rtype: IpoCurve object
315     @return: the corresponding IpoCurve, or None.
316     @raise ValueError: I{curvename} is not valid or already exists
317     """
318
319   def delCurve(curvename):
320     """
321     Delete an existing curve from the Ipo object (B{deprecated}).
322     Use the L{mapping operator B{[]}<__getitem__>} instead::
323        from Blender import Ipo
324
325        ipo = Ipo.Get('ObIpo')
326        ipo[Ipo.LOCX] = None
327
328     @type curvename : string
329     @rtype: None
330     @return: None.
331     """
332
333   def getBlocktype():
334     """
335     Gets the blocktype of the Ipo.
336     @rtype: int
337     @return: the blocktype of the Ipo.
338     """
339
340   def setBlocktype(newblocktype):
341     """
342     Sets the blocktype of the Ipo.
343     @type newblocktype: int 
344     @rtype: None
345     @return: None
346     @warn: 'newblocktype' should not be changed unless you really know what
347        you are doing ...
348     """
349
350   def getRctf():
351     """
352     Gets the rctf of the Ipo.
353     Kind of bounding box...
354     @rtype: list of floats
355     @return: the rctf of the Ipo.
356     """
357
358   def setRctf(newrctf):
359     """
360     Sets the rctf of the Ipo.
361     @type newrctf: four floats.
362     @rtype: None
363     @return: None
364     @warn: rctf should not be changed unless you really know what you are
365        doing ...
366     """
367
368   def getNcurves():
369     """
370     Gets the number of curves of the Ipo (B{deprecated}).  Use
371     L{len(ipo)<__len__>} instead.
372     @rtype: int 
373     @return: the number of curve of the Ipo.
374     """
375     
376   def getCurveBP(curvepos):
377     """
378     This method is unsupported.  BPoint Ipo curves are not implemented.
379     Calling this method throws a NotImplementedError exception.
380     @raise NotImplementedError: this method B{always} raises an exception
381     """
382  
383   def getBeztriple(curvepos,pointpos):
384     """
385     Gets a beztriple of the Ipo (B{deprecated}).  B{Note}:
386     Use L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} instead.
387     @type curvepos: int
388     @param curvepos: the position of the curve in the Ipo.
389     @type pointpos: int
390     @param pointpos: the position of the point in the curve.
391     @rtype: list of 9 floats
392     @return: the beztriple of the Ipo, or an error is raised.
393     """
394
395   def setBeztriple(curvepos,pointpos,newbeztriple):
396     """
397     Sets the beztriple of the Ipo (B{deprecated}).  B{Note}: use 
398     L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} to get a
399     BezTriple point, then use the
400     L{BezTriple} API to set the point's attributes.
401     @type curvepos: int
402     @param curvepos: the position of the curve in the Ipo.
403     @type pointpos: int
404     @param pointpos: the position of the point in the curve.
405     @type newbeztriple: list of 9 floats
406     @param newbeztriple: the new value for the point
407     @rtype: None
408     @return: None
409     """
410     
411   def getCurveCurval(curvepos):
412     """
413     Gets the current value of a curve of the Ipo (B{deprecated}). B{Note}:
414     new scripts should use L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
415     @type curvepos: int or string
416     @param curvepos: the position of the curve in the Ipo or the name of the
417         curve
418     @rtype: float
419     @return: the current value of the selected curve of the Ipo.
420     """
421
422   def EvaluateCurveOn(curvepos,time):
423     """
424     Gets the value at a specific time of a curve of the Ipo (B{deprecated}).
425     B{Note}: new scripts should use 
426     L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
427     @type curvepos: int
428     @param curvepos: the position of the curve in the Ipo.
429     @type time: float
430     @param time: the desired time.
431     @rtype: float
432     @return: the current value of the selected curve of the Ipo at the given
433     time.
434     """
435