class
#include <Magnum/Audio/Context.h>
Context 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::--magnum
-prefixed options unrelated to audio (such as those defined by GL::
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.
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() 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.
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::
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/
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.