source/gameengine/PyDoc/KX_SoundActuator.py

   1 # $Id$
   2 # Documentation for KX_SoundActuator
   3 from SCA_IActuator import *
   4
   5 class KX_SoundActuator(SCA_IActuator):
   6         """
   7         Sound Actuator.
   8
   9         The L{startSound()}, L{pauseSound()} and L{stopSound()} do not require
  10         the actuator to be activated - they act instantly.
  11
  12         @ivar filename: Sets the filename of the sound this actuator plays.
  13         @type filename: string
  14
  15         @ivar volume: Sets the volume (gain) of the sound.
  16         @type volume: float
  17
  18         @ivar pitch: Sets the pitch of the sound.
  19         @type pitch: float
  20
  21         @ivar rollOffFactor: Sets the roll off factor. Rolloff defines the rate of attenuation as the sound gets further away.
  22         @type rollOffFactor: float
  23
  24         @ivar looping: Sets the loop mode of the actuator.
  25         @type looping: integer
  26
  27         @ivar position: Sets the position of the sound.
  28         @type position: float array
  29
  30         @ivar velocity: Sets the speed of the sound; The speed of the sound alter the pitch.
  31         @type velocity: float array
  32
  33         @ivar orientation: Sets the orientation of the sound. When setting the orientation you can
  34                            also use quaternion [float,float,float,float] or euler angles [float,float,float]
  35         @type orientation: 3x3 matrix [[float]]
  36
  37         @ivar type: Sets the operation mode of the actuator. You can use one of the following constant:
  38                     KX_SOUNDACT_PLAYSTOP               (1)
  39                             KX_SOUNDACT_PLAYEND                (2)
  40                             KX_SOUNDACT_LOOPSTOP               (3)
  41                             KX_SOUNDACT_LOOPEND                (4)
  42                             KX_SOUNDACT_LOOPBIDIRECTIONAL      (5)
  43                             KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP (6)
  44         @type type:     integer
  45
  46         @group Play Methods: startSound, pauseSound, stopSound.
  47         """
  48         def setFilename(filename):
  49                 """
  50                 DEPRECATED: Use the filename property instead.
  51         Sets the filename of the sound this actuator plays.
  52
  53                 @type filename: string
  54                 """
  55         def getFilename():
  56                 """
  57                 DEPRECATED: Use the filename property instead.
  58                 Returns the filename of the sound this actuator plays.
  59
  60                 @rtype: string
  61                 """
  62         def startSound():
  63                 """
  64                 Starts the sound.
  65                 """
  66         def pauseSound():
  67                 """
  68                 Pauses the sound.
  69                 """
  70         def stopSound():
  71                 """
  72                 Stops the sound.
  73                 """
  74         def setGain(gain):
  75                 """
  76                 DEPRECATED: Use the volume property instead
  77                 Sets the gain (volume) of the sound
  78
  79                 @type gain: float
  80                 @param gain: 0.0 (quiet) <= gain <= 1.0 (loud)
  81                 """
  82         def getGain():
  83                 """
  84                 DEPRECATED: Use the volume property instead.
  85                 Gets the gain (volume) of the sound.
  86
  87                 @rtype: float
  88                 """
  89         def setPitch(pitch):
  90                 """
  91                 DEPRECATED: Use the pitch property instead.
  92                 Sets the pitch of the sound.
  93
  94                 @type pitch: float
  95                 """
  96         def getPitch():
  97                 """
  98                 DEPRECATED: Use the pitch property instead.
  99                 Returns the pitch of the sound.
 100
 101                 @rtype: float
 102                 """
 103         def setRollOffFactor(rolloff):
 104                 """
 105                 DEPRECATED: Use the rollOffFactor property instead.
 106                 Sets the rolloff factor for the sounds.
 107
 108                 Rolloff defines the rate of attenuation as the sound gets further away.
 109                 Higher rolloff factors shorten the distance at which the sound can be heard.
 110
 111                 @type rolloff: float
 112                 """
 113         def getRollOffFactor():
 114                 """
 115                 DEPRECATED: Use the rollOffFactor property instead.
 116                 Returns the rolloff factor for the sound.
 117
 118                 @rtype: float
 119                 """
 120         def setLooping(loop):
 121                 """
 122                 DEPRECATED: Use the looping property instead.
 123                 Sets the loop mode of the actuator.
 124
 125                 @bug: There are no constants defined for this method!
 126                 @param loop: - Play Stop        1
 127                              - Play End         2
 128                              - Loop Stop        3
 129                              - Loop End         4
 130                              - Bidirection Stop 5
 131                              - Bidirection End  6
 132                 @type loop: integer
 133                 """
 134         def getLooping():
 135                 """
 136                 DEPRECATED: Use the looping property instead.
 137                 Returns the current loop mode of the actuator.
 138
 139                 @rtype: integer
 140                 """
 141         def setPosition(x, y, z):
 142                 """
 143                 DEPRECATED: Use the position property instead.
 144                 Sets the position this sound will come from.
 145
 146                 @type x: float
 147                 @param x: The x coordinate of the sound.
 148                 @type y: float
 149                 @param y: The y coordinate of the sound.
 150                 @type z: float
 151                 @param z: The z coordinate of the sound.
 152                 """
 153         def setVelocity(vx, vy, vz):
 154                 """
 155                 DEPRECATED: Use the velocity property instead.
 156                 Sets the velocity this sound is moving at.
 157
 158                 The sound's pitch is determined from the velocity.
 159
 160                 @type vx: float
 161                 @param vx: The vx coordinate of the sound.
 162                 @type vy: float
 163                 @param vy: The vy coordinate of the sound.
 164                 @type vz: float
 165                 @param vz: The vz coordinate of the sound.
 166                 """
 167         def setOrientation(o11, o12, o13, o21, o22, o23, o31, o32, o33):
 168                 """
 169                 DEPRECATED: Use the orientation property instead.
 170                 Sets the orientation of the sound.
 171
 172                 The nine parameters specify a rotation matrix::
 173                         | o11, o12, o13 |
 174                         | o21, o22, o23 |
 175                         | o31, o32, o33 |
 176                 """
 177
 178         def setType(mode):
 179                 """
 180                 DEPRECATED: Use the type property instead.
 181                 Sets the operation mode of the actuator.
 182
 183                 @param mode: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
 184                 @type mode: integer
 185                 """
 186
 187         def getType():
 188                 """
 189                 DEPRECATED: Use the type property instead.
 190                 Returns the operation mode of the actuator.
 191
 192                 @rtype: integer
 193                 @return:  KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
 194                 """