KDEGames

audio/kgsound.h
1 /*
2  SPDX-FileCopyrightText: 2010 Stefan Majewsky <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-only
5 */
6 
7 #ifndef KGSOUND_H
8 #define KGSOUND_H
9 
10 // own
11 #include <libkdegames_export.h>
12 // Qt
13 #include <QObject>
14 #include <QPointF>
15 // Std
16 #include <memory>
17 
18 class PlaybackEvent;
19 
20 /**
21  * @class KgSound sound.h <KgSound>
22  *
23  * This class models a sound file. Because it is implicitly added to this
24  * application's KgAudioScene, it can be played at different positions (if
25  * positional playback is supported, see KgAudioScene::capabilities()).
26  *
27  * Compared to many other media playback classes, the notable difference of
28  * KgSound is that one sound instance can be played multiple times at the
29  * same point in time, by calling start() multiple times (possibly with
30  * different playback positions). This behavior can be suppressed by calling
31  * stop() before start().
32  *
33  * @note WAV files and Ogg/Vorbis files are guaranteed to work. Other audio
34  * files may also work, depending on the KgAudio backend and its
35  * configuration.
36  */
37 class KDEGAMES_EXPORT KgSound : public QObject
38 {
39  Q_OBJECT
41  Q_PROPERTY(KgSound::PlaybackType playbackType READ playbackType WRITE setPlaybackType NOTIFY playbackTypeChanged)
42  Q_PROPERTY(QPointF pos READ pos WRITE setPos NOTIFY posChanged)
43  Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged)
44  public:
45  ///This enumeration describes how a sound can be played back
47  {
48  ///Positional playback disabled. The sound will appear at the same
49  ///volume from every listener position, and will not appear to be
50  ///coming from any direction. The pos() of this sound is ignored.
51  AmbientPlayback = 1,
52  ///Positional playback enabled. That means that the sound comes from
53  ///a certain direction with a distance-depending volume. The pos()
54  ///of this sound is given in absolute coordinates: Both direction
55  ///and volume can change when the listener is moved.
57  ///Positional playback enabled. That means that the sound comes from
58  ///a certain direction with a distance-depending volume. The pos()
59  ///of this sound is given in relative coordinates: The direction
60  ///and volume do not depend on the listener's position. (In these
61  ///relative coordinates, the listener is at the point of origin.)
62  RelativePlayback
63  };
64 
65  /**
66  * Loads a new sound from the given @a file. Note that this is an
67  * expensive operation which you might want to do during application
68  * startup. However, you can reuse the same Sound instance for multiple
69  * playback events.
70  *
71  * Since version 7.2.0 this constructor supports reading files from Qt
72  * Resource System, @a file can be for example ":/sound.ogg".
73  */
74  explicit KgSound(const QString& file, QObject* parent = nullptr);
75  ///Destroys this KgSound instance.
76  virtual ~KgSound();
77 
78  ///@return whether the sound file could be loaded successfully
79  bool isValid() const;
80  ///@return the playback type for this sound
81  KgSound::PlaybackType playbackType() const;
82  ///Sets the playback type for this sound. This affects how the sound
83  ///will be perceived by the listener. The default is AmbientPlayback.
84  ///
85  ///@note Changes to this property will not be propagated to running
86  /// playbacks of this sound.
87  ///@note Effective only if positional playback is supported.
88  void setPlaybackType(KgSound::PlaybackType type);
89  ///@return the position of this sound
90  QPointF pos() const;
91  ///Sets the position of this sound. It depends on the playbackType() how
92  ///this is position interpreted. See the KgSound::PlaybackType
93  ///enumeration documentation for details.
94  ///
95  ///@note Changes to this property will not be propagated to running
96  /// playbacks of this sound.
97  ///@note Effective only if positional playback is supported.
98  void setPos(const QPointF& pos);
99  ///@return the volume of this sound
100  qreal volume() const;
101  ///Sets the volume of this sound. The default is 1.0, which means no
102  ///volume change, compared to the original sound file. 0.0 means that
103  ///the sound is inaudible.
104  ///
105  ///If you think of the KgSound as a loudspeaker, the
106  ///volume which is controlled by this method is what you regulate at its
107  ///volume control. If positional playback is enabled (see
108  ///playbackType()), this will not be the actual volume which the
109  ///listener will perceive, because the playback volume decreases with
110  ///increasing playback-listener distances.
111  ///
112  ///@note Changes to this property will not be propagated to running
113  /// playbacks of this sound.
114  void setVolume(qreal volume);
115 
116  ///@returns whether loading or playing this sound failed
117  ///
118  ///See KgAudioScene::hasError() for why you typically do not need to use
119  ///this method.
120  bool hasError() const;
121  public Q_SLOTS:
122  ///Starts a new playback instance of this sound. This will not interrupt
123  ///running playbacks of the same sound or any other sounds.
124  void start();
125  ///@overload
126  ///This overload takes an additional position argument which overrides
127  ///the sound's pos() property.
128  ///@note @a pos is respected only if positional playback is supported.
129  void start(const QPointF& pos);
130  ///Stops any playbacks of this sounds.
131  void stop();
132  Q_SIGNALS:
133  void playbackTypeChanged(KgSound::PlaybackType type);
134  void posChanged(const QPointF& pos);
135  void volumeChanged(qreal volume);
136  private:
137  friend class KgPlaybackEvent;
138  std::unique_ptr<class KgSoundPrivate> const d;
139 };
140 
141 #endif // KGSOUND_H
PlaybackType
This enumeration describes how a sound can be played back.
Definition: audio/kgsound.h:46
Positional playback enabled.
Definition: audio/kgsound.h:56
This class models a sound file.
Definition: audio/kgsound.h:37
Q_PROPERTY(...)
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu May 13 2021 22:37:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.