KGameSound Class

The KGameSound class models a sound file. More...

Header: #include <KGameSound>
Inherits: QObject

Public Types

enum PlaybackType { AmbientPlayback, AbsolutePlayback, RelativePlayback }

Properties

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

void start()
void start(QPointF pos)
void stop()

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.

ConstantValueDescription
KGameSound::AmbientPlayback1Positional 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::AbsolutePlayback2Positional 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::RelativePlayback3Positional 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.