nudsfml.audio.soundsource source code

1 /*
2  * DSFML - The Simple and Fast Multimedia Library for D
3  *
4  * Copyright (c) 2013 - 2018 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  * DSFML is based on SFML (Copyright Laurent Gomila)
26  */
27 
28 /**
29  *
30  * $(U SoundSource) is not meant to be used directly, it only serves as a common
31  * base for all audio objects that can live in the audio environment.
32  *
33  * It defines several properties for the sound: pitch, volume, position,
34  * attenuation, etc. All of them can be changed at any time with no impact on
35  * performances.
36  *
37  * See_Also:
38  * $(SOUND_LINK), $(SOUNDSTREAM_LINK)
39  */
40 module nudsfml.audio.soundsource;
41 
42 import nudsfml.system.vector3;
43 
44 /**
45  * Interface defining a sound's properties.
46  */
47 interface SoundSource {
48     /// Enumeration of the sound source states.
49     enum Status {
50         /// Sound is not playing.
51         Stopped,
52         /// Sound is paused.
53         Paused,
54         /// Sound is playing.
55         Playing
56     }
57 
58     @property {
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 
69         /// ditto
70         float pitch();
71     }
72 
73     @property {
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 
82         /// ditto
83         float volume();
84     }
85 
86     @property {
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 
95         /// ditto
96         Vector3f position();
97     }
98 
99     @property {
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 
112         /// ditto
113         bool relativeToListener();
114     }
115 
116     @property {
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 
128         /// ditto
129         float minDistance();
130     }
131 
132     @property {
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 
147         /// ditto
148         float attenuation();
149     }
150 }