ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Audio: updates for the new documentation theme.

pull/225/head
Vladimír Vondruš 8 years ago
parent
d49b8efe9e
commit
c54739d6c9
9 changed files with 74 additions and 97 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 8
      src/Magnum/Audio/AbstractImporter.h
  2. 69
      src/Magnum/Audio/Buffer.h
  3. 6
      src/Magnum/Audio/Context.h
  4. 12
      src/Magnum/Audio/Extensions.h
  5. 22
      src/Magnum/Audio/Listener.h
  6. 5
      src/Magnum/Audio/Playable.h
  7. 4
      src/Magnum/Audio/PlayableGroup.h
  8. 13
      src/Magnum/Audio/Renderer.h
  9. 32
      src/Magnum/Audio/Source.h

8
src/Magnum/Audio/AbstractImporter.h
Unescape View File

@ -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<const char> 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);

69
src/Magnum/Audio/Buffer.h
Unescape View File

@ -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

6
src/Magnum/Audio/Context.h
Unescape View File

@ -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<Extensions::ALC::SOFTX::HRTF>()) {
* // 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

12
src/Magnum/Audio/Extensions.h
Unescape View File

@ -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; } \
};

22
src/Magnum/Audio/Listener.h
Unescape View File

@ -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 <UnsignedInt dimensions> 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<dimensions, Float>& object):
@ -184,7 +183,6 @@ template <UnsignedInt dimensions> class Listener: public SceneGraph::AbstractFea
}
private:
virtual void clean(const MatrixTypeFor<dimensions, Float>& absoluteTransformationMatrix) override;
Matrix4 _soundTransformation;

5
src/Magnum/Audio/Playable.h
Unescape View File

@ -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<UnsignedInt dimensions> class Playable: public SceneGraph::AbstractGrou
}
private:
void clean(const MatrixTypeFor<dimensions, Float>& absoluteTransformationMatrix) override {
Vector3 position = Vector3::pad(absoluteTransformationMatrix.translation(), 0);
if(playables()) {

4
src/Magnum/Audio/PlayableGroup.h
Unescape View File

@ -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;

13
src/Magnum/Audio/Renderer.h
Unescape View File

@ -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) {

32
src/Magnum/Audio/Source.h
Unescape View File

@ -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) {

Write Preview
Loading…
Cancel
Save