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