dsfml.audio.soundsource source code

1 /*
2  * DSFML - The Simple and Fast Multimedia Library for D
3  *
4  * Copyright (c) 2013 - 2017 Jeremy DeHaan (dehaan.jeremiah@gmail.com)
5  *
6  * This software is provided 'as-is', without any express or implied warranty.
7  * In no event will the authors be held liable for any damages arising from the
8  * use of this software.
9  *
10  * Permission is granted to anyone to use this software for any purpose,
11  * including commercial applications, and to alter it and redistribute it
12  * freely, subject to the following restrictions:
13  *
14  * 1. The origin of this software must not be misrepresented; you must not claim
15  * that you wrote the original software. If you use this software in a product,
16  * an acknowledgment in the product documentation would be appreciated but is
17  * not required.
18  *
19  * 2. Altered source versions must be plainly marked as such, and must not be
20  * misrepresented as being the original software.
21  *
22  * 3. This notice may not be removed or altered from any source distribution
23  */
24 
25 /**
26  *
27  * $(U SoundSource) is not meant to be used directly, it only serves as a common
28  * base for all audio objects that can live in the audio environment.
29  *
30  * It defines several properties for the sound: pitch, volume, position,
31  * attenuation, etc. All of them can be changed at any time with no impact on
32  * performances.
33  *
34  * See_Also:
35  * $(SOUND_LINK), $(SOUNDSTREAM_LINK)
36  */
37 module dsfml.audio.soundsource;
38 
39 import dsfml.system.vector3;
40 
41 /**
42  * Base class defining a sound's properties.
43  */
44 interface SoundSource
45 {
46     /// Enumeration of the sound source states.
47     enum Status
48     {
49         /// Sound is not playing.
50         Stopped,
51         /// Sound is paused.
52         Paused,
53         /// Sound is playing.
54         Playing
55     }
56 
57     @property
58     {
59         /**
60          * The pitch of the sound.
61          *
62          * The pitch represents the perceived fundamental frequency of a sound; thus
63          * you can make a sound more acute or grave by changing its pitch. A side
64          * effect of changing the pitch is to modify the playing speed of the sound
65          * as well. The default value for the pitch is 1.
66          */
67         void pitch(float newPitch);
68         /// ditto
69         float pitch();
70     }
71 
72     @property
73     {
74         /**
75          * The volume of the sound.
76          *
77          * The volume is a vlue between 0 (mute) and 100 (full volume). The default
78          * value for the volume is 100.
79          */
80         void volume(float newVolume);
81         /// ditto
82         float volume();
83     }
84 
85     @property
86     {
87         /**
88          * The 3D position of the sound in the audio scene.
89          *
90          * Only sounds with one channel (mono sounds) can be spatialized. The
91          * default position of a sound is (0, 0, 0).
92          */
93         void position(Vector3f newPosition);
94         /// ditto
95         Vector3f position();
96     }
97 
98     @property
99     {
100         /**
101          * Make the sound's position relative to the listener (true) or absolute
102          * (false).
103          *
104          * Making a sound relative to the listener will ensure that it will always
105          * be played the same way regardless the position of the listener.  This can
106          * be useful for non-spatialized sounds, sounds that are produced by the
107          * listener, or sounds attached to it. The default value is false (position
108          * is absolute).
109          */
110         void relativeToListener(bool relative);
111         /// ditto
112         bool relativeToListener();
113     }
114 
115     @property
116     {
117         /**
118          * The minimum distance of the sound.
119          *
120          * The "minimum distance" of a sound is the maximum distance at which it is
121          * heard at its maximum volume. Further than the minimum distance, it will
122          * start to fade out according to its attenuation factor. A value of 0
123          * ("inside the head of the listener") is an invalid value and is forbidden.
124          * The default value of the minimum distance is 1.
125          */
126         void minDistance(float distance);
127         /// ditto
128         float minDistance();
129     }
130 
131     @property
132     {
133         /**
134          * The attenuation factor of the sound.
135          *
136          * The attenuation is a multiplicative factor which makes the sound more or
137          * less loud according to its distance from the listener. An attenuation of
138          * 0 will produce a non-attenuated sound, i.e. its volume will always be the
139          * same whether it is heard from near or from far.
140          *
141          * On the other hand, an attenuation value such as 100 will make the sound
142          * fade out very quickly as it gets further from the listener. The default
143          * value of the attenuation is 1.
144          */
145         void attenuation(float newAttenuation);
146         /// ditto
147         float attenuation();
148     }
149 }