1 | /*************************************************************************** |
2 | * Copyright 2010 Stefan Majewsky <majewsky@gmx.net> * |
3 | * * |
4 | * This program is free software; you can redistribute it and/or modify * |
5 | * it under the terms of the GNU Library General Public License * |
6 | * version 2 as published by the Free Software Foundation * |
7 | * * |
8 | * This program is distributed in the hope that it will be useful, * |
9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of * |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * |
11 | * GNU Library General Public License for more details. * |
12 | * * |
13 | * You should have received a copy of the GNU Library General Public * |
14 | * License along with this program; if not, write to the * |
15 | * Free Software Foundation, Inc., * |
16 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * |
17 | ***************************************************************************/ |
18 | |
19 | #ifndef KGSOUND_H |
20 | #define KGSOUND_H |
21 | |
22 | #include <QtCore/QObject> |
23 | #include <QtCore/QPointF> |
24 | |
25 | #include <libkdegames_export.h> |
26 | |
27 | class PlaybackEvent; |
28 | |
29 | /** |
30 | * @class KgSound sound.h <KgSound> |
31 | * |
32 | * This class models a sound file. Because it is implicitly added to this |
33 | * application's KgAudioScene, it can be played at different positions (if |
34 | * positional playback is supported, see KgAudioScene::capabilities()). |
35 | * |
36 | * Compared to many other media playback classes, the notable difference of |
37 | * KgSound is that one sound instance can be played multiple times at the |
38 | * same point in time, by calling start() multiple times (possibly with |
39 | * different playback positions). This behavior can be suppressed by calling |
40 | * stop() before start(). |
41 | * |
42 | * @note WAV files and Ogg/Vorbis files are guaranteed to work. Other audio |
43 | * files may also work, depending on the KgAudio backend and its |
44 | * configuration. |
45 | */ |
46 | class KDEGAMES_EXPORT KgSound : public QObject |
47 | { |
48 | Q_OBJECT |
49 | Q_DISABLE_COPY(KgSound) |
50 | Q_PROPERTY(KgSound::PlaybackType playbackType READ playbackType WRITE setPlaybackType NOTIFY playbackTypeChanged) |
51 | Q_PROPERTY(QPointF pos READ pos WRITE setPos NOTIFY posChanged) |
52 | Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged) |
53 | public: |
54 | ///This enumeration describes how a sound can be played back |
55 | enum PlaybackType |
56 | { |
57 | ///Positional playback disabled. The sound will appear at the same |
58 | ///volume from every listener position, and will not appear to be |
59 | ///coming from any direction. The pos() of this sound is ignored. |
60 | AmbientPlayback = 1, |
61 | ///Positional playback enabled. That means that the sound comes from |
62 | ///a certain direction with a distance-depending volume. The pos() |
63 | ///of this sound is given in absolute coordinates: Both direction |
64 | ///and volume can change when the listener is moved. |
65 | AbsolutePlayback, |
66 | ///Positional playback enabled. That means that the sound comes from |
67 | ///a certain direction with a distance-depending volume. The pos() |
68 | ///of this sound is given in relative coordinates: The direction |
69 | ///and volume do not depend on the listener's position. (In these |
70 | ///relative coordinates, the listener is at the point of origin.) |
71 | RelativePlayback |
72 | }; |
73 | |
74 | ///Loads a new sound from the given @a file. Note that this is an |
75 | ///expensive operation which you might want to do during application |
76 | ///startup. However, you can reuse the same Sound instance for multiple |
77 | ///playback events. |
78 | explicit KgSound(const QString& file, QObject* parent = 0); |
79 | ///Destroys this KgSound instance. |
80 | virtual ~KgSound(); |
81 | |
82 | ///@return whether the sound file could be loaded successfully |
83 | bool isValid() const; |
84 | ///@return the playback type for this sound |
85 | KgSound::PlaybackType playbackType() const; |
86 | ///Sets the playback type for this sound. This affects how the sound |
87 | ///will be perceived by the listener. The default is AmbientPlayback. |
88 | /// |
89 | ///@note Changes to this property will not be propagated to running |
90 | /// playbacks of this sound. |
91 | ///@note Effective only if positional playback is supported. |
92 | void setPlaybackType(KgSound::PlaybackType type); |
93 | ///@return the position of this sound |
94 | QPointF pos() const; |
95 | ///Sets the position of this sound. It depends on the playbackType() how |
96 | ///this is position interpreted. See the KgSound::PlaybackType |
97 | ///enumeration documentation for details. |
98 | /// |
99 | ///@note Changes to this property will not be propagated to running |
100 | /// playbacks of this sound. |
101 | ///@note Effective only if positional playback is supported. |
102 | void setPos(const QPointF& pos); |
103 | ///@return the volume of this sound |
104 | qreal volume() const; |
105 | ///Sets the volume of this sound. The default is 1.0, which means no |
106 | ///volume change, compared to the original sound file. 0.0 means that |
107 | ///the sound is inaudible. |
108 | /// |
109 | ///If you think of the KgSound as a loudspeaker, the |
110 | ///volume which is controlled by this method is what you regulate at its |
111 | ///volume control. If positional playback is enabled (see |
112 | ///playbackType()), this will not be the actual volume which the |
113 | ///listener will perceive, because the playback volume decreases with |
114 | ///increasing playback-listener distances. |
115 | /// |
116 | ///@note Changes to this property will not be propagated to running |
117 | /// playbacks of this sound. |
118 | void setVolume(qreal volume); |
119 | |
120 | ///@returns whether loading or playing this sound failed |
121 | /// |
122 | ///See KgAudioScene::hasError() for why you typically do not need to use |
123 | ///this method. |
124 | bool hasError() const; |
125 | public Q_SLOTS: |
126 | ///Starts a new playback instance of this sound. This will not interrupt |
127 | ///running playbacks of the same sound or any other sounds. |
128 | void start(); |
129 | ///@overload |
130 | ///This overload takes an additional position argument which overrides |
131 | ///the sound's pos() property. |
132 | ///@note @a pos is respected only if positional playback is supported. |
133 | void start(const QPointF& pos); |
134 | ///Stops any playbacks of this sounds. |
135 | void stop(); |
136 | Q_SIGNALS: |
137 | void playbackTypeChanged(KgSound::PlaybackType type); |
138 | void posChanged(const QPointF& pos); |
139 | void volumeChanged(qreal volume); |
140 | private: |
141 | friend class KgPlaybackEvent; |
142 | class Private; |
143 | Private* const d; |
144 | }; |
145 | |
146 | #endif // KGSOUND_H |
147 | |