Magnum::Audio::Context class
#include <Magnum/Audio/Context.h>

OpenAL context.

Provides access to OpenAL version and extension information and manages Magnum's internal OpenAL context.

Command-line options

The context is configurable through command-line options, that can be passed for example from the Platform::*Application classes. Usage:

<application> [--magnum-help] [--magnum-disable-extensions LIST]
              [--magnum-log default|quiet|verbose] ...

Arguments:

  • ... — main application arguments (see -h or --help for details)
  • --magnum-help — display this help message and exit
  • --magnum-disable-extensions LIST — API extensions to disable (environment: MAGNUM_DISABLE_EXTENSIONS)
  • --magnum-log default|quiet|verbose — console logging (environment: MAGNUM_LOG) (default: default)

Note that all options are prefixed with --magnum- to avoid conflicts with options passed to the application itself. Options that don't have this prefix are completely ignored, see documentation of the Utility::Arguments class for details. Moreover, --magnum-prefixed options unrelated to audio (such as those defined by GL::Context) are ignored as well. In order to provide a complete help and command-line argument diagnostic, you should instantiate this class after GL::Context.

Public types

class Configuration
OpenAL context configuration.
enum class HrtfStatus: ALenum { Disabled = ALC_HRTF_DISABLED_SOFT, Enabled = ALC_HRTF_ENABLED_SOFT, Denied = ALC_HRTF_DENIED_SOFT, Required = ALC_HRTF_REQUIRED_SOFT, Detected = ALC_HRTF_HEADPHONES_DETECTED_SOFT, UnsupportedFormat = ALC_HRTF_UNSUPPORTED_FORMAT_SOFT }
HRTF status.

Public static functions

static auto deviceSpecifierStrings() -> std::vector<std::string>
All device specifier strings.
static auto hasCurrent() -> bool
Whether there is any current context.
static auto current() -> Context&
Current context.

Constructors, destructors, conversion operators

Context(const Configuration& configuration, Int argc, const char*const* argv) explicit
Constructor.
Context(const Configuration& configuration) explicit
Context(Int argc, const char*const* argv) explicit
Context() explicit
Context(NoCreateT, Int argc, const char*const* argv) explicit noexcept
Construct without creating the underlying OpenAL context.
Context(NoCreateT) explicit noexcept
Context(const Context&) deleted
Copying is not allowed.
Context(Context&& other) noexcept
Move constructor.
~Context()
Destructor.

Public functions

auto operator=(const Context&) -> Context& deleted
Copying is not allowed.
auto operator=(Context&& other) -> Context& deleted
Move assignment is not allowed.
void create(const Configuration& configuration)
Complete the context setup and exit on failure.
auto tryCreate(const Configuration& configuration) -> bool
Complete the context setup.
auto frequency() const -> Int new in Git master
Sampling rate in Hz.
auto isHrtfEnabled() const -> bool
Whether HRTFs (Head Related Transfer Functions) are enabled.
auto hrtfStatus() const -> HrtfStatus
HRTF status.
auto hrtfSpecifierString() const -> std::string
HRTF specifier.
auto monoSourceCount() const -> Int new in Git master
Count of supported mono sources.
auto stereoSourceCount() const -> Int new in Git master
Count of supported stereo sources.
auto refreshRate() const -> Int new in Git master
Refresh rate in Hz.
auto deviceSpecifierString() const -> std::string
Device specifier string.
auto vendorString() const -> std::string
Vendor string.
auto rendererString() const -> std::string
Renderer string.
auto versionString() const -> std::string
Version string.
auto extensionStrings() const -> std::vector<std::string>
Extension strings.
auto supportedExtensions() const -> const std::vector<Extension>&
Supported extensions.
template<class T>
auto isExtensionSupported() const -> bool
Whether given extension is supported.
auto isExtensionSupported(const Extension& extension) const -> bool
Whether given extension is supported.
template<class T>
auto isExtensionDisabled() const -> bool
Whether given extension is disabled.
auto isExtensionDisabled(const Extension& extension) const -> bool
Whether given extension is disabled.

Enum documentation

enum class Magnum::Audio::Context::HrtfStatus: ALenum

HRTF status.

Enumerators
Disabled

HRTF is disabled
Enabled

HRTF is enabled
Denied

HRTF is disabled because it is not allowed on the device. This may be caused by invalid resource permissions, or an other user configuration that disallows HRTF.
Required

HRTF is enabled because it must be used on the device. This may be caused by a device that can only use HRTF, or other user configuration that forces HRTF to be used.
Detected

