Orange; merger with bf-blender.
[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     """
301
302   def getExtrapolation():
303     """
304     Gets the extend mode of the curve.
305     @rtype: string
306     @return: the extend mode of the curve. Can be Constant, Extrapolation, Cyclic or Cyclic_extrapolation.
307     """
308     
309
310   def setInterpolation(interpolationtype):
311     """
312     Sets the interpolation type of the curve.
313     @type interpolationtype: string
314     @param interpolationtype: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
315     @rtype: None
316     @return: None
317     """
318   def getInterpolation():
319     """
320     Gets the interpolation type of the curve.
321     @rtype: string
322     @return: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
323     """
324     
325   def addBezier(coordlist):
326     """
327     Adds a Bezier point to a curve.
328     @type coordlist: tuple of (at least) 2 floats
329     @param coordlist: the x and y coordinates of the new Bezier point.
330     @rtype: None
331     @return: None
332     """
333  
334   def delBezier(index):
335     """
336     Deletes a Bezier point from a curve.
337     @type index: integer
338     @param index: the index of the Bezier point.  Negative values index from the end of the list.
339     @rtype: None
340     @return: None
341     """
342
343   def recalc():
344     """
345     Recomputes the curve after changes to control points.
346     @rtype: None
347     @return: None
348     """
349
350   def getName():
351     """
352     Returns the name of the Ipo curve. This name can be:
353       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
354       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
355       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
356       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
357       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
358       Disp.
359       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
360       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
361       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
362       RDamp, Perm.
363       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
364       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
365       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
366       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
367       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
368       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
369       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
370       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
371       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
372       MgOff, MgGain, NBase1, NBase2.
373       7. Curve Ipo: Speed.
374       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
375       QuatZ, QuatW.
376       9. Sequence Ipo: Fac.
377       10. Constraint Ipo: Inf.
378
379     @rtype: string
380     @return: the name of the Ipo curve.
381     """
382
383   def getPoints():
384     """
385     Returns all the points of the Ipo curve.
386     @rtype: list of BezTriples
387     @return: the points of the Ipo curve.
388     """
389
390   def evaluate( time ):
391     """
392     Compute the value of the Ipo curve at a particular time.
393     @type time: float
394     @param time: value along the X axis
395     @rtype: float
396     @return: the Y value of the curve at the given time
397     """
398
399
400 class BezTriple:
401   """
402   The BezTriple object
403   ====================
404   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.
405   @ivar pt : the [x,y] coordinates for knot point of this BezTriple.  Read-only.
406   @type pt: list of floats
407   @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.
408   @type vec: list of points
409   @ivar hide: the visibility status of the control point.
410   @type hide: int
411   """
412
413   def __init__(coords):
414     """
415     Create a new BezTriple object.  
416
417     @type coords: sequence of three or nine floats
418     @param coords: the coordinate values for the new control point.  If three
419     floats are given, then the handle values are automatically generated.
420     @rtype: BezTriple
421     @return: a new BezTriple object
422     """
423
424   def getPoints():
425     """
426     Returns the xy coordinates of the Bezier knot point.
427     @rtype: list of floats
428     @return: list of the x and y coordinates of the Bezier point.
429     """
430
431   def setPoints(newval):
432     """
433     Sets the point xy coordinates of the Bezier knot point.  After changing
434     coordinates, it is advisable to call L{IpoCurve.recalc()} to update the
435     Ipo curves.
436     @type newval: tuple of 2 floats
437     @param newval: the x and y coordinates of the new Bezier point.
438     @rtype: None
439     @return: None
440     """
441
442   def getTriple():
443     """
444     Returns the x,y,z coordinates for each of the three points that make up
445     a BezierTriple.
446
447     The return list looks like this [ [H1x, H1y, H1z], [Px, Py, Pz],
448     [H2x, H2y, H2z] ] .
449
450     Example::
451       # where bt is of type BezierTriple
452       #  and h1, p, and h2 are lists of 3 floats
453       h1, p, h2 = bt.getTriple()
454     
455     @rtype: list consisting of 3 lists of 3 floats
456     @return: handle1, knot, handle2
457     """