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