More work on user manuals

Documentation/Manuals/Native/User/importingAudio.md

@@ -0,0 +1,85 @@
+Importing audio 						{#importingAudio}
+===============
+
+Audio in Banshee is represented in the form of an @ref bs::AudioClip "AudioClip" object. An audio clip is a resource, meaning it can be imported, saved and loaded as we described in the Resource manuals.
+
+Different audio file formats are supported depending on which audio backend is used:
+ - OpenAudio (default)
+  - .FLAC 
+  - .OGG
+  - .WAV
+ - FMOD
+  - .AIFF
+  - .ASF
+  - .ASX
+  - .DLS
+  - .FLAC
+  - .MIDI
+  - .MP3
+  - .OGG
+  - .WAV
+  - .WMA
+  
+~~~~~~~~~~~~~{.cpp}
+// Import an audio clip from disk
+HAudioClip clip = gImporter().import<AudioClip>("myAudioClip.ogg");
+~~~~~~~~~~~~~
+
+# Customizing import
+Import can be customized by providing a @ref bs::AudioClipImportOptions "AudioClipImportOptions" object to the importer.
+
+~~~~~~~~~~~~~{.cpp}
+auto importOptions = AudioClipImportOptions::create();
+// Set required options here (as described below)
+
+HAudioClip clip = gImporter().import<AudioClip>("myAudioClip.ogg", importOptions);
+~~~~~~~~~~~~~
+
+A variety of properties can be customized on import, the most important of which being audio format, compression/streaming mode, bit depth and 2D/3D toggle.
+
+## Audio format
+Audio format determines in what format will audio data be stored in, once imported. It is controlled by @ref bs::AudioClipImportOptions::setFormat "AudioClipImportOptions::setFormat()" which accepts @ref bs::AudioFormat "AudioFormat" enumeration as a parameter.
+
+There are only two formats supported:
+ - PCM - This is raw uncompressed audio data stored in pulse-code modulation format
+ - Vorbis - This is compressed audio data stored in the Vorbis format
+ 
+In most cases you want to use the Vorbis compressed format, in order to save on memory use. Using uncompressed audio can be useful when:
+ - No quality loss can be accepted
+ - CPU overhead of decompression is too high (see streaming/decompression section below)
+ 
+~~~~~~~~~~~~~{.cpp}
+importOptions->setFormat(AudioFormat::Vorbis);
+~~~~~~~~~~~~~
+
+## Streaming/decompression
+When an audio clip is loaded for playback, you can choose how is its data accessed, in order to tweak required memory and/or CPU usage by setting the read mode though @ref bs::AudioClipImportOptions::setReadMode "AudioClipImportOptions::setReadMode()".
+
+Available read modes are part of the @ref bs::AudioReadMode "AudioReadMode" enumeration. They are:
+ - **LoadDecompressed** - When an audio clip is first loaded it will immediately be decompressed in entirety, and playback will then proceed by using the uncompressed version. This uses more memory as the uncompressed clip is present in its entirety in memory, but has very small CPU overhead during playback due to it not requiring decompression. This option is not relevant for clips in PCM format, as they are already decompressed.
+ - **LoadCompressed** - Audio clip will be loaded compressed into memory, and then decompressed as the playback requires. This requires only the decompressed audio data to be in memory, having much smaller memory footprint than the method above. However it has a higher CPU overhead as decompression is done on-the-fly. This option is not relevant for clips in PCM format, as they are already decompressed.
+ - **Streaming** - Audio clip data will not be loaded into memory until playback starts. At that point only the required portion of the clip will be loaded and older portions unloaded, as playback proceeds. If the source data is compressed, this means the decompression is also performed on-the-fly, same as with **LoadCompressed**. This uses the least amount of memory, since it doesn't require the audio clip to be loaded fully in memory, but has a decompression overhead if source is compressed(same as **LoadCompressed**), as well as a IO overhead as it needs to read data from the storage device during playback.
+ 
+In most cases you will want to use **LoadCompressed** for smaller audio clips (like audio cues), and **Streaming** for longer clips (like music).
+
+~~~~~~~~~~~~~{.cpp}
+importOptions->setReadMode(AudioReadMode::LoadCompressed);
+~~~~~~~~~~~~~
+
+## Bit depth
+@ref bs::AudioClipImportOptions::setBitDepth "AudioClipImportOptions::setBitDepth()" controls how many bits will a single audio sample be stored in. Smaller values yield smaller memory footprint, but lesser quality, and the other way around.
+
+In general value of 16 is enough (the default). Other accepted values are 8, 24 and 32.
+
+~~~~~~~~~~~~~{.cpp}
+importOptions->setBitDepth(24);
+~~~~~~~~~~~~~
+
+## 2D/3D
+Audio files can be played back in 2D or 3D mode. 2D audio is the familiar audio playback, like music. 3D audio will control playback volume, pitch and other properties based on the position and velocity of the listener compared to the audio source. This can be controlled by setting the @ref bs::AudioClipImportOptions::setIs3D "AudioClipImportOptions::setIs3D()". Note this is on by default.
+
+In general you want to use 2D audio for music or narration, and 3D audio for audio cues, in-game character voices and similar.
+
+~~~~~~~~~~~~~{.cpp}
+importOptions->setIs3D(false);
+~~~~~~~~~~~~~

Documentation/Manuals/Native/User/importingFonts.md

@@ -6,7 +6,7 @@ Fonts control how text characters look and are used primarily throughout the GUI
 Fonts can be imported from .TTF or .OTF formats using the importer.
 
 ~~~~~~~~~~~~~{.cpp}
-// Import a font named "lato.ttf" from the disk
+// Import a font named "lato.ttf" from disk
 HFont font = gImporter().import<Font>("lato.ttf");
 ~~~~~~~~~~~~~
 

Documentation/Manuals/Native/User/renderingObjects.md

@@ -12,7 +12,7 @@ HRenderable renderable = renderableSO->addComponent<CRenderable>();
 ~~~~~~~~~~~~~
 
 # Rendering a mesh
-Once created you must assign it a **Mesh** to render, and a **Material** to render it with, both of which we have discussed in the previous chapters. Use @ref bs::Renderable::setMesh "Renderable::setMesh" and @ref bs::Renderable::setMaterial "Renderable::setMaterial".
+Once created you must assign it a **Mesh** to render, and a **Material** to render it with, both of which we have discussed in the previous chapters. Use @ref bs::CRenderable::setMesh "CRenderable::setMesh" and @ref bs::CRenderable::setMaterial "CRenderable::setMaterial".
 
 ~~~~~~~~~~~~~{.cpp}
 ... set up a camera ...

Documentation/Manuals/Native/manuals.md

@@ -39,6 +39,9 @@ Manuals									{#manuals}
  - [Layouts](@ref guiLayouts)
  - [Styles](@ref guiStyles)
  - [Importing fonts](@ref importingFonts)
+- **Audio**
+ - [Importing audio files](@ref importingAudio)
+ - [Playing audio](@ref playingAudio)
  
 # Developer guides
 

Documentation/Manuals/Native/playingAudio.md

@@ -0,0 +1,146 @@
+Playing audio 						{#playingAudio}
+===============
+
+To play an audio clip create an @ref bs::CAudioSource "AudioSource" component.
+
+~~~~~~~~~~~~~{.cpp}
+HSceneObject audioSourceSO = SceneObject::create("Audio source");
+HAudioSource audioSource = audioSourceSO->addComponent<CAudioSource>();
+~~~~~~~~~~~~~
+
+Each audio source can have a single **AudioClip** associated with it. We can attach the clip to the source by calling @ref bs::CAudioSource "CAudioSource::setClip()".
+
+~~~~~~~~~~~~~{.cpp}
+HAudioClip clip = gImporter().import<AudioClip>("myAudioClip.ogg");
+
+audioSource->setClip(clip);
+~~~~~~~~~~~~~
+
+Once clip has been assigned you can control playback through these methods:
+ - @ref bs::CAudioSource::play "CAudioSource::play()" - Starts playing the assigned audio clip. If playback is currently stopped it starts playback from the clip beginning. If paused the playback is resumed from the point it was paused.
+ - @ref bs::CAudioSource::stop "CAudioSource::stop()" - Stops playing the assigned audio clip.
+ - @ref bs::CAudioSource::pause "CAudioSource::pause()" - Pauses playing the assigned audio clip, allowing you to later resume it with a call to **CAudioSource::play()**.
+ 
+~~~~~~~~~~~~~{.cpp}
+audioSource->play();
+~~~~~~~~~~~~~
+
+You can also control playback by enabling/disabling the scene object the component is attached to. Disabling the scene object will stop any playback.
+
+~~~~~~~~~~~~~{.cpp}
+// Stops playback on any audio source components attached to the scene object
+audioSourceSO->setActive(false);
+~~~~~~~~~~~~~
+
+When enabling a scene object, you can tell the audio source component to automatically start playback of its assigned clip by enabling the option through @ref bs::CAudioSource::setPlayOnStart "CAudioSource::setPlayOnStart()".
+
+~~~~~~~~~~~~~{.cpp}
+// When scene object this component is attached to, is enabled, playback will start automatically. Otherwise the user is required to call play() manually.
+audioSource->setPlayOnStart(true);
+
+// Starts playback
+audioSourceSO->setActive(true);
+~~~~~~~~~~~~~
+
+This is all you need to do in order to play basic audio clips. But lets investigate a few more options that let you control the audio in more detail.
+
+# Volume
+Volume of the audio source can be controlled through @ref bs::CAudioSource::setVolume "CAudioSource::setVolume()". The provided value ranges from 0 to 1.
+
+~~~~~~~~~~~~~{.cpp}
+// Set at half volume
+audioSource->setVolume(0.5f);
+~~~~~~~~~~~~~
+
+# Pitch
+Pitch can be controlled through @ref bs::CAudioSource::setPitch "CAudioSource::setPitch()" by providing a pitch multiplier. Values larger than 1 yield a higher pitch, while values smaller than 1 yield a lower pitch.
+
+~~~~~~~~~~~~~{.cpp}
+// Increase pitch 100%
+audioSource->setPitch(2.0f);
+
+// Decrease pitch by 50% (from default)
+audioSource->setPitch(0.5f);
+~~~~~~~~~~~~~
+
+# Seeking
+You can seek to a specific position within the currently assigned audio clip by calling @ref bs::CAudioSource::setTime "CAudioSource::setTime()". It accepts a time in seconds. If clip is currently playing, the playback will skip to the provided time. If clip is currently paused, the clip will resume from the provided time the next time **CAudioSource::play()** is called.
+
+~~~~~~~~~~~~~{.cpp}
+// Seek to 30 seconds
+audioSource->setTime(30.0f);
+~~~~~~~~~~~~~
+
+# Loop
+By default when the playback reaches the end of the current audio clip, the playback will end. You can ensure the playback loops instead by calling @ref bs::CAudioSource::setIsLooping "CAudioSource::setIsLooping()".
+
+~~~~~~~~~~~~~{.cpp}
+// When playback reaches the end, loop back to start
+audioSource->setIsLooping(true);
+~~~~~~~~~~~~~
+
+# 3D sounds
+If an **AudioClip** has been marked as 3D sound (as described in the previous chapter), then sound playback will be influenced by the position and/or velocity of the scene object the **AudioSource** component is attached to. This means such sounds will sound differently depending on their distance from the listener (among other properties). This ensures the sounds feel realistic as the player walks around the level (i.e. sounding quieter when far away, or using surround to project the sound behind the player).
+
+3D sounds only work if there is a listener defined in the scene. 
+
+## Listener
+Listener provides a reference point used for 3D sound effects. It is represented with a @ref bs::CAudioListener "AudioListener" component. It requires no additional properties aside from being present in the scene.
+
+~~~~~~~~~~~~~{.cpp}
+HSceneObject audioListenerSO = SceneObject::create("Audio listener");
+audioListenerSO->addComponent<CAudioListener>();
+~~~~~~~~~~~~~
+
+Normally you want to attach this component to a scene object representing your player, or the player's camera.
+
+## Attenuation
+Attenuation determines how quickly does audio volume drop off as the listener moves further from the audio source. Change it through @ref bs::CAudioSource::setAttenuation "CAudioSource::setAttenuation()". Higher values means the sound attenuates more quickly with distance.
+
+You can further control attenuation by setting @ref bs::CAudioSource::setMinDistance "CAudioSource::setMinDistance()". If the listener is closer to the source than minimum distance, then the audio will play at full volume. This ensures that the effect of attenuation can be avoided when the listener is close to the source.
+
+~~~~~~~~~~~~~{.cpp}
+// Normal attenuation
+audioSource->setAttenuation(1.0f);
+
+// Attenuation starts at distance of 2 units
+setAttenuation->setMinDistance(2.0f);
+~~~~~~~~~~~~~
+
+# Global controls
+Audio options can also be controlled globally though the @ref bs::Audio "Audio" system, accessible though @ref bs::gAudio "gAudio()". 
+
+You can change the audio volume globally by calling @ref bs::Audio::setVolume "Audio::setVolume()".
+~~~~~~~~~~~~~{.cpp}
+// Mute all sounds
+gAudio().setVolume(0.0f);
+~~~~~~~~~~~~~
+
+You can also pause/unpause all sounds globally by calling @ref bs::Audio::setPaused "Audio::setPaused()".
+~~~~~~~~~~~~~{.cpp}
+// Pause all sounds
+gAudio().setPaused(true);
+~~~~~~~~~~~~~
+
+# Direct clip playback
+Sometimes you do not need all the features offered by **AudioSource** component, and just want to play a sound with no extra options. In that case you can call @ref bs::Audio::play "Audio::play()" and provide it with an **AudioClip** to play. The clip will play at the provided volume & position. It will stop once it ends (no looping), and you won't have any control over its playback once it starts. This is useful for short one-shot effects.
+
+~~~~~~~~~~~~~{.cpp}
+gAudio().play(clip);
+~~~~~~~~~~~~~
+
+# Device enumeration & switching
+If user has multiple audio devices, you can use the **Audio** system to enumerate through them and switch which device you wish to output to.
+
+To retrieve a list of all devices call @ref bs::Audio::getAllDevices "Audio::getAllDevices()". This will return a set of @ref bs::AudioDevice "AudioDevice" objects, which contain unique names for all the output devices.
+
+To switch the active device call @ref bs::Audio::setActiveDevice "Audio::setActiveDevice()".
+
+To retrieve the default audio device (the one user selected in the operating system), call @ref bs::Audio::getDefaultDevice "Audio::getDefaultDevice()".
+
+~~~~~~~~~~~~~{.cpp}
+// Enumerate devices and choose the second one available if present
+Vector<AudioDevice> devices = gAudio().getAllDevices();
+if(devices.size() > 1)
+	gAudio().setActiveDevice(devices[1]);
+~~~~~~~~~~~~~

Source/BansheeCore/Include/BsAudioSource.h

@@ -56,10 +56,10 @@ namespace bs
 		/** Retrieves the volume of the audio source, in [0, 1] range. */
 		float getVolume() const { return mVolume; }
 
-		/** Sets the pitch of the audio source. */
+		/** Sets the pitch multiplier of the audio source. */
 		virtual void setPitch(float pitch);
 
-		/** Gets the pitch of the audio source. */
+		/** Gets the pitch multiplier of the audio source. */
 		float getPitch() const { return mPitch; }
 
 		/** Sets whether the audio clip should loop when it finishes playing. */