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