KDEGames

audio/kgameaudioscene.h
1/*
2 SPDX-FileCopyrightText: 2010 Stefan Majewsky <majewsky@gmx.net>
3
4 SPDX-License-Identifier: LGPL-2.0-only
5*/
6
7#ifndef KGAMEAUDIOSCENE_H
8#define KGAMEAUDIOSCENE_H
9
10// own
11#include "kdegames_export.h"
12// Qt
13#include <QPointF>
14
15/**
16 * @namespace KGameAudioScene
17 *
18 * This class exposes general properties of the audio playback context. Actual
19 * sounds are represented in this context by KGameSound 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 KGameAudio backend. Check
30 * KGameAudioScene::capabilities() if in doubt.
31 */
32namespace KGameAudioScene
33{
34/// This enumeration represents capabilities which may not be provided by
35/// every KGameAudio backend.
37 /// Playback starts as soon as KGameSound::start is called.
39 SupportsPositionalPlayback = 1 << 1,
40};
41/**
42 * Stores a combination of #Capability values.
43 */
44Q_DECLARE_FLAGS(Capabilities, Capability)
45
46/// @return which capabilities are supported by the compiled KGameAudio backend
47KDEGAMES_EXPORT Capabilities capabilities();
48
49/// @return the position of the listener
50KDEGAMES_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.
54KDEGAMES_EXPORT void setListenerPos(QPointF pos);
55/// @return the master volume for sounds outputted by TagaroAudio
56KDEGAMES_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.
60KDEGAMES_EXPORT void setVolume(qreal volume);
61
62/// @returns whether an error was detected in the audio backend
63///
64/// Since KGameAudio 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 KGameSound::hasError()
75KDEGAMES_EXPORT bool hasError();
76};
77
78Q_DECLARE_OPERATORS_FOR_FLAGS(KGameAudioScene::Capabilities)
79
80#endif // KGAMEAUDIOSCENE_H
This class exposes general properties of the audio playback context.
Capability
This enumeration represents capabilities which may not be provided by every KGameAudio backend.
@ SupportsLowLatencyPlayback
Playback starts as soon as KGameSound::start is called.
void setListenerPos(QPointF pos)
Sets the position of the listener.
void setVolume(qreal volume)
Sets the master volume for sounds outputted by TagaroAudio.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:59:04 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.