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