KDEGames

audio/kgaudioscene.h
1 /*
2  SPDX-FileCopyrightText: 2010 Stefan Majewsky <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-only
5 */
6 
7 #ifndef KGAUDIOSCENE_H
8 #define KGAUDIOSCENE_H
9 
10 // own
11 #include <libkdegames_export.h>
12 // Qt
13 #include <QPointF>
14 
15 /**
16  * @namespace KgAudioScene
17  *
18  * This class exposes general properties of the audio playback context. Actual
19  * sounds are represented in this context by KgSound instances.
20  *
21  * The audio scene basically consists of a listener. The position of this
22  * listener is relevant when sounds are played at certain positions: The audio
23  * channels will then be balanced to make the sound appear to come from that
24  * direction.
25  *
26  * Because there can ogly be one listener, all methods in this class are static.
27  *
28  * @warning Not all functionally exposed by the API of this class is guaranteed
29  * to be available on the compiled KgAudio backend. Check
30  * KgAudioScene::capabilities() if in doubt.
31  */
32 namespace KgAudioScene
33 {
34 /// This enumeration represents capabilities which may not be provided by
35 /// every KgAudio backend.
36 enum Capability {
37  /// Playback starts as soon as KgSound::start is called.
39  SupportsPositionalPlayback = 1 << 1,
40 };
41 /**
42  * Stores a combination of #Capability values.
43  */
44 Q_DECLARE_FLAGS(Capabilities, Capability)
45 
46 /// @return which capabilities are supported by the compiled KgAudio backend
47 KDEGAMES_EXPORT Capabilities capabilities();
48 
49 /// @return the position of the listener
50 KDEGAMES_EXPORT QPointF listenerPos();
51 /// Sets the position of the listener. The default is (0.0, 0.0), the
52 /// point of origin.
53 /// @note Effective only if positional playback is supported.
54 KDEGAMES_EXPORT void setListenerPos(const QPointF &pos);
55 /// @return the master volume for sounds outputted by TagaroAudio
56 KDEGAMES_EXPORT qreal volume();
57 /// Sets the master volume for sounds outputted by TagaroAudio. The
58 /// default is 1.0, which means no volume change, compared to the
59 /// original sounds. 0.0 means that all sounds are muted.
60 KDEGAMES_EXPORT void setVolume(qreal volume);
61 
62 /// @returns whether an error was detected in the audio backend
63 ///
64 /// Since KgAudio is typically used by games where audio is not an absolutely
65 /// vital part of the gameplay, we do not need to fail if sound does not work,
66 /// over even make some sort of deep analysis why something did not work. The
67 /// user will notice missing sound, and advanced users may investigate
68 /// the kWarning() messages. That is usually enough. If not, use this method.
69 ///
70 /// The state of hasError() may theoretically change while the application
71 /// runs, but in practice, this is very unlikely. (The only tricky part is
72 /// typically the initial allocation of resources.)
73 ///
74 /// @sa KgSound::hasError()
75 KDEGAMES_EXPORT bool hasError();
76 };
77 
78 Q_DECLARE_OPERATORS_FOR_FLAGS(KgAudioScene::Capabilities)
79 
80 #endif // KGAUDIOSCENE_H
void setListenerPos(const QPointF &pos)
Sets the position of the listener.
void setVolume(qreal volume)
Sets the master volume for sounds outputted by TagaroAudio.
Capability
This enumeration represents capabilities which may not be provided by every KgAudio backend.
Capabilities capabilities()
@ SupportsLowLatencyPlayback
Playback starts as soon as KgSound::start is called.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Jun 27 2022 03:57:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.