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