urho3d.UrhoSharp/Docs/ns-Urho.Audio.xml

<Namespace Name="Urho.Audio">
  <Docs>
    <summary>The audio subsystem implementation</summary>
    <remarks>
      <para>The Audio subsystem implements an audio output stream. Once it has been initialized, the following operations are supported:</para>
      <list type="bullet">
        <item>
          <term>Playing raw audio, Ogg Vorbis or WAV <see cref="T:Urho.Audio.Sound" /> resources using the <see cref="T:Urho.Audio.SoundSource" /> component. This allows manual stereo panning of mono sounds; stereo sounds will be output with their original stereo mix.</term>
        </item>
        <item>
          <term>Playing the above sound formats in pseudo-3D using the <see cref="T:Urho.Audio.SoundSource3D" /> component. It has stereo positioning and distance attenuation, but does not (at least yet) filter the sound depending on the direction.</term>
        </item>
      </list>
      <para>To hear pseudo-3D positional sounds, a <see cref="T:Urho.Audio.SoundListener" /> component must exist in a scene node and be assigned to the audio subsystem by setting the <see cref="P:Urho.Audio.Audio.Listener" /> property. If the sound listener's scene node exists within a specific scene, it will only hear sounds from that scene, but if it has been created into a "sceneless" node it will hear sounds from all scenes.</para>
      <para>The output is software mixed for an unlimited amount of simultaneous sounds. Ogg Vorbis sounds are decoded on the fly, and decoding them can be memory- and CPU-intensive, so WAV files are recommended when a large number of short sound effects need to be played.</para>
      <para>For purposes of volume control, each <see cref="T:Urho.Audio.SoundSource" /> can be classified into a user defined group which is multiplied with a master category and the individual <see cref="T:Urho.Audio.SoundSource" /> gain set using <see cref="P:Urho.Audio.SoundSource.Gain" /> for the final volume level.</para>
      <para>To control the category volumes, set the <see cref="M:Urho.Audio.Audio.SetMasterGain" />, which defines the category if it didn't already exist.</para>
      <para>The <see cref="T:Urho.Audio.SoundSource" /> components support automatic removal from the node they belong to, once playback is finished. To use, set the <see cref="P:Urho.Audio.SoundSource.AutoRemove property" /> on them. This may be useful when a game object plays several "fire and forget" sound effects.</para>
      <para></para>
      <format type="text/html">
        <h2>Sound Parameters</h2>
      </format>
      <para></para>
      <para>A standard WAV file can not tell whether it should loop, and raw audio does not contain any header information. Parameters for the<see cref="Sound" /> resource can optionally be specified through an XML file that has the same name as the sound, but .xml extension. Possible elements are “format” which allows optional attributes “frequency” (and a value in Hz), “sixteenbits” (with either “true” and “false” values) and “stereo” (with either “true” and “false” values).  The other element is “loop” and it allows the optional attributes “enable” (with either “true” and “false” values) and “start” and “end” </para>
      <para>The frequency is in Hz, and loop start and end are bytes from the start of audio data. If a loop is enabled without specifying the start and end, it is assumed to be the whole sound. Ogg Vorbis compressed sounds do not support specifying the loop range, only whether whole sound looping is enabled or disabled.</para>
      <para>The <see cref="Audio" /> subsystem is always instantiated, but in headless mode it is not active. In headless mode the playback of sounds is simulated, taking the sound length and frequency into account. This allows basing logic on whether a specific sound is still playing or not, even in server code.</para>
      <format type="text/html">
        <h2>Sound Streaming</h2>
      </format>
      <para>In addition to playing existing sound resources, sound can be generated during runtime using the <see cref="T:Urho.Audio.SoundSource" />  class and its subclasses. To start playback of a stream on a <see cref="T:Urho.Audio.SoundSource" />, call <see cref="M:Urho.Audio.SoundSource.Play(Urho.SoundStream)" />.</para>
      <para>Sound streaming is used internally to implement on-the-fly Ogg Vorbis decoding. See the SoundSynthesis sample for an example of using the <see cref="T:Urho.Audio.BufferedSoundStream" /> subclass, which allows the sound data to be queued for playback from the main thread.</para>
    </remarks>
  </Docs>
</Namespace>