383b45e6eb94797244bf0adcc05cb861d2138ee9
[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.
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                 """