audio/kgameaudioscene.h

/*
    SPDX-FileCopyrightText: 2010 Stefan Majewsky <majewsky@gmx.net>
 
    SPDX-License-Identifier: LGPL-2.0-only
*/
 
#ifndef KGAMEAUDIOSCENE_H
#define KGAMEAUDIOSCENE_H
 
// own
#include "kdegames_export.h"
// Qt
#include <QPointF>
 
/**
 * @namespace KGameAudioScene
 *
 * This class exposes general properties of the audio playback context. Actual
 * sounds are represented in this context by KGameSound instances.
 *
 * The audio scene basically consists of a listener. The position of this
 * listener is relevant when sounds are played at certain positions: The audio
 * channels will then be balanced to make the sound appear to come from that
 * direction.
 *
 * Because there can ogly be one listener, all methods in this class are static.
 *
 * @warning Not all functionally exposed by the API of this class is guaranteed
 *          to be available on the compiled KGameAudio backend. Check
 *          KGameAudioScene::capabilities() if in doubt.
 */
namespace KGameAudioScene
{
/// This enumeration represents capabilities which may not be provided by
/// every KGameAudio backend.
enum Capability {
    /// Playback starts as soon as KGameSound::start is called.
    SupportsLowLatencyPlayback = 1 << 0,
    SupportsPositionalPlayback = 1 << 1,
};
/**
 * Stores a combination of #Capability values.
 */
Q_DECLARE_FLAGS(Capabilities, Capability)
 
/// @return which capabilities are supported by the compiled KGameAudio backend
KDEGAMES_EXPORT Capabilities capabilities();
 
/// @return the position of the listener
KDEGAMES_EXPORT QPointF listenerPos();
/// Sets the position of the listener. The default is (0.0, 0.0), the
/// point of origin.
/// @note Effective only if positional playback is supported.
KDEGAMES_EXPORT void setListenerPos(QPointF pos);
/// @return the master volume for sounds outputted by TagaroAudio
KDEGAMES_EXPORT qreal volume();
/// Sets the master volume for sounds outputted by TagaroAudio. The
/// default is 1.0, which means no volume change, compared to the
/// original sounds. 0.0 means that all sounds are muted.
KDEGAMES_EXPORT void setVolume(qreal volume);
 
/// @returns whether an error was detected in the audio backend
///
/// Since KGameAudio is typically used by games where audio is not an absolutely
/// vital part of the gameplay, we do not need to fail if sound does not work,
/// over even make some sort of deep analysis why something did not work. The
/// user will notice missing sound, and advanced users may investigate
/// the kWarning() messages. That is usually enough. If not, use this method.
///
/// The state of hasError() may theoretically change while the application
/// runs, but in practice, this is very unlikely. (The only tricky part is
/// typically the initial allocation of resources.)
///
/// @sa KGameSound::hasError()
KDEGAMES_EXPORT bool hasError();
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS(KGameAudioScene::Capabilities)
 
#endif // KGAMEAUDIOSCENE_H