KDEGames

kgamesound.h
1/*
2 SPDX-FileCopyrightText: 2010 Stefan Majewsky <majewsky@gmx.net>
3
4 SPDX-License-Identifier: LGPL-2.0-only
5*/
6
7#ifndef KGAMESOUND_H
8#define KGAMESOUND_H
9
10// own
11#include "kdegames_export.h"
12// Qt
13#include <QObject>
14#include <QPointF>
15// Std
16#include <memory>
17
18class PlaybackEvent;
19
20/**
21 * @class KGameSound kgamesound.h <KGameSound>
22 *
23 * This class models a sound file. Because it is implicitly added to this
24 * application's KGameAudioScene, it can be played at different positions (if
25 * positional playback is supported, see KGameAudioScene::capabilities()).
26 *
27 * Compared to many other media playback classes, the notable difference of
28 * KGameSound 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 KGameAudio backend and its
35 * configuration.
36 */
37class KDEGAMES_EXPORT KGameSound : public QObject
38{
39 Q_OBJECT
40 Q_DISABLE_COPY(KGameSound)
41 Q_PROPERTY(KGameSound::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
45public:
46 /// This enumeration describes how a sound can be played back
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 KGameSound(const QString &file, QObject *parent = nullptr);
75 /// Destroys this KGameSound instance.
76 ~KGameSound() override;
77
78 /// @return whether the sound file could be loaded successfully
79 bool isValid() const;
80 /// @return the playback type for this sound
81 KGameSound::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(KGameSound::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 KGameSound::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(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 KGameSound 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 KGameAudioScene::hasError() for why you typically do not need to use
119 /// this method.
120 bool hasError() const;
121public 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(QPointF pos);
130 /// Stops any playbacks of this sounds.
131 void stop();
133 void playbackTypeChanged(KGameSound::PlaybackType type);
134 void posChanged(QPointF pos);
135 void volumeChanged(qreal volume);
136
137private:
138 friend class KGamePlaybackEvent;
139 std::unique_ptr<class KGameSoundPrivate> const d_ptr;
140 Q_DECLARE_PRIVATE(KGameSound)
141};
142
143#endif // KGAMESOUND_H
This class models a sound file.
Definition kgamesound.h:38
PlaybackType
This enumeration describes how a sound can be played back.
Definition kgamesound.h:47
@ AbsolutePlayback
Positional playback enabled.
Definition kgamesound.h:56
void stop(Ekos::AlignState mode)
Q_SCRIPTABLE Q_NOREPLY void start()
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:56:07 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.