KGameSound Class
The KGameSound class models a sound file. More...
| Header: | #include <KGameSound> |
| Inherits: | QObject |
Public Types
| enum | PlaybackType { AmbientPlayback, AbsolutePlayback, RelativePlayback } |
Properties
- playbackType : KGameSound::PlaybackType
- pos : QPointF
- volume : qreal
Public Functions
| KGameSound(const QString &file, QObject *parent = nullptr) | |
| bool | hasError() const |
| bool | isValid() const |
| KGameSound::PlaybackType | playbackType() const |
| QPointF | pos() const |
| void | setPlaybackType(KGameSound::PlaybackType type) |
| void | setPos(QPointF pos) |
| void | setVolume(qreal volume) |
| qreal | volume() const |
Public Slots
Signals
| void | playbackTypeChanged(KGameSound::PlaybackType type) |
| void | posChanged(QPointF pos) |
| void | volumeChanged(qreal volume) |
Detailed Description
This class models a sound file. Because it is implicitly added to this application's KGameAudioScene, it can be played at different positions (if positional playback is supported, see KGameAudioScene::capabilities()).
Compared to many other media playback classes, the notable difference of KGameSound is that one sound instance can be played multiple times at the same point in time, by calling start() multiple times (possibly with different playback positions). This behavior can be suppressed by calling stop() before start().
Note: WAV files and Ogg/Vorbis files are guaranteed to work. Other audio files may also work, depending on the KGameAudio backend and its configuration.
Member Type Documentation
enum KGameSound::PlaybackType
This enumeration describes how a sound can be played back.
| Constant | Value | Description |
|---|---|---|
KGameSound::AmbientPlayback | 1 | Positional playback disabled. The sound will appear at the same volume from every listener position, and will not appear to be coming from any direction. The pos() of this sound is ignored. |
KGameSound::AbsolutePlayback | 2 | Positional playback enabled. That means that the sound comes from a certain direction with a distance-depending volume. The pos() of this sound is given in absolute coordinates: Both direction and volume can change when the listener is moved. |
KGameSound::RelativePlayback | 3 | Positional playback enabled. That means that the sound comes from a certain direction with a distance-depending volume. The pos() of this sound is given in relative coordinates: The direction and volume do not depend on the listener's position. (In these relative coordinates, the listener is at the point of origin.) |
Property Documentation
playbackType : KGameSound::PlaybackType
This property holds the playback type for this sound.
This affects how the sound will be perceived by the listener. The default is AmbientPlayback.
Note: Changes to this property will not be propagated to running playbacks of this sound.
Note: Effective only if positional playback is supported.
Access functions:
| KGameSound::PlaybackType | playbackType() const |
| void | setPlaybackType(KGameSound::PlaybackType type) |
Notifier signal:
| void | playbackTypeChanged(KGameSound::PlaybackType type) |
pos : QPointF
This property holds the position of this sound.
It depends on the playbackType() how this is position interpreted. See the KGameSound::PlaybackType enumeration documentation for details.
Note: Changes to this property will not be propagated to running playbacks of this sound.
Note: Effective only if positional playback is supported.
Access functions:
| QPointF | pos() const |
| void | setPos(QPointF pos) |
Notifier signal:
| void | posChanged(QPointF pos) |
volume : qreal
This property holds the volume of this sound.
The default is 1.0, which means no volume change, compared to the original sound file. 0.0 means that the sound is inaudible.
If you think of the KGameSound as a loudspeaker, the volume which is controlled by this method is what you regulate at its volume control. If positional playback is enabled (see playbackType()), this will not be the actual volume which the listener will perceive, because the playback volume decreases with increasing playback-listener distances.
Note: Changes to this property will not be propagated to running playbacks of this sound.
Access functions:
| qreal | volume() const |
| void | setVolume(qreal volume) |
Notifier signal:
| void | volumeChanged(qreal volume) |
Member Function Documentation
[explicit] KGameSound::KGameSound(const QString &file, QObject *parent = nullptr)
Loads a new sound from the given file, with parent parent. Note that this is an expensive operation which you might want to do during application startup. However, you can reuse the same Sound instance for multiple playback events.
Since version 7.2.0 this constructor supports reading files from Qt Resource System, file can be for example ":/sound.ogg".
bool KGameSound::hasError() const
Returns whether loading or playing this sound failed.
See KGameAudioScene::hasError() for why you typically do not need to use this method.
bool KGameSound::isValid() const
Returns whether the sound file could be loaded successfully.
[signal] void KGameSound::playbackTypeChanged(KGameSound::PlaybackType type)
Emitted when the playbackType changes to type.
Note: Notifier signal for property playbackType.
[signal] void KGameSound::posChanged(QPointF pos)
Emitted when the pos changes to pos.
Note: Notifier signal for property pos.
[slot] void KGameSound::start()
Starts a new playback instance of this sound. This will not interrupt running playbacks of the same sound or any other sounds.
Note: This slot is overloaded. To connect to this slot:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
kGameSound, qOverload<>(&KGameSound::start));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
kGameSound, [receiver = kGameSound]() { receiver->start(); });
For more examples and approaches, see connecting to overloaded slots.
[slot] void KGameSound::start(QPointF pos)
This overload takes an additional position argument which overrides the sound's pos() property.
Note: pos is respected only if positional playback is supported.
Note: This slot is overloaded. To connect to this slot:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
kGameSound, qOverload(&KGameSound::start));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
kGameSound, [receiver = kGameSound](QPointF pos) { receiver->start(pos); });
For more examples and approaches, see connecting to overloaded slots.
[slot] void KGameSound::stop()
Stops any playbacks of this sound.
[signal] void KGameSound::volumeChanged(qreal volume)
Emitted when the volume changes to volume.
Note: Notifier signal for property volume.