HRTF is enabled automatically because the device reported headphones.
UnsupportedFormat

The device does not support HRTF with the current format. Typically this is caused by non-stereo output or an incompatible output frequency.

Function documentation

static std::vector<std::string> Magnum::Audio::Context::deviceSpecifierStrings()

All device specifier strings.

static bool Magnum::Audio::Context::hasCurrent()

Whether there is any current context.

static Context& Magnum::Audio::Context::current()

Current context.

Expect that there is current context.

Magnum::Audio::Context::Context(const Configuration& configuration, Int argc, const char*const* argv) explicit

Constructor.

Parses command-line arguments, and creates OpenAL context with given configuration.

Magnum::Audio::Context::Context(const Configuration& configuration) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Audio::Context::Context(Int argc, const char*const* argv) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Audio::Context::Context() explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Audio::Context::Context(NoCreateT, Int argc, const char*const* argv) explicit noexcept

Construct without creating the underlying OpenAL context.

Useful in cases where you need to defer context creation to a later time, for example to do a more involved configuration. Call create() or tryCreate() to create the actual context.

Magnum::Audio::Context::Context(NoCreateT) explicit noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Magnum::Audio::Context::~Context()

Destructor.

Destroys OpenAL context.

void Magnum::Audio::Context::create(const Configuration& configuration)

Complete the context setup and exit on failure.

Finalizes the setup after the class was created using Context(NoCreateT). If any error occurs, a message is printed to error output and the application exits. See tryCreate() for an alternative.

bool Magnum::Audio::Context::tryCreate(const Configuration& configuration)

Complete the context setup.

Unlike create() just prints a message to error output and returns false on error.

Int Magnum::Audio::Context::frequency() const new in Git master

Sampling rate in Hz.

bool Magnum::Audio::Context::isHrtfEnabled() const

Whether HRTFs (Head Related Transfer Functions) are enabled.

HRFTs may not be enabled/disabled in a running context. Instead create a new Context with HRFTs enabled or disabled.

HrtfStatus Magnum::Audio::Context::hrtfStatus() const

HRTF status.

std::string Magnum::Audio::Context::hrtfSpecifierString() const

HRTF specifier.

Name of the HRTF being used.

Int Magnum::Audio::Context::monoSourceCount() const new in Git master

Count of supported mono sources.

Int Magnum::Audio::Context::stereoSourceCount() const new in Git master

Count of supported stereo sources.

Int Magnum::Audio::Context::refreshRate() const new in Git master

Refresh rate in Hz.

std::string Magnum::Audio::Context::deviceSpecifierString() const

Device specifier string.

std::string Magnum::Audio::Context::vendorString() const

Vendor string.

std::string Magnum::Audio::Context::rendererString() const

Renderer string.

std::string Magnum::Audio::Context::versionString() const

Version string.

std::vector<std::string> Magnum::Audio::Context::extensionStrings() const

Extension strings.

The result is not cached, repeated queries will result in repeated OpenAL calls. Note that this function returns list of all extensions reported by the driver (even those not supported by Magnum), see supportedExtensions(), Extension::extensions() or isExtensionSupported() for alternatives.

const std::vector<Extension>& Magnum::Audio::Context::supportedExtensions() const

Supported extensions.

The list contains only extensions from OpenAL versions newer than the current.

template<class T>
bool Magnum::Audio::Context::isExtensionSupported() const

Whether given extension is supported.

Extensions usable with this function are listed in the Extensions namespace in the Magnum/Audio/Extensions.h header. Example usage:

if(Audio::Context::current().isExtensionSupported<Audio::Extensions::ALC::SOFTX::HRTF>()) {
    // amazing binaural audio
} else {
    // probably left/right stereo only
}

bool Magnum::Audio::Context::isExtensionSupported(const Extension& extension) const

Whether given extension is supported.

Can be used e.g. for listing extensions available on current hardware, but for general usage prefer isExtensionSupported() const, as it does most operations in compile time.

template<class T>
bool Magnum::Audio::Context::isExtensionDisabled() const

Whether given extension is disabled.

Can be used for detecting driver bug workarounds. Disabled extensions return false in isExtensionSupported() even if they are advertised as being supported by the driver.

bool Magnum::Audio::Context::isExtensionDisabled(const Extension& extension) const

Whether given extension is disabled.

Can be used e.g. for listing extensions available on current hardware, but for general usage prefer isExtensionDisabled() const, as it does most operations in compile time.

Debug& operator<<(Debug& debug, Context::HrtfStatus value)

Debug output operator.