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