Magnum::Audio::Context class

OpenAL 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 = Configuration()) explicit
Constructor.
Context(NoCreateT) explicit noexcept
Construct without creating the underlying OpenAL context.
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 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 hrtfSpecifier() const -> std::string deprecated
HRTF specifier.
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.

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 = Configuration()) explicit

Constructor.

Creates OpenAL context with given configuration.

Magnum::Audio::Context::Context(NoCreateT) 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()

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.

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.

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

HRTF specifier.

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 Extensions namespace in header Extensions.h. 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.

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

Debug output operator.