← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/blender/gutsy-security

« back to all changes in this revision

Viewing changes to source/blender/python/api2_2x/doc/Ipo.py

  • Committer: Bazaar Package Importer
  • Author(s): Florian Ernst
  • Date: 2007-05-17 11:47:59 UTC
  • mfrom: (1.2.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20070517114759-yp4ybrnhp2u7pk66
Tags: 2.44-1
* New upstream release.
* Drop debian/patches/01_64bits_stupidity, not needed anymore: as of this
  version blender is 64 bits safe again. Adjust README.Debian accordingly.

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/blender/python/api2_2x/doc/Ipo.py
4
4
The Blender.Ipo submodule
5
5
 
6
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
 
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
10
 
11
11
This module provides access to the Ipo Data in Blender. An Ipo is composed of
12
12
several IpoCurves, and an IpoCurve is composed of several BezTriples.
13
13
 
14
14
Example::
15
 
  from Blender import Ipo
 
15
        from Blender import Ipo
16
16
 
17
 
  ob = Ipo.Get('ObIpo')          # retrieves an Ipo object
18
 
  ob.name = 'ipo1'                               # change the Ipo's name
19
 
  icu = ipo[Ipo.OB_LOCX]         # request X Location Ipo curve object
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
 
     icu[Ipo.OB_LOCX] = None     # delete the ipo curve
23
 
  
 
17
        ob = Ipo.Get('ObIpo')          # retrieves an Ipo object
 
18
        ob.name = 'ipo1'                                 # change the Ipo's name
 
19
        icu = ipo[Ipo.OB_LOCX]         # request X Location Ipo curve object
 
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
                 icu[Ipo.OB_LOCX] = None     # delete the ipo curve
 
23
        
24
24
Each type of Ipo has different types Ipocurves.  With the exception of Shape
25
25
Key Ipos, constants are used to specify all Ipocurves.  There are two ways
26
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
 
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
31
 
32
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_SIZEX, OB_SIZEY, OB_SIZEZ, OB_DSIZEX, OB_DSIZEY, OB_DSIZEZ,
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
 
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_SIZEX, OB_SIZEY, OB_SIZEZ, OB_DSIZEX, OB_DSIZEY, OB_DSIZEZ,
 
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
63
 
64
64
Shape Key Ipos are handled differently from other Ipos.  The user can rename
65
65
the curves, so string are used to access them instead of constants.  The
68
68
"""
69
69
 
70
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
 
  """
 
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
82
 
83
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
 
  """
 
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
93
 
94
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 name: The Ipo datablock's name
136
 
  @type name: string
137
 
  @ivar curves: Ipo curves currently defined for the Ipo.
138
 
  @type curves: list of Ipocurves.
139
 
  @ivar curveConsts: The valid Ipo curves for this Ipo.  These can be used
140
 
  by the [] mapping operator.  The value 
141
 
  depends on the Ipo curve type.  If the Ipo is any type other than a Key or
142
 
  Shape Ipo, this attribute returns a set of constants that can be
143
 
  used to specify a particular curve.  For Key or Shape Ipos, the attribute
144
 
  returns a list of all defined keys by name.  
145
 
  @type curveConsts: constant or list of strings. Read-only.
146
 
  @ivar channel: the current texture channel for Blender object which support
147
 
  textures (materials, lamps and worlds).  Returns None if the Ipo does
148
 
  not support texture channels. Value must be in the range [0,9].
149
 
  @type channel: int or None
150
 
  """
151
 
 
152
 
  def __contains__():
153
 
    """
154
 
    The "in" operator for Ipos. It returns B{True} if the specified 
155
 
    IpoCurve exists for the Ipo.  This operator B{should not} be used to 
156
 
    test for whether a curve constant is valid for a particular Ipo type.
157
 
    Many constants for different Ipo types have the same value, and it is
158
 
    the constant's value used internally.
159
 
    No exceptions are raised if the argument is not a valid curve constant or
160
 
    or string, nor does the operator return B{True} when the curve
161
 
    constant is valid but does not currently exist.  As such, it should only be
162
 
    used to test for specific curves when the Ipo type is known::
163
 
      ipo = Object.Get('Cube').ipo # get Object-type Ipo 
164
 
      if ipo:
165
 
        print Ipo.OB_LOCX in ipo # prints "True" if 'LocX' curve exists
166
 
        print Ipo.MA_R in ipo    # also prints "True" since MA_R and OB_LOCX are have the same value
167
 
        print 'hiccup' in ipo    # always prints "False" since argument is not a constant
168
 
 
169
 
    @return: see above.
170
 
    @rtype: Boolean
171
 
    """
172
 
 
173
 
  def __getitem__():
174
 
    """
175
 
    This operator is similar to the Python dictionary mapping operator [],
176
 
    except that the user cannot assign arbitrary keys.  Each Ipo type has
177
 
    a pre-defined set of IpoCurves which may or may not exist at a given time.      This operator
178
 
    will either return an IpoCurve object if the specified curve exists,
179
 
    return None if the curve does not exists, or throws a KeyError exception
180
 
    if the curve is not valid for this Ipo type.
181
 
    @return: an IpoCurve object if it exists
182
 
    @rtype: IpoCurve or None
183
 
    @raise KeyError: an undefined IpoCurve was specified for the Ipo
184
 
    """
185
 
 
186
 
  def __iter__():
187
 
    """
188
 
    Iterator for Ipos.  It returns all the defined IpoCurve objects associated 
189
 
    with the Ipo.  For example::
190
 
       from Blender import Ipo
191
 
 
192
 
       ipo = Ipo.Get()
193
 
       if len(ipo) > 0:
194
 
         ipo = ipo[0]
195
 
         print 'ipo name is',ipo.name
196
 
         for icu in ipo:
197
 
           print ' curve name is',icu.name
198
 
    might result in::
199
 
       ipo name is ObIpo
200
 
         curve name is LocX
201
 
         curve name is LocY
202
 
         curve name is LocZ
203
 
 
204
 
    @return: an IpoCurve object
205
 
    @rtype: IpoCurve
206
 
    """
207
 
 
208
 
  def __len__():
209
 
    """
210
 
    Returns the number of curves defined for the Ipo.
211
 
    @return: number of defined IpoCurves
212
 
    @rtype: int
213
 
    """
214
 
 
215
 
  def getName():
216
 
    """
217
 
    Gets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
218
 
    @rtype: string
219
 
    @return: the name of the Ipo.
220
 
    """
221
 
 
222
 
  def setName(newname):
223
 
    """
224
 
    Sets the name of the Ipo (B{deprecated}).  See the L{name} attribute.
225
 
    @type newname: string
226
 
    @rtype: None
227
 
    @return: None
228
 
    """
229
 
 
230
 
  def getCurves():
231
 
    """
232
 
    Gets all the IpoCurves of the Ipo (B{deprecated}).  Use the
233
 
    L{iterator operator []<__iter__>} instead.
234
 
    @rtype: list of IpoCurves
235
 
    @return: A list (possibly empty) containing all the IpoCurves associated
236
 
    to the Ipo object.
237
 
    """
238
 
 
239
 
  def getCurve(curve):
240
 
    """
241
 
    Return the specified IpoCurve (B{deprecated}).  Use the L{mapping
242
 
    operator B{[]}<__getitem__>} instead.
243
 
    If the curve does not exist in the Ipo,
244
 
    None is returned.  I{curve} can be either a string or an integer,
245
 
    denoting either the name of the Ipo curve or its internal adrcode.
246
 
    The possible Ipo curve names are:
247
 
    
248
 
      1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
249
 
      2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
250
 
      Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
251
 
      RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
252
 
      OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
253
 
      Disp.
254
 
      3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
255
 
      dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
256
 
      Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
257
 
      RDamp, Perm.
258
 
      4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
259
 
      5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
260
 
      MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
261
 
      SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
262
 
      5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
263
 
      MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
264
 
      SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
265
 
      6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
266
 
      MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
267
 
      MgOff, MgGain, NBase1, NBase2.
268
 
      7. Curve Ipo: Speed.
269
 
      8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
270
 
      QuatZ, QuatW.
271
 
      9. Sequence Ipo: Fac.
272
 
      10. Constraint Ipo: Inf.
273
 
 
274
 
    The adrcode for the Ipo curve can also be given; this is useful for
275
 
    accessing curves for Shape Key Ipos.  The adrcodes for Shape Key Ipo are
276
 
    numbered consecutively starting at 0.
277
 
    @type curve : string or int
278
 
    @rtype: IpoCurve object
279
 
    @return: the corresponding IpoCurve, or None.
280
 
    @raise ValueError: I{curve} is not a valid name or adrcode for this Ipo
281
 
    type.
282
 
    """
283
 
 
284
 
  def addCurve(curvename):
285
 
    """
286
 
    Add a new curve to the Ipo object. The possible values for I{curvename} are:
287
 
      1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
288
 
      2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
289
 
      Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
290
 
      RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
291
 
      OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
292
 
      Disp.
293
 
      3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
294
 
      dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
295
 
      Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
296
 
      RDamp, Perm.
297
 
      4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
298
 
      5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
299
 
      MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
300
 
      SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
301
 
      5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
302
 
      MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
303
 
      SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
304
 
      6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
305
 
      MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
306
 
      MgOff, MgGain, NBase1, NBase2.
307
 
      7. Curve Ipo: Speed.
308
 
      8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
309
 
      QuatZ, QuatW.
310
 
      9. Sequence Ipo: Fac.
311
 
      10. Constraint Ipo: Inf.
312
 
 
313
 
    For Key IPOs, the name must be an existing KeyBlock name.  Use
314
 
    L{curveConsts} to determine the set of valid names.
315
 
 
316
 
    @type curvename : string
317
 
    @rtype: IpoCurve object
318
 
    @return: the corresponding IpoCurve, or None.
319
 
    @raise ValueError: I{curvename} is not valid or already exists
320
 
    """
321
 
 
322
 
  def delCurve(curvename):
323
 
    """
324
 
    Delete an existing curve from the Ipo object (B{deprecated}).
325
 
    Use the L{mapping operator B{[]}<__getitem__>} instead::
326
 
       from Blender import Ipo
327
 
 
328
 
       ipo = Ipo.Get('ObIpo')
329
 
       ipo[Ipo.LOCX] = None
330
 
 
331
 
    @type curvename : string
332
 
    @rtype: None
333
 
    @return: None.
334
 
    """
335
 
 
336
 
  def getBlocktype():
337
 
    """
338
 
    Gets the blocktype of the Ipo.
339
 
    @rtype: int
340
 
    @return: the blocktype of the Ipo.
341
 
    """
342
 
 
343
 
  def setBlocktype(newblocktype):
344
 
    """
345
 
    Sets the blocktype of the Ipo.
346
 
    @type newblocktype: int 
347
 
    @rtype: None
348
 
    @return: None
349
 
    @warn: 'newblocktype' should not be changed unless you really know what
350
 
       you are doing ...
351
 
    """
352
 
 
353
 
  def getRctf():
354
 
    """
355
 
    Gets the rctf of the Ipo.
356
 
    Kind of bounding box...
357
 
    @rtype: list of floats
358
 
    @return: the rctf of the Ipo.
359
 
    """
360
 
 
361
 
  def setRctf(newrctf):
362
 
    """
363
 
    Sets the rctf of the Ipo.
364
 
    @type newrctf: four floats.
365
 
    @rtype: None
366
 
    @return: None
367
 
    @warn: rctf should not be changed unless you really know what you are
368
 
       doing ...
369
 
    """
370
 
 
371
 
  def getNcurves():
372
 
    """
373
 
    Gets the number of curves of the Ipo (B{deprecated}).  Use
374
 
    L{len(ipo)<__len__>} instead.
375
 
    @rtype: int 
376
 
    @return: the number of curve of the Ipo.
377
 
    """
378
 
    
379
 
  def getCurveBP(curvepos):
380
 
    """
381
 
    This method is unsupported.  BPoint Ipo curves are not implemented.
382
 
    Calling this method throws a NotImplementedError exception.
383
 
    @raise NotImplementedError: this method B{always} raises an exception
384
 
    """
385
 
 
386
 
  def getBeztriple(curvepos,pointpos):
387
 
    """
388
 
    Gets a beztriple of the Ipo (B{deprecated}).  B{Note}:
389
 
    Use L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} instead.
390
 
    @type curvepos: int
391
 
    @param curvepos: the position of the curve in the Ipo.
392
 
    @type pointpos: int
393
 
    @param pointpos: the position of the point in the curve.
394
 
    @rtype: list of 9 floats
395
 
    @return: the beztriple of the Ipo, or an error is raised.
396
 
    """
397
 
 
398
 
  def setBeztriple(curvepos,pointpos,newbeztriple):
399
 
    """
400
 
    Sets the beztriple of the Ipo (B{deprecated}).  B{Note}: use 
401
 
    L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} to get a
402
 
    BezTriple point, then use the
403
 
    L{BezTriple} API to set the point's attributes.
404
 
    @type curvepos: int
405
 
    @param curvepos: the position of the curve in the Ipo.
406
 
    @type pointpos: int
407
 
    @param pointpos: the position of the point in the curve.
408
 
    @type newbeztriple: list of 9 floats
409
 
    @param newbeztriple: the new value for the point
410
 
    @rtype: None
411
 
    @return: None
412
 
    """
413
 
    
414
 
  def getCurveCurval(curvepos):
415
 
    """
416
 
    Gets the current value of a curve of the Ipo (B{deprecated}). B{Note}:
417
 
    new scripts should use L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
418
 
    @type curvepos: int or string
419
 
    @param curvepos: the position of the curve in the Ipo or the name of the
420
 
        curve
421
 
    @rtype: float
422
 
    @return: the current value of the selected curve of the Ipo.
423
 
    """
424
 
 
425
 
  def EvaluateCurveOn(curvepos,time):
426
 
    """
427
 
    Gets the value at a specific time of a curve of the Ipo (B{deprecated}).
428
 
    B{Note}: new scripts should use 
429
 
    L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}.
430
 
    @type curvepos: int
431
 
    @param curvepos: the position of the curve in the Ipo.
432
 
    @type time: float
433
 
    @param time: the desired time.
434
 
    @rtype: float
435
 
    @return: the current value of the selected curve of the Ipo at the given
436
 
    time.
437
 
    """
438
 
 
 
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