Final merge of HEAD (bf-blender) into the orange branch.
[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
10 This module provides access to the Ipo Data in Blender. An Ipo is composed of
11 several IpoCurves.
12
13 A datatype is defined : IpoCurve type. The member functions of this data type
14 are given below.
15
16
17 Example::
18   import Blender
19   ob = Blender.Ipo.Get('ipo')    # retrieves an Ipo object
20   ob.setName('ipo1')
21   print ob.name
22   print ipo.getRctf()
23   ipo.setRctf(1,2,3,4)
24   
25 """
26
27 def New (type, name):
28   """
29   Creates a new Ipo.
30   @type type: string
31   @type name: string
32   @param type: The Ipo's blocktype. Depends on the object the Ipo will be
33       linked to. Currently supported types are Object, Camera, World,
34       Material, Texture, Lamp, Action, Constraint, Sequence, Curve, Key.
35   @param name: The name for this Ipo.
36   @rtype: Blender Ipo
37   @return: The created Ipo.
38   """
39
40 def Get (name = None):
41   """
42   Get the Ipo from Blender.
43   @type name: string
44   @param name: The name of the requested Ipo, or nothing.
45   @rtype: Blender Ipo or a list of Blender Ipos
46   @return: It depends on the 'name' parameter:
47       - (name): The Ipo with the given name;
48       - ():     A list with all Ipos in the current scene.
49   """
50
51 class Ipo:
52   """
53   The Ipo object
54   ==============
55   This object gives access to generic data from all objects in Blender.
56   It has no attributes.
57   """
58
59   def getName():
60     """
61     Gets the name of the Ipo.
62     @rtype: string
63     @return: the name of the Ipo.
64     """
65
66   def getCurves():
67     """
68     Gets all the IpoCurves of the Ipo.
69     @rtype: list of IpoCurves
70     @return: A list (possibly void) containing all the IpoCurves associated to the Ipo object.
71     """
72
73   def getCurve(curve):
74     """
75     Return the specified IpoCurve.  If the curve does not exist in the Ipo,
76     None is returned.  I{curve} can be either a string or an integer,
77     denoting either the name of the Ipo curve or its internal adrcode.
78     The possible Ipo curve names are:
79     
80       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
81       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
82       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
83       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
84       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
85       Disp.
86       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
87       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
88       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
89       RDamp, Perm.
90       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
91       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
92       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
93       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
94       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
95       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
96       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
97       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
98       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
99       MgOff, MgGain, NBase1, NBase2.
100       7. Curve Ipo: Speed.
101       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
102       QuatZ, QuatW.
103       9. Sequence Ipo: Fac.
104       10. Constraint Ipo: Inf.
105
106     The adrcode for the Ipo curve can also be given; currently this is the
107     only way to access curves for Key Ipos.  The adrcodes for Key Ipo are
108     numbered consecutively starting at 0.
109     @type curve : string or int
110     @rtype: IpoCurve object
111     @return: the corresponding IpoCurve, or None.
112     @raise ValueError: I{curve} is not a valid name or adrcode for this Ipo
113     type.
114     """
115
116   def addCurve(curvename):
117     """
118     Add a new curve to the Ipo object. The possible values for I{curvename} are:
119       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
120       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
121       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
122       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
123       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
124       Disp.
125       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
126       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
127       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
128       RDamp, Perm.
129       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
130       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
131       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
132       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
133       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
134       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
135       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
136       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
137       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
138       MgOff, MgGain, NBase1, NBase2.
139       7. Curve Ipo: Speed.
140       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
141       QuatZ, QuatW.
142       9. Sequence Ipo: Fac.
143       10. Constraint Ipo: Inf.
144
145     @type curvename : string
146     @rtype: IpoCurve object
147     @return: the corresponding IpoCurve, or None.
148     @raise ValueError: I{curvename} is not valid or already exists
149     """
150
151   def delCurve(curvename):
152     """
153     Delete an existing curve from the Ipo object. See addCurve() for possible values for curvename.
154     @type curvename : string
155     @rtype: None
156     @return: None.
157     """
158
159   def setName(newname):
160     """
161     Sets the name of the Ipo.
162     @type newname: string
163     @rtype: None
164     @return: None
165     """
166
167   def getBlocktype():
168     """
169     Gets the blocktype of the Ipo.
170     @rtype: int
171     @return: the blocktype of the Ipo.
172     """
173
174   def setBlocktype(newblocktype):
175     """
176     Sets the blocktype of the Ipo.
177     @type newblocktype: int 
178     @rtype: None
179     @return: None
180     @warn: 'newblocktype' should not be changed unless you really know what
181        you are doing ...
182     """
183
184   def getRctf():
185     """
186     Gets the rctf of the Ipo.
187     Kind of bounding box...
188     @rtype: list of floats
189     @return: the rctf of the Ipo.
190     """
191
192   def setRctf(newrctf):
193     """
194     Sets the rctf of the Ipo.
195     @type newrctf: four floats.
196     @rtype: None
197     @return: None
198     @warn: rctf should not be changed unless you really know what you are
199        doing ...
200     """
201
202   def getNcurves():
203     """
204     Gets the number of curves of the Ipo.
205     @rtype: int 
206     @return: the number of curve of the Ipo.
207     """
208     
209   def getCurveBP(curvepos):
210     """
211     This method is unsupported.  BPoint Ipo curves are not implemented.
212     Calling this method throws a NotImplementedError exception.
213     @raise NotImplementedError: this method B{always} raises an exception
214     """
215  
216   def getBeztriple(curvepos,pointpos):
217     """
218     Gets a beztriple of the Ipo.
219     @type curvepos: int
220     @param curvepos: the position of the curve in the Ipo.
221     @type pointpos: int
222     @param pointpos: the position of the point in the curve.
223     @rtype: list of 9 floats
224     @return: the beztriple of the Ipo, or an error is raised.
225     """
226
227   def setBeztriple(curvepos,pointpos,newbeztriple):
228     """
229     Sets the beztriple of the Ipo.
230     @type curvepos: int
231     @param curvepos: the position of the curve in the Ipo.
232     @type pointpos: int
233     @param pointpos: the position of the point in the curve.
234     @type newbeztriple: list of 9 floats
235     @param newbeztriple: the new value for the point
236     @rtype: None
237     @return: None
238     """
239     
240   def getCurveCurval(curvepos):
241     """
242     Gets the current value of a curve of the Ipo (B{deprecated}). B{Note}:
243     new scripts should use L{IpoCurve.evaluate()}.
244     @type curvepos: int or string
245     @param curvepos: the position of the curve in the Ipo or the name of the
246         curve
247     @rtype: float
248     @return: the current value of the selected curve of the Ipo.
249     """
250
251   def EvaluateCurveOn(curvepos,time):
252     """
253     Gets the value at a specific time of a curve of the Ipo (B{deprecated}).
254     B{Note}: new scripts should use L{IpoCurve.evaluate()}.
255     @type curvepos: int
256     @param curvepos: the position of the curve in the Ipo.
257     @type time: float
258     @param time: the desired time.
259     @rtype: float
260     @return: the current value of the selected curve of the Ipo at the given
261         time.
262     """
263
264 class IpoCurve:
265   """
266   The IpoCurve object
267   ===================
268   This object gives access to generic data from all Ipo curves objects in Blender.
269
270   Important Notes for Rotation Ipo Curves:\n
271   For the rotation Ipo curves, the y values for points are in units of 10
272   degrees.  For example, 45.0 degrees is stored as 4.50 degrees.  These are the
273   same numbers you see in the Transform Properties pop-up menu ( NKey ) in
274   the IPO Curve Editor window.  Positive rotations are in a counter-clockwise
275   direction, following the standard convention.
276   
277   @ivar driver:  Status of the driver.  1= on, 0= off.
278   @type driver:  int
279   @ivar driverObject:  Object used to drive the Ipo curve.
280   @type driverObject:  Blender Object or None
281   @ivar driverChannel:  Object channel used to drive the Ipo curve.
282   Use module constants: IpoCurve.LOC_X, IpoCurve.LOC_Y, IpoCurve.LOC_Z,
283   IpoCurve.ROT_X, IpoCurve.ROT_Y, IpoCurve.ROT_Z, IpoCurve.SIZE_X,
284   IpoCurve.SIZE_Y, IpoCurve.SIZE_Z
285   @type driverChannel:  int 
286   @ivar name: The IpoCurve data name.
287   @type name: string
288   @ivar bezierPoints : The list of the curve's bezier points.
289   @type bezierPoints : list
290   """
291
292   def setExtrapolation(extendmode):
293     """
294     Sets the extend mode of the curve.
295     @type extendmode: string
296     @param extendmode: the extend mode of the curve.
297         Can be Constant, Extrapolation, Cyclic or Cyclic_extrapolation.
298     @rtype: None
299     @return: None
300     @note: Cyclic Ipo curves never reach the end value.  If the first and
301     last bezier points do not have the same y coordinate, the value of the
302     curve when it "cycles" is that of the first point.  If a user wants to
303     get the value of the final curve point, read the final point from the
304     curve's L{bezierPoints} attribute::
305
306                 ipo = Blender.Object.Get('Cube').ipo
307                 icu = ipo.getCurves('LocX')
308                 endtime,endvalue = icu.bezierPoints[-1].pt
309
310     """
311
312   def getExtrapolation():
313     """
314     Gets the extend mode of the curve.
315     @rtype: string
316     @return: the extend mode of the curve. Can be Constant, Extrapolation, Cyclic or Cyclic_extrapolation.
317     """
318     
319
320   def setInterpolation(interpolationtype):
321     """
322     Sets the interpolation type of the curve.
323     @type interpolationtype: string
324     @param interpolationtype: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
325     @rtype: None
326     @return: None
327     """
328   def getInterpolation():
329     """
330     Gets the interpolation type of the curve.
331     @rtype: string
332     @return: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
333     """
334     
335   def addBezier(coordlist):
336     """
337     Adds a Bezier point to a curve.
338     @type coordlist: tuple of (at least) 2 floats
339     @param coordlist: the x and y coordinates of the new Bezier point.
340     @rtype: None
341     @return: None
342     """
343  
344   def delBezier(index):
345     """
346     Deletes a Bezier point from a curve.
347     @type index: integer
348     @param index: the index of the Bezier point.  Negative values index from the end of the list.
349     @rtype: None
350     @return: None
351     """
352
353   def recalc():
354     """
355     Recomputes the curve after changes to control points.
356     @rtype: None
357     @return: None
358     """
359
360   def getName():
361     """
362     Returns the name of the Ipo curve. This name can be:
363       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
364       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
365       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
366       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
367       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
368       Disp.
369       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
370       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
371       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
372       RDamp, Perm.
373       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
374       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
375       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
376       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
377       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
378       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
379       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
380       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
381       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
382       MgOff, MgGain, NBase1, NBase2.
383       7. Curve Ipo: Speed.
384       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
385       QuatZ, QuatW.
386       9. Sequence Ipo: Fac.
387       10. Constraint Ipo: Inf.
388
389     @rtype: string
390     @return: the name of the Ipo curve.
391     """
392
393   def getPoints():
394     """
395     Returns all the points of the Ipo curve.
396     @rtype: list of BezTriples
397     @return: the points of the Ipo curve.
398     """
399
400   def evaluate( time ):
401     """
402     Compute the value of the Ipo curve at a particular time.
403     @type time: float
404     @param time: value along the X axis
405     @rtype: float
406     @return: the Y value of the curve at the given time
407     """
408
409
410 class BezTriple:
411   """
412   The BezTriple object
413   ====================
414   This object gives access to generic data from all beztriple objects in Blender.  If an attribute is listed as being 'read-only' that means you cannot write to it.  Use the set*() methods instead.
415   @ivar pt : the [x,y] coordinates for knot point of this BezTriple.  Read-only.
416   @type pt: list of floats
417   @ivar vec : a list of the 3 points [ handle, knot, handle ] that comprise a BezTriple.  See the getTriple() method for an example of the format.  Read-only.
418   @type vec: list of points
419   @ivar hide: the visibility status of the control point.
420   @type hide: int
421   """
422
423   def __init__(coords):
424     """
425     Create a new BezTriple object.  
426
427     @type coords: sequence of three or nine floats
428     @param coords: the coordinate values for the new control point.  If three
429     floats are given, then the handle values are automatically generated.
430     @rtype: BezTriple
431     @return: a new BezTriple object
432     """
433
434   def getPoints():
435     """
436     Returns the xy coordinates of the Bezier knot point.
437     @rtype: list of floats
438     @return: list of the x and y coordinates of the Bezier point.
439     """
440
441   def setPoints(newval):
442     """
443     Sets the point xy coordinates of the Bezier knot point.  After changing
444     coordinates, it is advisable to call L{IpoCurve.recalc()} to update the
445     Ipo curves.
446     @type newval: tuple of 2 floats
447     @param newval: the x and y coordinates of the new Bezier point.
448     @rtype: None
449     @return: None
450     """
451
452   def getTriple():
453     """
454     Returns the x,y,z coordinates for each of the three points that make up
455     a BezierTriple.
456
457     The return list looks like this [ [H1x, H1y, H1z], [Px, Py, Pz],
458     [H2x, H2y, H2z] ] .
459
460     Example::
461       # where bt is of type BezierTriple
462       #  and h1, p, and h2 are lists of 3 floats
463       h1, p, h2 = bt.getTriple()
464     
465     @rtype: list consisting of 3 lists of 3 floats
466     @return: handle1, knot, handle2
467     """