dsfml.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 dsfml.audio.soundsource;
41 
42 import dsfml.system.vector3;
43 
44 /**
45  * Interface defining a sound's properties.
46  */
47 interface SoundSource
48 {
49     /// Enumeration of the sound source states.
50     enum Status
51     {
52         /// Sound is not playing.
53         Stopped,
54         /// Sound is paused.
55         Paused,
56         /// Sound is playing.
57         Playing
58     }
59 
60     @property
61     {
62         /**
63          * The pitch of the sound.
64          *
65          * The pitch represents the perceived fundamental frequency of a sound; thus
66          * you can make a sound more acute or grave by changing its pitch. A side
67          * effect of changing the pitch is to modify the playing speed of the sound
68          * as well. The default value for the pitch is 1.
69          */
70         void pitch(float newPitch);
71 
72         /// ditto
73         float pitch();
74     }
75 
76     @property
77     {
78         /**
79          * The volume of the sound.
80          *
81          * The volume is a vlue between 0 (mute) and 100 (full volume). The default
82          * value for the volume is 100.
83          */
84         void volume(float newVolume);
85 
86         /// ditto
87         float volume();
88     }
89 
90     @property
91     {
92         /**
93          * The 3D position of the sound in the audio scene.
94          *
95          * Only sounds with one channel (mono sounds) can be spatialized. The
96          * default position of a sound is (0, 0, 0).
97          */
98         void position(Vector3f newPosition);
99 
100         /// ditto
101         Vector3f position();
102     }
103 
104     @property
105     {
106         /**
107          * Make the sound's position relative to the listener (true) or absolute
108          * (false).
109          *
110          * Making a sound relative to the listener will ensure that it will always
111          * be played the same way regardless the position of the listener.  This can
112          * be useful for non-spatialized sounds, sounds that are produced by the
113          * listener, or sounds attached to it. The default value is false (position
114          * is absolute).
115          */
116         void relativeToListener(bool relative);
117 
118         /// ditto
119         bool relativeToListener();
120     }
121 
122     @property
123     {
124         /**
125          * The minimum distance of the sound.
126          *
127          * The "minimum distance" of a sound is the maximum distance at which it is
128          * heard at its maximum volume. Further than the minimum distance, it will
129          * start to fade out according to its attenuation factor. A value of 0
130          * ("inside the head of the listener") is an invalid value and is forbidden.
131          * The default value of the minimum distance is 1.
132          */
133         void minDistance(float distance);
134 
135         /// ditto
136         float minDistance();
137     }
138 
139     @property
140     {
141         /**
142          * The attenuation factor of the sound.
143          *
144          * The attenuation is a multiplicative factor which makes the sound more or
145          * less loud according to its distance from the listener. An attenuation of
146          * 0 will produce a non-attenuated sound, i.e. its volume will always be the
147          * same whether it is heard from near or from far.
148          *
149          * On the other hand, an attenuation value such as 100 will make the sound
150          * fade out very quickly as it gets further from the listener. The default
151          * value of the attenuation is 1.
152          */
153         void attenuation(float newAttenuation);
154 
155         /// ditto
156         float attenuation();
157     }
158 }