diff --git a/Doxyfile b/Doxyfile index 58fb558d7..e288b5e36 100644 --- a/Doxyfile +++ b/Doxyfile @@ -280,8 +280,8 @@ ALIASES = \ "fn_alc{1}=`alc\1()`" \ "def_al{1}=`AL_\1`" \ "def_alc{1}=`ALC_\1`" \ - "al_extension{2}=AL_\1_\2" \ - "alc_extension{2}=ALC_\1_\2" + "al_extension{2}=AL_\1_\2" \ + "alc_extension{2}=ALC_\1_\2" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" diff --git a/doc/openal-support.dox b/doc/openal-support.dox index 57667e26d..f99d146f3 100644 --- a/doc/openal-support.dox +++ b/doc/openal-support.dox @@ -34,7 +34,6 @@ The extension implementation is considered complete if all its defined types, functions and enum values are exposed through the API. - @subsection openal-extension-support Extensions Extension | Status @@ -42,7 +41,7 @@ Extension | Status @al_extension{EXT,double} | done @al_extension{EXT,float32} | done -@subsection openal-extension-support OpenAL Soft Extensions +@subsection openal-extension-support-soft OpenAL Soft Extensions Extension | Status ------------------------------------------- | ------ diff --git a/src/Magnum/Audio/Buffer.h b/src/Magnum/Audio/Buffer.h index a5d25cd17..72fafc036 100644 --- a/src/Magnum/Audio/Buffer.h +++ b/src/Magnum/Audio/Buffer.h @@ -58,32 +58,32 @@ class Buffer { Stereo16 = AL_FORMAT_STEREO16, /**< 16-bit interleaved signed stereo */ /** - * @brief 32-bit mono + * @brief 32-bit floating-point mono * - * @requires_al_extension extension @al_extension{EXT,float32} + * @requires_al_extension Extension @al_extension{EXT,float32} */ MonoFloat32 = AL_FORMAT_MONO_FLOAT32, /** - * @brief 32-bit interleaved stereo + * @brief 32-bit interleaved floating-point stereo * - * @requires_al_extension extension @al_extension{EXT,float32} + * @requires_al_extension Extension @al_extension{EXT,float32} */ StereoFloat32 = AL_FORMAT_STEREO_FLOAT32, /** - * @brief 64-bit mono + * @brief 64-bit floating-point mono * - * @requires_al_extension extension @al_extension{EXT,double} + * @requires_al_extension Extension @al_extension{EXT,double} */ MonoDouble = AL_FORMAT_MONO_DOUBLE_EXT, /** - * @brief 64-bit interleaved stereo + * @brief 64-bit interleaved floating-point stereo * - * @requires_al_extension extension @al_extension{EXT,double} + * @requires_al_extension Extension @al_extension{EXT,double} */ - StereoDouble = AL_FORMAT_STEREO_DOUBLE_EXT, + StereoDouble = AL_FORMAT_STEREO_DOUBLE_EXT }; /** diff --git a/src/Magnum/Audio/Context.cpp b/src/Magnum/Audio/Context.cpp index 369325560..089339318 100644 --- a/src/Magnum/Audio/Context.cpp +++ b/src/Magnum/Audio/Context.cpp @@ -134,7 +134,7 @@ bool Context::tryCreateContext(const Configuration& config) { }; /* last valid index in the attributes array */ - int last = 1; + Int last = 1; if(config.isHrtfEnabled() != Configuration::EnabledState::Default) { attributes[++last] = ALC_HRTF_SOFT; diff --git a/src/Magnum/Audio/Context.h b/src/Magnum/Audio/Context.h index 3e4bf9b93..5c0347c84 100644 --- a/src/Magnum/Audio/Context.h +++ b/src/Magnum/Audio/Context.h @@ -38,11 +38,9 @@ #include -#include - -#include "Magnum/Audio/visibility.h" +#include "Magnum/Audio/Audio.h" #include "Magnum/Audio/Buffer.h" - +#include "Magnum/Audio/visibility.h" #ifndef DOXYGEN_GENERATING_OUTPUT typedef struct ALCdevice_struct ALCdevice; @@ -51,8 +49,6 @@ typedef struct ALCcontext_struct ALCcontext; namespace Magnum { namespace Audio { -class Context; - /** @brief Run-time information about OpenAL extension @@ -170,7 +166,7 @@ class MAGNUM_AUDIO_EXPORT Context { * @endcode * * @see @ref isExtensionSupported(const Extension&) const, - * @ref MAGNUM_AUDIO_ASSERT_EXTENSION_SUPPORTED() + * @ref MAGNUM_ASSERT_AUDIO_EXTENSION_SUPPORTED() */ template bool isExtensionSupported() const { return _extensionStatus[T::Index]; @@ -183,7 +179,7 @@ class MAGNUM_AUDIO_EXPORT Context { * hardware, but for general usage prefer @ref isExtensionSupported() const, * as it does most operations in compile time. * @see @ref supportedExtensions(), @ref Extension::extensions(), - * @ref MAGNUM_AUDIO_ASSERT_EXTENSION_SUPPORTED() + * @ref MAGNUM_ASSERT_AUDIO_EXTENSION_SUPPORTED() */ bool isExtensionSupported(const Extension& extension) const { return _extensionStatus[extension._index]; @@ -203,9 +199,13 @@ class MAGNUM_AUDIO_EXPORT Context { std::vector _supportedExtensions; }; +/** +@brief OpenAL context configuration + +@see @ref Context() +*/ class MAGNUM_AUDIO_EXPORT Context::Configuration { public: - /** * @brief Enum for boolean values with a driver specific default * value @@ -216,9 +216,7 @@ class MAGNUM_AUDIO_EXPORT Context::Configuration { Disabled = 2 }; - /** - * @brief Constructor - */ + /** @brief Constructor */ explicit Configuration(): _frequency(44100), _enableHrtf(), @@ -232,6 +230,7 @@ class MAGNUM_AUDIO_EXPORT Context::Configuration { /** * @brief Set sampling rate (in Hz) + * @return Reference to self (for method chaining) * * Default is `44100`. */ @@ -269,8 +268,9 @@ class MAGNUM_AUDIO_EXPORT Context::Configuration { /** * @brief Set hint for how mono sources to support + * @return Reference to self (for method chaining) * - * If not set, no hint will given to OpenAL. + * If set to `-1` (the default), no hint will be given to OpenAL. */ Configuration& setMonoSourcesCount(Int sources) { _monoSources = sources; @@ -286,8 +286,9 @@ class MAGNUM_AUDIO_EXPORT Context::Configuration { /** * @brief Set hint for how stereo sources to support + * @return Reference to self (for method chaining) * - * If not set, no hint will given to OpenAL. + * If set to `-1` (the default), no hint will be given to OpenAL. */ Configuration& setStereoSourcesCount(Int sources) { _stereoSources = sources; @@ -307,7 +308,6 @@ class MAGNUM_AUDIO_EXPORT Context::Configuration { } private: - Int _frequency; EnabledState _enableHrtf; diff --git a/src/Magnum/Audio/Renderer.h b/src/Magnum/Audio/Renderer.h index df66e43c0..bef60aa70 100644 --- a/src/Magnum/Audio/Renderer.h +++ b/src/Magnum/Audio/Renderer.h @@ -61,14 +61,22 @@ class Renderer { OutOfMemory = AL_OUT_OF_MEMORY /**< Unable to allocate memory */ }; + /** + * @brief HRTF status + * + * @see @ref hrtfStatus(), @ref isHrtfEnabled() + * @requires_al_extension Extension @alc_extension{SOFTX,HRTF} or + * @alc_extension{SOFT,HRTF} + */ enum class HrtfStatus: Short { - Disabled = ALC_HRTF_DISABLED_SOFT, /**< HRTF is disabled */ - Enabled = ALC_HRTF_ENABLED_SOFT, /**< HRTF is enabled */ + Disabled = ALC_HRTF_DISABLED_SOFT, /**< HRTF is disabled */ + Enabled = ALC_HRTF_ENABLED_SOFT, /**< HRTF is enabled */ /** * 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. + * @requires_al_extension Extension @alc_extension{SOFT,HRTF} */ Denied = ALC_HRTF_DENIED_SOFT, @@ -76,12 +84,14 @@ class Renderer { * 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. + * @requires_al_extension Extension @alc_extension{SOFT,HRTF} */ Required = ALC_HRTF_REQUIRED_SOFT, /** * HRTF is enabled automatically because the device reported * headphones. + * @requires_al_extension Extension @alc_extension{SOFT,HRTF} */ Detected = ALC_HRTF_HEADPHONES_DETECTED_SOFT, @@ -89,6 +99,7 @@ class Renderer { * The device does not support HRTF with the current format. * Typically this is caused by non-stereo output or an incompatible * output frequency. + * @requires_al_extension Extension @alc_extension{SOFT,HRTF} */ UnsupportedFormat = ALC_HRTF_UNSUPPORTED_FORMAT_SOFT }; @@ -96,6 +107,39 @@ class Renderer { /** @brief Error status */ static Error error() { return Error(alGetError()); } + /** + * @brief Whether HRTFs (Head Related Transfer Functions) are enabled + * + * HRFTs may not be enabled/disabled in a running context. Instead + * create a new @ref Context with HRFTs enabled or disabled. + * @see @ref hrtfStatus(), @ref Audio::Context::Configuration::setHrtf(), + * @fn_al{GetIntegerv} with @def_alc{HRTF_SOFT} + * @requires_al_extension Extension @alc_extension{SOFTX,HRTF} or + * @alc_extension{SOFT,HRTF} + */ + static bool isHrtfEnabled() { + Int enabled; + alGetIntegerv(ALC_HRTF_SOFT, &enabled); + return enabled == ALC_TRUE; + } + + /** + * @brief HRTF status + * + * @see @ref isHrtfEnabled(), @fn_al{GetIntegerv} with + * @def_alc{HRTF_STATUS_SOFT} + * @requires_al_extension Extension @alc_extension{SOFTX,HRTF} or + * @alc_extension{SOFT,HRTF} + */ + static HrtfStatus hrtfStatus() { + if(!Context::current()->isExtensionSupported()) + return isHrtfEnabled() ? HrtfStatus::Enabled : HrtfStatus::Disabled; + + Int status; + alGetIntegerv(ALC_HRTF_STATUS_SOFT, &status); + return HrtfStatus(status); + } + /** @{ @name Listener positioning */ /** @@ -291,40 +335,6 @@ class Renderer { alDistanceModel(ALenum(model)); } - /** - * @brief 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. - * @see @fn_al{GetIntegerv} with @def_alc{HRTF_SOFT}, - * Audio::Configuration::isHrtfEnabled(), - * Audio::Configuration::setHrtfEnabled() - */ - static bool isHrtfEnabled() { - Int enabled = ALC_FALSE; - alGetIntegerv(ALC_HRTF_SOFT, &enabled); - return enabled == ALC_TRUE; - } - - /** - * @brief HRTF status - * - * @requires_alc_extension for only @ref HrtfStatus::Enabled and - * @ref HrtfStatus::Disabled, extension @alc_extension{SOFTX,HRTF} - * @requires_alc_extension for any @ref HrtfStatus, @alc_extension{SOFT,HRTF} - * @see @fn_al{GetIntegerv} with @def_alc{HRTF_STATUS_SOFT}, - * @ref isHrtfEnabled() - */ - static HrtfStatus hrtfStatus() { - if(!Context::current()->isExtensionSupported()) { - return (isHrtfEnabled()) ? HrtfStatus::Enabled : HrtfStatus::Disabled; - } - - Int status = ALC_HRTF_DISABLED_SOFT; - alGetIntegerv(ALC_HRTF_STATUS_SOFT, &status); - return HrtfStatus(status); - } - /*@}*/ };