Fix for bug [#13479] Particle system "corrupts" when changing material colour and...
[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}: 
7         -  Ipo updates to both the program and Bpython access.
8         -  access to Blender's new Ipo driver capabilities.
9         -  Ipo now supports the mapping operator [] to access IpoCurves
10
11 This module provides access to the Ipo Data in Blender. An Ipo is composed of
12 several IpoCurves, and an IpoCurve is composed of several BezTriples.
13
14 Example::
15         from Blender import Ipo
16
17         ipo = Ipo.Get('ObIpo')                          # retrieves an Ipo object
18         ipo.name = 'ipo1'                                       # change the Ipo's name
19         icu = ipo[Ipo.OB_LOCX]                          # request X Location Ipo curve
20         if icu != None and len(icu.bezierPoints) > 0: # if curve exists and has BezTriple points
21                 val = icu[2.5]                                  # get the curve's value at time 2.5
22                 ipo[Ipo.OB_LOCX] = None                 # delete the Ipo curve
23         
24 Each type of Ipo has different types Ipocurves.  With the exception of Shape
25 Key Ipos, constants are used to specify all Ipocurves.  There are two ways
26 to tell which Ipo curves go with which Ipo type:
27         - all constants start with a two-character identifier for their Ipo type;
28         for example, "OB_LOCX" is the LocX curve for an Object Ipo
29         - each Ipo now has a read-only attribute L{Ipo.curveConsts}, which returns 
30         the valid Ipo curve types for that specific Ipo
31
32 The valid IpoCurve constants are:
33                         1. Material Ipo: MA_R, MA_G, MA_B, MA_SPECR, MA_SPECG, MA_SPECB,
34                         MA_MIRR, MA_MIRG, MA_MIRB, MA_REF, MA_ALPHA, MA_EMIT, MA_AMB,
35                         MA_SPEC, MA_HARD, MA_SPTRA, MA_IOR, MA_MODE, MA_HASIZE, MA_TRANSLU,
36                         MA_RAYMIR, MA_FRESMIR, MA_FRESMIRI, MA_FRESTRA, MA_FRESTRAI,
37                         MA_TRAGLOW, MA_OFSX, MA_OFSY, MA_OFSZ, MA_SIZEX, MA_SIZEY, MA_SIZEZ,
38                         MA_TEXR, MA_TEXG, MA_TEXB, MA_DEFVAR, MA_COL, MA_NOR, MA_VAR, MA_DISP
39                         2. Lamp Ipo: LA_ENERG, LA_R, LA_G, LA_B, LA_DIST, LA_SPOSI, LA_SPOBL,
40                         LA_QUAD1, LA_QUAD2, LA_HAINT, LA_OFSX, LA_OFSY, LA_OFSZ, LA_SIZEX,
41                         LA_SIZEY, LA_SIZEZ, LA_TEXR, LA_TEXG, LA_TEXB, LA_DEFVAR, LA_COL
42                         3. World Ipo: WO_HORR, WO_HORG, WO_HORB, WO_ZENR, WO_ZENG, WO_ZENB,
43                         WO_EXPOS, WO_MISI, WO_MISDI, WO_MISSTA, WO_MISHI, WO_STARR,
44                         WO_STARB, WO_STARG, WO_STARDI, WO_STARSI, WO_OFSX, WO_OFSY,
45                         WO_OFSZ, WO_SIZEX, WO_SIZEY, WO_SIZEZ, WO_TEXR, WO_TEXG,
46                         WO_TEXB, WO_DEFVAR, WO_COL, WO_NOR, WO_VAR
47                         4. Camera Ipo: CA_LENS, CA_CLSTA, CA_CLEND, CA_APERT, CA_FDIST
48                         5. Object Ipo: OB_LOCX, OB_LOCY, OB_LOCZ, OB_DLOCX, OB_DLOCY, OB_DLOCZ,
49                         OB_ROTX, OB_ROTY, OB_ROTZ, OB_DROTX, OB_DROTY, OB_DROTZ,
50                         OB_SCALEX, OB_SCALEY, OB_SCALEZ, OB_DSCALEX, OB_DSCALEY, OB_DSCALEZ,
51                         OB_LAYER, OB_TIME, OB_COLR, OB_COLG, OB_COLB, OB_COLA,
52                         OB_FSTRENG, OB_FFALL, OB_RDAMP, OB_DAMPING, OB_PERM
53                         6. Curve Ipo: CU_SPEED
54                         7. Constraint Ipo: CO_INF
55                         8. Texture Ipo: TE_NSIZE, TE_NDEPTH, TE_NTYPE, TE_TURB, TE_VNW1, TE_VNW2,
56                         TE_VNW3, TE_VNW4, TE_MINKMEXP, TE_DISTM, TE_COLT, TE_ISCALE,
57                         TE_DISTA, TE_MGTYPE, TE_MGH, TE_LACU, TE_OCT, TE_MGOFF,
58                         TE_MGGAIN, TE_NBASE1, TE_NBASE2, TE_COLR, TE_COLG, TE_COLB,
59                         TE_BRIGHT, TE_CONTRAS
60                         9. Pose/Action Ipo: PO_LOCX, PO_LOCY, PO_LOCZ, PO_SIZEX, PO_SIZEY,
61                         PO_SIZEZ, PO_QUATW, PO_QUATX, PO_QUATY, PO_QUATZ
62                         10. Sequence Ipo: SQ_FAC
63
64 Shape Key Ipos are handled differently from other Ipos.  The user can rename
65 the curves, so string are used to access them instead of constants.  The
66 L{Ipo.curveConsts} attribute for Shape Key Ipos returns a list of all defined
67 key names.
68 """
69
70 def New (type, name):
71         """
72         Creates a new Ipo.
73         @type type: string
74         @type name: string
75         @param type: The Ipo's blocktype. Depends on the object the Ipo will be
76                         linked to. Currently supported types are Object, Camera, World,
77                         Material, Texture, Lamp, Action, Constraint, Sequence, Curve, Key.
78         @param name: The name for this Ipo.
79         @rtype: Blender Ipo
80         @return: The created Ipo.
81         """
82
83 def Get (name = None):
84         """
85         Get the Ipo from Blender.
86         @type name: string
87         @param name: The name of the requested Ipo, or nothing.
88         @rtype: Blender Ipo or a list of Blender Ipos
89         @return: It depends on the 'name' parameter:
90                         - (name): The Ipo with the given name;
91                         - (): A list with all Ipos in the current scene.
92         """
93
94 class Ipo:
95         """
96         The Ipo object
97         ==============
98         This object gives access to Ipo data from all objects in Blender.
99         @Note: Blender Materials, Lamps and Worlds have I{texture channels} which
100         allow the user to assign textures to them.  The Blender Ipo Window allows
101         the user to access the IpoCurves for these channels by specifying a number
102         between 0 and 9 (the number appears next to the Ipo type in the window
103         header).  Prior to Version 2.42, the BPy API did not allow users to access
104         these texture channels in a predictable manner.  A new attribute named
105         L{channel} was added to the API in Version 2.42 to correct this problem.
106
107         The current channel setting has an effect on the operators B{[]}, B{len()} 
108         and others.  For example, suppose a Material has three IpoCurves 
109         (R, G, and B), and two texture channels (numbered 0 and 1), and furthermore
110         channel 0 has one Ipocurve (Col).  The IpoCurve Col can only be
111         "seen" through the API when B{ipo.channel} is 0.  Setting B{ipo.channel} to
112         1 will cause this curve to be ignored by B{len(ipo)}::
113
114                 from Blender import Ipo
115
116                 ipo = Ipo.Get('MatIpo')
117                 for channel in xrange(2):
118                                 ipo.channel = channel
119                                 print 'channel is',channel
120                                 print ' len is',len(ipo)
121                                 names = dict([(x[1],x[0]) for x in ipo.curveConsts.items()])
122                                 for curve in [Ipo.MA_R,Ipo.MA_COL]:
123                                                 print ' ',names[curve],'is',curve in ipo
124
125         will output::
126                 channel is 0
127                 len is 4
128                         MA_R is True
129                         MA_COL is True
130                 channel is 1
131                 len is 3
132                         MA_R is True
133                         MA_COL is False
134
135         @ivar curves: Ipo curves currently defined for the Ipo.
136         @type curves: list of Ipocurves.
137         @ivar curveConsts: The valid Ipo curves for this Ipo.  These can be used
138         by the [] mapping operator.  The value 
139         depends on the Ipo curve type.  If the Ipo is any type other than a Key or
140         Shape Ipo, this attribute returns a set of constants that can be
141         used to specify a particular curve.  For Key or Shape Ipos, the attribute
142         returns a list of all defined keys by name.  
143         @type curveConsts: constant or list of strings. Read-only.
144         @ivar channel: the current texture channel for Blender object which support
145         textures (materials, lamps and worlds).  Returns None if the Ipo does
146         not support texture channels. Value must be in the range [0,9].
147         @type channel: int or None
148         """
149
150         def __contains__():
151                 """
152                 The "in" operator for Ipos. It returns B{True} if the specified 
153                 IpoCurve exists for the Ipo.  This operator B{should not} be used to 
154                 test for whether a curve constant is valid for a particular Ipo type.
155                 Many constants for different Ipo types have the same value, and it is
156                 the constant's value used internally.
157                 No exceptions are raised if the argument is not a valid curve constant or
158                 or string, nor does the operator return B{True} when the curve
159                 constant is valid but does not currently exist.  As such, it should only be
160                 used to test for specific curves when the Ipo type is known::
161                         ipo = Object.Get('Cube').ipo # get Object-type Ipo 
162                         if ipo:
163                                 print Ipo.OB_LOCX in ipo # prints "True" if 'LocX' curve exists
164                                 print Ipo.MA_R in ipo    # also prints "True" since MA_R and OB_LOCX are have the same value
165                                 print 'hiccup' in ipo    # always prints "False" since argument is not a constant
166
167                 @return: see above.
168                 @rtype: Boolean
169                 """
170
171         def __getitem__():
172                 """
173                 This operator is similar to the Python dictionary mapping operator [],
174                 except that the user cannot assign arbitrary keys.  Each Ipo type has
175                 a pre-defined set of IpoCurves which may or may not exist at a given time.      This operator
176                 will either return an IpoCurve object if the specified curve exists,
177                 return None if the curve does not exists, or throws a KeyError exception
178                 if the curve is not valid for this Ipo type.
179                 @return: an IpoCurve object if it exists
180                 @rtype: IpoCurve or None
181                 @raise KeyError: an undefined IpoCurve was specified for the Ipo
182                 """
183
184         def __iter__():
185                 """
186                 Iterator for Ipos.  It returns all the defined IpoCurve objects associated 
187                 with the Ipo.  For example::
188                         from Blender import Ipo
189
190                         ipo = Ipo.Get()
191                         if len(ipo) > 0:
192                                 ipo = ipo[0]
193                                 print 'ipo name is',ipo.name
194                                 for icu in ipo:
195                                         print ' curve name is',icu.name
196                 might result in::
197                         ipo name is ObIpo
198                                 curve name is LocX
199                                 curve name is LocY
200                                 curve name is LocZ
201
202                 @return: an IpoCurve object
203                 @rtype: IpoCurve
204                 """
205
206         def __len__():
207                 """
208                 Returns the number of curves defined for the Ipo.
209                 @return: number of defined IpoCurves
210                 @rtype: int
211                 """
212
213         def getName():
214                 """
215                 Gets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
216                 @rtype: string
217                 @return: the name of the Ipo.
218                 """
219
220         def setName(newname):
221                 """
222                 Sets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
223                 @type newname: string
224                 @rtype: None
225                 @return: None
226                 """
227
228         def getCurves():
229                 """
230                 Gets all the IpoCurves of the Ipo (B{deprecated}).  Use the
231                 L{iterator operator []<__iter__>} instead.
232                 @rtype: list of IpoCurves
233                 @return: A list (possibly empty) containing all the IpoCurves associated
234                 to the Ipo object.
235                 """
236
237         def getCurve(curve):
238                 """
239                 Return the specified IpoCurve (B{deprecated}).  Use the L{mapping
240                 operator B{[]}<__getitem__>} instead.
241                 If the curve does not exist in the Ipo,
242                 None is returned.  I{curve} can be either a string or an integer,
243                 denoting either the name of the Ipo curve or its internal adrcode.
244                 The possible Ipo curve names are:
245                 
246                         1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
247                         2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
248                         Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
249                         RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
250                         OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
251                         Disp.
252                         3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
253                         dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
254                         Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
255                         RDamp, Perm.
256                         4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
257                         5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
258                         MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
259                         SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
260                         5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
261                         MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
262                         SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
263                         6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
264                         MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
265                         MgOff, MgGain, NBase1, NBase2.
266                         7. Curve Ipo: Speed.
267                         8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
268                         QuatZ, QuatW.
269                         9. Sequence Ipo: Fac.
270                         10. Constraint Ipo: Inf.
271
272                 The adrcode for the Ipo curve can also be given; this is useful for
273                 accessing curves for Shape Key Ipos.  The adrcodes for Shape Key Ipo are
274                 numbered consecutively starting at 0.
275                 @type curve : string or int
276                 @rtype: IpoCurve object
277                 @return: the corresponding IpoCurve, or None.
278                 @raise ValueError: I{curve} is not a valid name or adrcode for this Ipo
279                 type.
280                 """
281
282         def addCurve(curvename):
283                 """
284                 Add a new curve to the Ipo object. The possible values for I{curvename} are:
285                         1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
286                         2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
287                         Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
288                         RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
289                         OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
290                         Disp.
291                         3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
292                         dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
293                         Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
294                         RDamp, Perm.
295                         4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
296                         5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
297                         MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
298                         SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
299                         5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
300                         MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
301                         SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
302                         6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
303                         MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
304                         MgOff, MgGain, NBase1, NBase2.
305                         7. Curve Ipo: Speed.
306                         8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
307                         QuatZ, QuatW.
308                         9. Sequence Ipo: Fac.
309                         10. Constraint Ipo: Inf.
310
311                 For Key IPOs, the name must be an existing KeyBlock name.  Use
312                 L{curveConsts} to determine the set of valid names.
313
314                 @type curvename : string
315                 @rtype: IpoCurve object
316                 @return: the corresponding IpoCurve, or None.
317                 @raise ValueError: I{curvename} is not valid or already exists
318                 """
319
320         def delCurve(curvename):
321                 """
322                 Delete an existing curve from the Ipo object (B{deprecated}).
323                 Use the L{mapping operator B{[]}<__getitem__>} instead::
324                          from Blender import Ipo
325
326                          ipo = Ipo.Get('ObIpo')
327                          ipo[Ipo.LOCX] = None
328
329                 @type curvename : string
330                 @rtype: None
331                 @return: None.
332                 """
333
334         def getBlocktype():
335                 """
336                 Gets the blocktype of the Ipo.
337                 @rtype: int
338                 @return: the blocktype of the Ipo.
339                 """
340
341         def setBlocktype(newblocktype):
342                 """
343                 Sets the blocktype of the Ipo.
344                 @type newblocktype: int 
345                 @rtype: None
346                 @return: None
347                 @warn: 'newblocktype' should not be changed unless you really know what
348                          you are doing ...
349                 """
350
351         def getRctf():
352                 """
353                 Gets the rctf of the Ipo.
354                 Kind of bounding box...
355                 @rtype: list of floats
356                 @return: the rctf of the Ipo.
357                 """
358
359         def setRctf(newrctf):
360                 """
361                 Sets the rctf of the Ipo.
362                 @type newrctf: four floats.
363                 @rtype: None
364                 @return: None
365                 @warn: rctf should not be changed unless you really know what you are
366                          doing ...
367                 """
368
369         def getNcurves():
370                 """
371                 Gets the number of curves of the Ipo (B{deprecated}).  Use
372                 L{len(ipo)<__len__>} instead.
373                 @rtype: int 
374                 @return: the number of curve of the Ipo.
375                 """
376                 
377         def getCurveBP(curvepos):
378                 """
379                 This method is unsupported.  BPoint Ipo curves are not implemented.
380                 Calling this method throws a NotImplementedError exception.
381                 @raise NotImplementedError: this method B{always} raises an exception
382                 """
383
384         def getBeztriple(curvepos,pointpos):
385                 """
386                 Gets a beztriple of the Ipo (B{deprecated}).  B{Note}:
387                 Use L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} instead.
388                 @type curvepos: int
389                 @param curvepos: the position of the curve in the Ipo.
390                 @type pointpos: int
391                 @param pointpos: the position of the point in the curve.
392                 @rtype: list of 9 floats
393                 @return: the beztriple of the Ipo, or an error is raised.
394                 """
395
396         def setBeztriple(curvepos,pointpos,newbeztriple):
397                 """
398                 Sets the beztriple of the Ipo (B{deprecated}).  B{Note}: use 
399                 L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} to get a
400                 BezTriple point, then use the
401                 L{BezTriple} API to set the point's attributes.
402                 @type curvepos: int
403                 @param curvepos: the position of the curve in the Ipo.
404                 @type pointpos: int
405                 @param pointpos: the position of the point in the curve.
406                 @type newbeztriple: list of 9 floats
407                 @param newbeztriple: the new value for the point
408                 @rtype: None
409                 @return: None
410                 """
411                 
412         def getCurveCurval(curvepos):
413                 """
414                 Gets the current value of a curve of the Ipo (B{deprecated}). B{Note}:
415                 new scripts should use L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
416                 @type curvepos: int or string
417                 @param curvepos: the position of the curve in the Ipo or the name of the
418                                 curve
419                 @rtype: float
420                 @return: the current value of the selected curve of the Ipo.
421                 """
422
423         def EvaluateCurveOn(curvepos,time):
424                 """
425                 Gets the value at a specific time of a curve of the Ipo (B{deprecated}).
426                 B{Note}: new scripts should use 
427                 L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
428                 @type curvepos: int
429                 @param curvepos: the position of the curve in the Ipo.
430                 @type time: float
431                 @param time: the desired time.
432                 @rtype: float
433                 @return: the current value of the selected curve of the Ipo at the given
434                 time.
435                 """
436 import id_generics
437 Ipo.__doc__ += id_generics.attributes