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
27class 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 */
46class 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