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.
37  {
38  ///Playback starts as soon as KgSound::start is called.
40  SupportsPositionalPlayback = 1 << 1,
41  };
42  Q_DECLARE_FLAGS(Capabilities, Capability)
43 
44  ///@return which capabilities are supported by the compiled KgAudio backend
45  KDEGAMES_EXPORT Capabilities capabilities();
46 
47  ///@return the position of the listener
48  KDEGAMES_EXPORT QPointF listenerPos();
49  ///Sets the position of the listener. The default is (0.0, 0.0), the
50  ///point of origin.
51  ///@note Effective only if positional playback is supported.
52  KDEGAMES_EXPORT void setListenerPos(const QPointF& pos);
53  ///@return the master volume for sounds outputted by TagaroAudio
54  KDEGAMES_EXPORT qreal volume();
55  ///Sets the master volume for sounds outputted by TagaroAudio. The
56  ///default is 1.0, which means no volume change, compared to the
57  ///original sounds. 0.0 means that all sounds are muted.
58  KDEGAMES_EXPORT void setVolume(qreal volume);
59 
60  ///@returns whether an error was detected in the audio backend
61  ///
62  ///Since KgAudio is typically used by games where audio is not an absolutely
63  ///vital part of the gameplay, we do not need to fail if sound does not work,
64  ///over even make some sort of deep analysis why something did not work. The
65  ///user will notice missing sound, and advanced users may investigate
66  ///the kWarning() messages. That is usually enough. If not, use this method.
67  ///
68  ///The state of hasError() may theoretically change while the application
69  ///runs, but in practice, this is very unlikely. (The only tricky part is
70  ///typically the initial allocation of resources.)
71  ///
72  ///@sa KgSound::hasError()
73  KDEGAMES_EXPORT bool hasError();
74 };
75 
76 Q_DECLARE_OPERATORS_FOR_FLAGS(KgAudioScene::Capabilities)
77 
78 #endif // KGAUDIOSCENE_H
Capability
This enumeration represents capabilities which may not be provided by every KgAudio backend...
void setListenerPos(const QPointF &pos)
Sets the position of the listener.
void setVolume(qreal volume)
Sets the master volume for sounds outputted by TagaroAudio.
This class exposes general properties of the audio playback context.
Playback starts as soon as KgSound::start is called.
Capabilities capabilities()
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Dec 7 2021 22:34:15 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.