From c54739d6c9423dae9f08ea868b60b0ff02c519a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 21 Dec 2017 15:02:48 +0100 Subject: [PATCH] Audio: updates for the new documentation theme. --- src/Magnum/Audio/AbstractImporter.h | 8 ++-- src/Magnum/Audio/Buffer.h | 69 ++++++++++------------------- src/Magnum/Audio/Context.h | 6 ++- src/Magnum/Audio/Extensions.h | 12 ++--- src/Magnum/Audio/Listener.h | 22 +++++---- src/Magnum/Audio/Playable.h | 5 +-- src/Magnum/Audio/PlayableGroup.h | 4 +- src/Magnum/Audio/Renderer.h | 13 +++--- src/Magnum/Audio/Source.h | 32 ++++++------- 9 files changed, 74 insertions(+), 97 deletions(-) diff --git a/src/Magnum/Audio/AbstractImporter.h b/src/Magnum/Audio/AbstractImporter.h index ba969be2a..c69f5ea99 100644 --- a/src/Magnum/Audio/AbstractImporter.h +++ b/src/Magnum/Audio/AbstractImporter.h @@ -43,7 +43,7 @@ Provides interface for importing various audio formats. See @ref plugins for more information and `*Importer` classes in @ref Audio namespace for available importer plugins. -## Subclassing +@section Audio-AbstractImporter-subclassing Subclassing Plugin implements function @ref doFeatures(), @ref doIsOpened(), one of or both @ref doOpenData() and @ref doOpenFile() functions, function @ref doClose() and @@ -60,7 +60,7 @@ checked by the implementation: - All `do*()` implementations working on opened file are called only if there is any file opened. -Plugin interface string is `"cz.mosra.magnum.Audio.AbstractImporter/0.1"`. +Plugin interface string is @cpp "cz.mosra.magnum.Audio.AbstractImporter/0.1" @ce. @attention @ref Corrade::Containers::Array instances returned from the plugin should *not* use anything else than the default deleter, otherwise this can @@ -108,7 +108,7 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractManagi * * Closes previous file, if it was opened, and tries to open given * file. Available only if @ref Feature::OpenData is supported. Returns - * `true` on success, `false` otherwise. + * @cpp true @ce on success, @cpp false @ce otherwise. * @see @ref features(), @ref openFile() */ bool openData(Containers::ArrayView data); @@ -117,7 +117,7 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractManagi * @brief Open file * * Closes previous file, if it was opened, and tries to open given - * file. Returns `true` on success, `false` otherwise. + * file. Returns @cpp true @ce on success, @cpp false @ce otherwise. * @see @ref features(), @ref openData() */ bool openFile(const std::string& filename); diff --git a/src/Magnum/Audio/Buffer.h b/src/Magnum/Audio/Buffer.h index 4f41990ed..0c64bd0dd 100644 --- a/src/Magnum/Audio/Buffer.h +++ b/src/Magnum/Audio/Buffer.h @@ -58,162 +58,139 @@ class Buffer { Stereo16 = AL_FORMAT_STEREO16, /**< 16-bit interleaved signed stereo */ /** - * @brief 8-bit mono [A-Law Compressed Sound Format](https://en.wikipedia.org/wiki/A-law_algorithm) - * + * 8-bit mono [A-Law Compressed Sound Format](https://en.wikipedia.org/wiki/A-law_algorithm) * @requires_al_extension Extension @al_extension{EXT,ALAW} */ MonoALaw = AL_FORMAT_MONO_ALAW_EXT, /** - * @brief 8-bit interleaved stereo [A-Law Compressed Sound Format](https://en.wikipedia.org/wiki/A-law_algorithm) - * + * 8-bit interleaved stereo [A-Law Compressed Sound Format](https://en.wikipedia.org/wiki/A-law_algorithm) * @requires_al_extension Extension @al_extension{EXT,ALAW} */ StereoALaw = AL_FORMAT_STEREO_ALAW_EXT, /** - * @brief 8-bit mono [μ-Law Compressed Sound Format](https://en.wikipedia.org/wiki/Μ-law_algorithm) - * + * 8-bit mono [μ-Law Compressed Sound Format](https://en.wikipedia.org/wiki/Μ-law_algorithm) * @requires_al_extension Extension @al_extension{EXT,MULAW} */ MonoMuLaw = AL_FORMAT_MONO_MULAW_EXT, /** - * @brief 8-bit interleaved [μ-Law Compressed Sound Format](https://en.wikipedia.org/wiki/Μ-law_algorithm) - * + * 8-bit interleaved [μ-Law Compressed Sound Format](https://en.wikipedia.org/wiki/Μ-law_algorithm) * @requires_al_extension Extension @al_extension{EXT,MULAW} */ StereoMuLaw = AL_FORMAT_STEREO_MULAW_EXT, /** - * @brief 32-bit floating-point mono - * + * 32-bit floating-point mono * @requires_al_extension Extension @al_extension{EXT,float32} */ MonoFloat = AL_FORMAT_MONO_FLOAT32, /** - * @brief 32-bit interleaved floating-point stereo - * + * 32-bit interleaved floating-point stereo * @requires_al_extension Extension @al_extension{EXT,float32} */ StereoFloat = AL_FORMAT_STEREO_FLOAT32, /** - * @brief 64-bit floating-point mono - * + * 64-bit floating-point mono * @requires_al_extension Extension @al_extension{EXT,double} */ MonoDouble = AL_FORMAT_MONO_DOUBLE_EXT, /** - * @brief 64-bit interleaved floating-point stereo - * + * 64-bit interleaved floating-point stereo * @requires_al_extension Extension @al_extension{EXT,double} */ StereoDouble = AL_FORMAT_STEREO_DOUBLE_EXT, /** - * @brief 8-bit unsigned quadrophonic - * + * 8-bit unsigned quadrophonic * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Quad8 = AL_FORMAT_QUAD8, /** - * @brief 16-bit signed quadrophonic - * + * 16-bit signed quadrophonic * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Quad16 = AL_FORMAT_QUAD16, /** - * @brief 32-bit interleaved floating-point quadrophonic - * + * 32-bit interleaved floating-point quadrophonic * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Quad32 = AL_FORMAT_QUAD32, /** - * @brief 8-bit unsigned rear - * + * 8-bit unsigned rear * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Rear8 = AL_FORMAT_REAR8, /** - * @brief 16-bit signed rear - * + * 16-bit signed rear * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Rear16 = AL_FORMAT_REAR16, /** - * @brief 32-bit interleaved floating-point rear - * + * 32-bit interleaved floating-point rear * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Rear32 = AL_FORMAT_REAR32, /** - * @brief 8-bit unsigned 5.1 surround - * + * 8-bit unsigned 5.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround51Channel8 = AL_FORMAT_51CHN8, /** - * @brief 16-bit signed 5.1 surround - * + * 16-bit signed 5.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround51Channel16 = AL_FORMAT_51CHN16, /** - * @brief 32-bit interleaved floating-point 5.1 surround - * + * 32-bit interleaved floating-point 5.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround51Channel32 = AL_FORMAT_51CHN32, /** - * @brief 8-bit unsigned 6.1 surround - * + * 8-bit unsigned 6.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround61Channel8 = AL_FORMAT_61CHN8, /** - * @brief 16-bit signed 6.1 surround - * + * 16-bit signed 6.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround61Channel16 = AL_FORMAT_61CHN16, /** - * @brief 32-bit interleaved floating-point 6.1 surround - * + * 32-bit interleaved floating-point 6.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround61Channel32 = AL_FORMAT_61CHN32, /** - * @brief 8-bit unsigned 7.1 surround - * + * 8-bit unsigned 7.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround71Channel8 = AL_FORMAT_71CHN8, /** - * @brief 16-bit signed 7.1 surround - * + * 16-bit signed 7.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround71Channel16 = AL_FORMAT_71CHN16, /** - * @brief 32-bit interleaved floating-point 7.1 surround - * + * 32-bit interleaved floating-point 7.1 surround * @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */ Surround71Channel32 = AL_FORMAT_71CHN32 diff --git a/src/Magnum/Audio/Context.h b/src/Magnum/Audio/Context.h index 5b2bf5bca..80f5184c2 100644 --- a/src/Magnum/Audio/Context.h +++ b/src/Magnum/Audio/Context.h @@ -270,7 +270,8 @@ class MAGNUM_AUDIO_EXPORT Context { * * Extensions usable with this function are listed in @ref Extensions * namespace in header @ref Extensions.h. Example usage: - * @code + * + * @code{.cpp} * if(Context::current().isExtensionSupported()) { * // amazing binaural audio * } else { @@ -445,7 +446,8 @@ Useful for initial checks on availability of required features. By default, if assertion fails, an message is printed to error output and the application aborts. If `CORRADE_NO_ASSERT` is defined, this macro does nothing. Example usage: -@code + +@code{.cpp} MAGNUM_ASSERT_AUDIO_EXTENSION_SUPPORTED(Extensions::ALC::SOFTX::HRTF); @endcode diff --git a/src/Magnum/Audio/Extensions.h b/src/Magnum/Audio/Extensions.h index ece1cf38e..993e01ab5 100644 --- a/src/Magnum/Audio/Extensions.h +++ b/src/Magnum/Audio/Extensions.h @@ -37,9 +37,9 @@ namespace Magnum { namespace Audio { /** @brief Compile-time information about OpenAL extensions -Each extension is `struct` named hierarchically by prefix, vendor and +Each extension is a @cpp struct @ce named hierarchically by prefix, vendor and extension name taken from list at @ref openal-support, for example -`ALC::SOFTX::HRTF`. +@cpp ALC::SOFTX::HRTF @ce. Each struct has the same public methods as @ref Extension class (@ref Extension::requiredVersion() "requiredVersion()", @@ -61,15 +61,15 @@ information. namespace Extensions { #ifndef DOXYGEN_GENERATING_OUTPUT -#define _extension(prefix, vendor, extension) \ +#define _extension(prefix, vendor, extension) \ struct extension { \ - enum: std::size_t { Index = __LINE__-1 }; \ + enum: std::size_t { Index = __LINE__-1 }; \ constexpr static const char* string() { return #prefix "_" #vendor "_" #extension; } \ }; -#define _extension_rev(prefix, vendor, extension) \ +#define _extension_rev(prefix, vendor, extension) \ struct extension { \ - enum: std::size_t { Index = __LINE__-1 }; \ + enum: std::size_t { Index = __LINE__-1 }; \ constexpr static const char* string() { return #prefix "_" #extension "_" #vendor; } \ }; diff --git a/src/Magnum/Audio/Listener.h b/src/Magnum/Audio/Listener.h index c3272580d..67bf8f752 100644 --- a/src/Magnum/Audio/Listener.h +++ b/src/Magnum/Audio/Listener.h @@ -56,28 +56,27 @@ namespace Implementation { Feature which manages the position, orientation and gain of the OpenAL listener for an @ref SceneGraph::Object. -## Usage +@section Audio-Listener-usage Usage Minimal scene setup for a @ref Listener3D will require the following code: -@code +@code{.cpp} Scene3D scene; Object3D object{&scene}; Listener3D listener{object}; // ... every frame, update the listener to changes in object transformation: listener.update({}); - @endcode For two dimensional scenes simply replace all `3D` with `2D`. -### Using Listener with PlayableGroup +@subsection Audio-Listener-usage-playablegroup Using Listener with PlayableGroup When using @ref PlayableGroup, you can update the listener and groups as follows: -@code +@code{.cpp} // ... Listener3D listener{object}; PlayableGroup3D group1, group2; @@ -86,7 +85,7 @@ PlayableGroup3D group1, group2; listener.update({group1, group2}); @endcode -## Active Listener +@section Audio-Listener-active-listener Active listener There can only be at the most *one* active listener at a given time, i.e. the one on which @ref Listener::update() was called last. This is because OpenAL @@ -96,7 +95,7 @@ between them for cinematics for example. @ref AbstractObject::setClean() will not affect inactive listeners. -## Sound Transformation +@section Audio-Listener-sound-transformation Sound transformation @ref Listener::setSoundTransformation() enables you to set a transformation matrix which is applied to the listeners orientation and position before passed @@ -119,10 +118,10 @@ template class Listener: public SceneGraph::AbstractFea * @brief Constructor * @param object Object this listener belongs to * - * Creates a listener with a forward vector of `{0.0f, 0.0f, -1.0f}` and - * up vector of `{0.0f, 1.0f, 0.0f}`. These vectors cannot be changed, - * the listeners orientation and translation can be instead affected by - * `object` or via @ref Listener::setSoundTransformation(). + * Creates a listener with a forward vector of `{0.0f, 0.0f, -1.0f}` + * and up vector of `{0.0f, 1.0f, 0.0f}`. These vectors cannot be + * changed, the listeners orientation and translation can be instead + * affected by @p object or via @ref Listener::setSoundTransformation(). * @see @ref setGain() */ explicit Listener(SceneGraph::AbstractObject& object): @@ -184,7 +183,6 @@ template class Listener: public SceneGraph::AbstractFea } private: - virtual void clean(const MatrixTypeFor& absoluteTransformationMatrix) override; Matrix4 _soundTransformation; diff --git a/src/Magnum/Audio/Playable.h b/src/Magnum/Audio/Playable.h index d5b681732..171fa8038 100644 --- a/src/Magnum/Audio/Playable.h +++ b/src/Magnum/Audio/Playable.h @@ -49,9 +49,9 @@ namespace Magnum { namespace Audio { Feature which manages the position, orientation and gain of a @ref Source for an @ref SceneGraph::Object. -## Usage +@section Audio-Playable-usage Usage -@code +@code{.cpp} Object3D object; Source source; Playable3D playable{object, source}; @@ -140,7 +140,6 @@ template class Playable: public SceneGraph::AbstractGrou } private: - void clean(const MatrixTypeFor& absoluteTransformationMatrix) override { Vector3 position = Vector3::pad(absoluteTransformationMatrix.translation(), 0); if(playables()) { diff --git a/src/Magnum/Audio/PlayableGroup.h b/src/Magnum/Audio/PlayableGroup.h index f2522ae00..4909feadc 100644 --- a/src/Magnum/Audio/PlayableGroup.h +++ b/src/Magnum/Audio/PlayableGroup.h @@ -52,9 +52,9 @@ Manages @ref Audio::Playable features and provides means of setting gain or transformation of a group of Playables, aswell as the ability of playing, pausing, stopping or cleaning all sources of all Playables. -## Usage +@section Audio-PlayableGroup-usage Usage -@code +@code{.cpp} Object3D object; Source source; PlayableGroup3D group; diff --git a/src/Magnum/Audio/Renderer.h b/src/Magnum/Audio/Renderer.h index 247e7840d..f99f19242 100644 --- a/src/Magnum/Audio/Renderer.h +++ b/src/Magnum/Audio/Renderer.h @@ -77,7 +77,7 @@ class Renderer { /** * @brief Set listener position * - * Default is `{0.0f, 0.0f, 0.0f}`. + * Default is @cpp {0.0f, 0.0f, 0.0f} @ce. * @see @fn_al{Listenerfv} with @def_al{POSITION} */ static void setListenerPosition(const Vector3& position) { @@ -136,7 +136,7 @@ class Renderer { /** * @brief Set listener velocity * - * Default is `{0.0f, 0.0f, 0.0f}`. + * Default is @cpp {0.0f, 0.0f, 0.0f} @ce. * @see @fn_al{Listenerfv} with @def_al{VELOCITY} */ static void setListenerVelocity(const Vector3& velocity) { @@ -195,8 +195,8 @@ class Renderer { /** * @brief Set listener gain * - * Default is `1.0f`, which means that the sound is unattenuated. - * If set to `0.0f`, all sound is muted. + * Default is @cpp 1.0f @ce, which means that the sound is + * unattenuated. If set to @cpp 0.0f @ce, all sound is muted. * @see @fn_al{Listenerf} with @def_al{GAIN} */ static void setListenerGain(Float gain) { @@ -214,7 +214,8 @@ class Renderer { /** * @brief Set Doppler factor * - * Default is `1.0f`. If set to `0.0f`, the effect is disabled. + * Default is @cpp 1.0f @ce. If set to @cpp 0.0f @ce, the effect is + * disabled. * @see @ref setSpeedOfSound(), @fn_al{DopplerFactor} */ static void setDopplerFactor(Float factor) { @@ -232,7 +233,7 @@ class Renderer { /** * @brief Set speed of sound * - * Default is `343.3f` (meters per second). + * Default is @cpp 343.3f @ce (meters per second). * @see @ref setDopplerFactor(), @fn_al{SpeedOfSound} */ static void setSpeedOfSound(Float speed) { diff --git a/src/Magnum/Audio/Source.h b/src/Magnum/Audio/Source.h index 77497fb62..82e06363e 100644 --- a/src/Magnum/Audio/Source.h +++ b/src/Magnum/Audio/Source.h @@ -97,7 +97,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set position * @return Reference to self (for method chaining) * - * Default is `{0.0f, 0.0f, 0.0f}`. + * Default is @cpp {0.0f, 0.0f, 0.0f} @ce. * @see @ref setRelative(), @fn_al{Sourcefv} with @def_al{POSITION} */ Source& setPosition(const Vector3& position) { @@ -127,7 +127,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set velocity * @return Reference to self (for method chaining) * - * Default is `{0.0f, 0.0f, 0.0f}`. + * Default is @cpp {0.0f, 0.0f, 0.0f} @ce. * @see @ref setRelative(), @fn_al{Sourcefv} with @def_al{VELOCITY} */ Source& setVelocity(const Vector3& velocity) { @@ -158,7 +158,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Interpret source relatively to listener * * When enabled, source position, direction and velocity will be - * interpreted relatively to listener. Default is `false`. + * interpreted relatively to listener. Default is @cpp false @ce. * @see @ref setPosition(), @ref setDirection(), @ref setVelocity(), * @fn_al{Sourcei} with @def_al{SOURCE_RELATIVE} */ @@ -185,8 +185,8 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set gain * @return Reference to self (for method chaining) * - * Default is `1.0f`, which means that the sound is unattenuated. - * If set to `0.0f`, the source is muted. + * Default is @cpp 1.0f @ce, which means that the sound is + * unattenuated. If set to @cpp 0.0f @ce, the source is muted. * @see @ref setMinGain(), @ref setMaxGain(), @fn_al{Sourcef} with * @def_al{GAIN} */ @@ -212,7 +212,7 @@ class MAGNUM_AUDIO_EXPORT Source { * * If effective gain is lower than min gain, min gain is used. Note * that this is done before listener gain is applied. Default is - * `0.0f`. + * @cpp 0.0f @ce. * @see @ref setMaxGain(), @ref setGain(), @fn_al{Sourcef} with * @def_al{MIN_GAIN} */ @@ -238,7 +238,7 @@ class MAGNUM_AUDIO_EXPORT Source { * * If effective gain is higher than max gain, max gain is used. Note * that this is done before listener gain is applied. Default is - * `1.0f`. If set to `0.0f`, the source is muted. + * @cpp 1.0f @ce. If set to @cpp 0.0f @ce, the source is muted. * @see @ref setMinGain(), @ref setGain(), @fn_al{Sourcef} with * @def_al{MIN_GAIN} */ @@ -261,7 +261,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set reference distance * @return Reference to self (for method chaining) * - * Default is `1.0f`. Distance at which the listener will + * Default is @cpp 1.0f @ce. Distance at which the listener will * experience @ref gain() (or @ref minGain(), @ref maxGain() * if gain was clamped). * @see @ref setRolloffFactor(), @fn_al{Sourcef} with @@ -294,7 +294,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set rolloff factor * @return Reference to self (for method chaining) * - * Default is `1.0f`. + * Default is @cpp 1.0f @ce. * @see @ref setReferenceDistance(), @fn_al{Sourcef} with * @def_al{ROLLOFF_FACTOR} */ @@ -355,8 +355,8 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set direction * @return Reference to self (for method chaining) * - * Default is `{0.0f, 0.0f, 0.0f}`, which means that the source is not - * directional. + * Default is @cpp {0.0f, 0.0f, 0.0f} @ce, which means that the source + * is not directional. * @see @ref setInnerConeAngle(), @ref setOuterConeAngle(), * @ref setRelative(), @fn_al{Sourcefv} with @def_al{DIRECTION} */ @@ -388,7 +388,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @return Reference to self (for method chaining) * * Has effect only if the source is directional. Default is - * `360.0_degf`. + * @cpp 360.0_degf @ce. * @see @ref setOuterConeAngle(), @ref setDirection(), @fn_al{Sourcef} * with @def_al{CONE_INNER_ANGLE} */ @@ -412,7 +412,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @return Reference to self (for method chaining) * * Has effect only if the source is directional. Default is - * `360.0_degf`. + * @cpp 360.0_degf @ce. * @see @ref setInnerConeAngle(), @ref setDirection(), * @ref setOuterConeGain() @fn_al{Sourcef} with * @def_al{CONE_OUTER_ANGLE} @@ -437,7 +437,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @return Reference to self (for method chaining) * * The factor with which the gain is multiplied outside the outer cone. - * Default is `0.0f`. + * Default is @cpp 0.0f @ce. * @see @ref setGain(), @ref setOuterConeAngle(), @fn_al{Sourcef} with * @def_al{CONE_OUTER_GAIN} */ @@ -460,7 +460,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set pitch * @return Reference to self (for method chaining) * - * Default is `1.0f`. + * Default is @cpp 1.0f @ce. * @see @fn_al{Sourcef} with @def_al{PITCH} */ Source& setPitch(Float pitch) { @@ -626,7 +626,7 @@ class MAGNUM_AUDIO_EXPORT Source { * @brief Set source looping * @return Reference to self (for method chaining) * - * Default is `false`. + * Default is @cpp false @ce. * @see @fn_al{Sourcei} with @def_al{LOOPING} */ Source& setLooping(bool loop) {