seal 0.1.0 → 0.1.1

data/README.md

@@ -71,7 +71,7 @@ Apply a reverberation effect to the sound source:
 # Allocate an effect slot and associate a specific reverb object.
 slot = EffectSlot.new(Reverb.new(Reverb::Preset::FOREST))
 # Start feeding the slot.
-slot.feed(0, source)
+source.feed(slot, 0)
 ```
 
 Uninitialize Seal:

data/include/seal/buf.h

@@ -1,13 +1,15 @@
 /*
- * buf.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
+ * Interfaces for manipulating buffers. Buffers are essentially abstract
+ * representations of (raw) audio data and are used by sources. Buffers are
+ * most suitable for small-sized sound effect which can be efficiently loaded
+ * to memory at once. Streams, on the other hand, are more suitable for massive
+ * audio such as background music.
  *
- * buf.h wraps up the abstract data type `seal_buf_t'. Buffers are essentially
- * abstract representations of the (raw) audio data and are used by sources.
- * Buffers are most suitable for small-sized sound effect which can be
- * efficiently loaded to memory at once. Streams, on the other hand, are more
- * suitable for long audio such as background music.
+ * In order to have 3D sound effect on the buffer, the audio file needs to have
+ * mono-channel. If the audio file has multi-channel, the sound will not be
+ * positioned in a 3D space. Multi-channel audio (a.k.a. stereo) is already
+ * designed to have illusion of directionality and audible perspective. Most
+ * sound effect should be monophonic.
  */
 
 #ifndef _SEAL_BUF_H_
@@ -28,6 +30,9 @@ extern "C" {
  * Initializes a new buffer. If the buffer is no longer needed, call
  * `seal_destroy_buf' to release the resources used by the buffer.
  *
+ * There is a limit on the number of allocated buffer. This function returns an
+ * error if it is exceeding the limit.
+ *
  * @param buf   the buffer to initialize
  */
 seal_err_t seal_init_buf(seal_buf_t*);

data/include/seal/core.h

@@ -1,9 +1,5 @@
 /*
- * core.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * core.h defines interfaces for low-level Seal operations.
+ * Interfaces for global Seal operations.
  */
 
 #ifndef _SEAL_CORE_H_

data/include/seal/efs.h

@@ -1,25 +1,33 @@
 /*
- * efs.h is part of the Scorched End Audio Library (SEAL) and is
- * licensed under the terms of the GNU Lesser General Public License. See
- * COPYING attached with the library.
+ * Interfaces for manipulating effect slots, which are containers for effect
+ * objects. Effect slots can attach effect objects (such as reverb objects) and
+ * then be fed with a mix of audio from different sources, essentially
+ * filtering the rendering of the sound sources and output to the mixer based
+ * on the attached effect object. For example, if a reverb object is attached
+ * to an effect slot and one source is feeding the slot, the sound of that
+ * source will have the reverberation effect defined by the reverb object.
+
+ * Multiple sources can feed the same effect slot, but conversely there is a
+ * limit on the number of effect slots a source can feed concurrently. See the
+ * documentation for EffectSlot#feed for more details.
  *
- * efs.h defines the effect slot type, which is the container type for
- * effects. A source can mix an effect in an effect slot to filter the output
- * sound.
+ * For more infomation about effect slots, check out the OpenAL effect
+ * extension guide at: http://zhang.su/seal/EffectsExtensionGuide.pdf
  */
 
 #ifndef _SEAL_EFS_H_
 #define _SEAL_EFS_H_
 
-#include "src.h"
 #include "err.h"
 
 typedef struct seal_efs_t seal_efs_t;
 
 /*
  * Initializes a new effect slot. If the effect slot is no longer needed, call
- * `seal_destroy_efs' to release the resources used by the effect
- * slot.
+ * `seal_destroy_efs' to release the resources used by the effect slot.
+ *
+ * There is a limit on the number of allocated effect slots. This function
+ * returns an error if it is exceeding the limit.
  *
  * @param efs   the effect slot to initialize
  */
@@ -34,25 +42,17 @@ seal_err_t seal_destroy_efs(seal_efs_t*);
 
 /*
  * Fills an effect slot with an effect object, then the effect Slot will
- * become ready to be mixed with sources. Pass 0 to unfill the slot.
+ * become ready to be fed by sources. Pass 0 to unfill the slot.
+ *
+ * Changing the parameters of the effect object after it is attached to the
+ * slot will not change the sound effect provided by the slot. To update the
+ * sound effect, the effect object must be re-attached to the slot.
  *
  * @param efs       the effect slot to fill
  * @param effect    the effect to fill the effect slot with
  */
 seal_err_t seal_set_efs_effect(seal_efs_t*, void* /*effect*/);
 
-/*
- * Mixes a sound effect loaded into an effect slot with a source's output.
- * Later calls to this function with a different effect slot and the same
- * index will override the old effect slot association.
- *
- * @see             seal_get_neffects_per_src
- * @param efs       the slot that contains the effect to mix
- * @param index     the zero-based index of the effect
- * @param src       the source that feeds the effect slot
- */
-seal_err_t seal_feed_efs(seal_efs_t*, int /*index*/, seal_src_t*);
-
 /*
  * Sets the output level of an effect Slot in the interval [0.0f, 1.0f]. A
  * value of 0.0 mutes the output.

data/include/seal/err.h

@@ -1,12 +1,7 @@
 /*
- * err.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * err.h defines Seal errors and provides subroutines for clearing and
- * retriving errors. Seal functions will set a thread-local error flag when
- * error strikes, so if the last Seal function call returns 0, the exact error
- * and detailed error message can be retrieved using functions in this module.
+ * Seal errors and interfaces for retriving error messages. Most Seal functions
+ * return an error code which can be used to retrieve the corresponding error
+ * message.
  */
 
 #ifndef _SEAL_ERR_H_

data/include/seal/fmt.h

@@ -1,10 +1,5 @@
 /*
- * fmt.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * fmt.h defines all the supported audio file format and provides utilities
- * to deal with them.
+ * Supported audio file formats and utilities to deal with them.
  */
 
 #ifndef _SEAL_FMT_H_

data/include/seal/listener.h

@@ -1,10 +1,11 @@
 /*
- * listener.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * listener.h wraps up the listener singleton object, which is the abstract
- * representation of the sole listener who hears the sound.
+ * Interfaces for manipulating the listener singleton object. The listener
+ * object abstractly represents the main object in a sound application which
+ * "hears" all the sound. For example, the listener object can be used to
+ * represent the main character moving around on the map in a role-playing
+ * game. The properties of the listener (position, velocity, etc.) combined
+ * with those of the existing sources determine how the sound should be
+ * rendered.
  */
 
 #ifndef _SEAL_LISTENER_H_

data/include/seal/raw.h

@@ -1,10 +1,6 @@
 /*
- * raw.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * raw.h defines the the data structure `seal_raw_t' that represents raw PCM
- * data as well as a series of operations on them.
+ * Interfaces for manipulating the data structure `seal_raw_t' which contains
+ * raw PCM data.
  */
 
 #ifndef _SEAL_RAW_H_

data/include/seal/rvb.h

@@ -1,10 +1,13 @@
 /*
- * rvb.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * rvb.h defines the reverberation effect type and its parameters. Effect
- * objects can be put into an effect slot for sources to use.
+ * Interfaces for manipulating reverberation effect objects which can be loaded
+ * into effect slots. The reverberation parameters can be customized to
+ * emulate reverberations in different environment or can be loaded from
+ * presets. The preset constants suggest the reverberation environment, for
+ * example, `SEAL_ICEPALACE_LONGPASSAGE_REVERB` emulates the reverberation in
+ * a long passage of an ice palace.
+ *
+ * For more infomation about reverberations, check out the OpenAL effect
+ * extension guide at: http://zhang.su/seal/EffectsExtensionGuide.pdf
  */
 
 #ifndef _SEAL_RVB_H_
@@ -169,6 +172,9 @@ extern "C" {
  * Initializes a new reverb effect. If the reverb is no longer needed, call
  * `seal_destroy_rvb' to release the resources used by the reverb.
  *
+ * There is a limit on the number of allocated reverbs. This function returns
+ * an error if it is exceeding the limit.
+ *
  * @param reverb    the reverb object to initialize
  */
 seal_err_t seal_init_rvb(seal_rvb_t*);

data/include/seal/src.h

@@ -1,10 +1,8 @@
 /*
- * src.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
- * src.h wraps up the abstract data type `seal_src_t'. Sources are abstract
- * representations of sound sources which emit sound in Euclidean space.
+ * Interfaces for manipulating sources. Sources are abstract representations of
+ * sound sources which emit sound in a Euclidean space. The sound comes from
+ * its attached buffer or stream. Its properties combined with those of the
+ * listener singleton object determine how the sound should be rendered.
  */
 
 #ifndef _SEAL_SRC_H_
@@ -13,13 +11,13 @@
 #include <stddef.h>
 #include "buf.h"
 #include "stream.h"
+#include "efs.h"
 #include "err.h"
 
 /*
- * A just-initialized source is of the `SEAL_UNDETERMINED' type. A source that
- * attaches a buffer through `seal_set_src_buf' will become the `SEAL_STATIC'
- * type. A source that streams audio from file through `seal_set_src_stream'
- * will become the `SEAL_STREAMING' type.
+ * A source not attached to anything is of the `SEAL_UNDETERMINED` type. A
+ * source that is attached to a buffer will become the `SEAL_STATIC` type.
+ * A source that is attached to a stream will become the `SEAL_STREAMING` type.
  */
 enum seal_src_type_t
 {
@@ -55,6 +53,9 @@ extern "C" {
  * Initializes a new source. If the source is no longer needed, call
  * `seal_destroy_source' to release any resource used by the source.
  *
+ * There is a limit on the number of allocated sources. This function returns
+ * an error if it is exceeding the limit.
+ *
  * @param src   the source to initialize
  */
 seal_err_t seal_init_src(seal_src_t*);
@@ -140,6 +141,22 @@ seal_err_t seal_set_src_buf(seal_src_t*, seal_buf_t*);
  */
 seal_err_t seal_set_src_stream(seal_src_t*, seal_stream_t*);
 
+/*
+ * Feeds an effect slot with the output of a source so the output is filtered
+ * based on the effect attached to the slot. Later calls to this function with
+ * a different effect slot and the same source and index will override the old
+ * association.
+ *
+ * @see             seal_get_per_src_effect_limit
+ * @param src       the source that feeds the effect slot
+ * @param efs       the effect slot to feed
+ * @param index     the zero-based index for the effect; each different effect
+ *                  slot that the source is feeding must have a unique
+ *                  corresponding index; the max is the return value of
+ *                  seal_get_per_src_effect_limit - 1.
+ */
+seal_err_t seal_feed_efs(seal_src_t*, seal_efs_t*, int /*index*/);
+
 /*
  * Updates a streaming source. If the source is not up-to-date, the playback
  * will end before the end of the stream is reached. Does nothing if the

data/include/seal/stream.h

@@ -1,10 +1,17 @@
 /*
- * stream.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
+ * Interfaces for manipulating streams used by streaming sources. Streams are
+ * usually necessary when the audio data is too massive to fit into main
+ * memory as a whole (such as a background music, which can eat up to dozens of
+ * megabytes of memory after decoding), in which case buffers are not suitable.
  *
- * stream.h wraps up the `seal_stream_t' data type used by streaming sources.
- * It is the front end for various decoders.
+ * Streams often contain multi-channel audio (since most of the time they are
+ * used to play background music, and background music files are often
+ * multi-channel already), which means that they often contain sound that are
+ * not positioned, i.e., not processed by the 3D sound rendering pipeline. That
+ * fact is totally fine for background music since they are usually not
+ * associated to any object in the application. If positioned streams are
+ * needed and the audio file has multi-channel, the audio file need to be
+ * converted to mono-channel.
  */
 
 #ifndef _SEAL_STREAM_H_

data/mpg123/ports/MSVC++/2010/libmpg123/libmpg123.vcxproj

@@ -340,6 +340,8 @@ yasm -a x86 -p gas -r raw -f win32 -g null -m x86 -o "$(ProjectDir)..\libmpg123\
       <AdditionalDependencies>dct36_3dnow.o;dct36_3dnowext.o;dct64_3dnow.o;dct64_3dnowext.o;dct64_mmx.o;dct64_sse.o;dct64_sse_float.o;equalizer_3dnow.o;getcpuflags.o;synth_3dnow.o;synth_3dnowext.o;synth_i586.o;synth_mmx.o;synth_sse.o;synth_sse_float.o;synth_stereo_sse_float.o;tabinit_mmx.o;synth_sse_accurate.o;synth_sse_s32.o;synth_stereo_sse_accurate.o;synth_stereo_sse_s32.o;%(AdditionalDependencies)</AdditionalDependencies>
       <OutputFile>$(ProjectDir)Debug\$(ProjectName).lib</OutputFile>
       <AdditionalLibraryDirectories>$(ProjectDir)\Debug;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+      <IgnoreAllDefaultLibraries>
+      </IgnoreAllDefaultLibraries>
     </Lib>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release_x86|Win32'">
@@ -434,6 +436,9 @@ yasm -a x86 -p gas -r raw -f win32 -g null -m x86 -o "$(ProjectDir)..\libmpg123\
       <OutputFile>$(ProjectDir)Release\$(ProjectName).lib</OutputFile>
       <AdditionalLibraryDirectories>$(ProjectDir)\Release;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
     </Lib>
+    <PreBuildEvent>
+      <Command>del "$(ProjectDir)..\..\..\..\src\libmpg123\mpg123.h"</Command>
+    </PreBuildEvent>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug_x86_Dll|Win32'">
     <ClCompile>

data/spec/seal/core_spec.rb

@@ -16,7 +16,7 @@ describe Seal do
     Seal.listener.should be Seal.listener
     Seal.listener.should be_a Listener
     expect { Seal::Listener.new }.to raise_error NoMethodError
-    expect { Seal::Listener.allocate }.to raise_error TypeError
+    expect { Seal::Listener.allocate }.to raise_error
   end
 
   it 'defines a limit on the number of effect slots per source' do

data/spec/seal/effect_slot_spec.rb

@@ -11,6 +11,7 @@ describe EffectSlot do
 
   it_validates 'the boolean attribute', :auto
   it_validates 'the float attribute', :gain, "[0, 1]"
+  it_defines 'boolean reader aliases', [:auto]
 
   it 'can initialize with an effect' do
     reverb = Reverb.new
@@ -25,14 +26,10 @@ describe EffectSlot do
     effect_slot.effect.should be reverb
   end
 
-  it 'has a limited number of sources it can feed concurrently' do
-    effect_slot = subject
-    sources = []
-    Seal.per_source_effect_limit.times do |i|
-      sources << Source.new
-      effect_slot.feed(i, sources[-1])
+  it 'can be fed by multiple sources' do
+    23.times do
+      source = Source.new
+      source.feed(subject, 0)
     end
-    expect { effect_slot.feed(sources.size, Source.new) }.to raise_error \
-      /Invalid parameter value/
   end
 end

data/spec/seal/reverb_spec.rb

@@ -30,15 +30,16 @@ describe Reverb do
   it_validates 'the float attribute', :reflections_delay, '[0, 0.3]'
   it_validates 'the float attribute', :reflections_gain, '[0, 3.16]'
   it_validates 'the float attribute', :room_rolloff_factor, '[0, 10]'
+  it_defines 'boolean reader aliases', [:hfdecay_limited]
 
-  it 'can load different reverb presets' do
-    test_load_presets = -> a_module do
-      a_module.constants.each do |const_sym|
-        constant = a_module.const_get const_sym
-        case constant
-        when Module
-          test_load_presets.call(constant)
-        else
+  specify_preset_loading = -> mod do
+    mod.constants.each do |const_sym|
+      constant = mod.const_get(const_sym)
+      case constant
+      when Module
+        specify_preset_loading.(constant)
+      else
+        it "can load preset #{mod}::#{const_sym}" do
           expect do
             reverb = Reverb.new(constant)
             reverb.load(constant)
@@ -46,6 +47,6 @@ describe Reverb do
         end
       end
     end
-    test_load_presets.call(Reverb::Preset)
   end
+  specify_preset_loading.(Reverb::Preset)
 end

data/spec/seal/source_spec.rb

@@ -11,7 +11,7 @@ describe Source do
   it_behaves_like 'a movable object'
 
   describe 'by default' do
-    its(:auto?) { should be_true }
+    its(:auto) { should be_true }
     its(:buffer) { should be_nil }
     its(:chunk_size) { should eq 36864 }
     its(:gain) { should be_within(TOLERANCE).of(1.0) }
@@ -21,13 +21,14 @@ describe Source do
     its(:relative) { should be_false }
     its(:state) { should be INITIAL }
     its(:stream) { should be_nil }
-    its (:type) { should be UNDETERMINED }
+    its(:type) { should be UNDETERMINED }
   end
 
   it_validates 'the boolean attribute', :relative
   it_validates 'the boolean attribute', :auto
   it_validates 'the float attribute', :pitch, "[0, +inf.)"
   it_validates 'the float attribute', :gain, "[0, +inf.)"
+  it_defines 'boolean reader aliases', [:auto, :relative, :looping]
 
   it 'validates its queue size is in [2, 63]' do
     error_pattern = /Invalid parameter value/
@@ -180,6 +181,18 @@ describe Source do
     end
   end
 
+  describe 'feeding effect slots' do
+    it 'can only feed a limited number concurrently' do
+      effect_slot = nil
+      Seal.per_source_effect_limit.times do |i|
+        effect_slot = EffectSlot.new
+        source.feed(effect_slot, i)
+      end
+      expect { source.feed(effect_slot, Seal.per_source_effect_limit) }.to \
+        raise_error /Invalid parameter value/
+    end
+  end
+
   describe 'automatic streaming' do
     let(:source) do
       Source.new.tap do |source|
@@ -209,31 +222,31 @@ describe Source do
 
   describe 'looping' do
     example 'as undetermined type' do
-      source.looping?.should be_false
+      source.looping.should be_false
       source.looping = true
       source.looping.should be_true
       source.looping = false
-      source.looping?.should be_false
+      source.looping.should be_false
     end
 
     example 'as streaming type' do
       source.looping = true
       source.stream = stream
-      source.looping?.should be_true
+      source.looping.should be_true
       source.looping = false
-      source.looping?.should be_false
+      source.looping.should be_false
       source.looping = true
-      source.looping?.should be_true
+      source.looping.should be_true
     end
 
     example 'as static type' do
       source.looping = true
       source.buffer = buffer
-      source.looping?.should be_true
+      source.looping.should be_true
       source.looping = false
-      source.looping?.should be_false
+      source.looping.should be_false
       source.looping = true
-      source.looping?.should be_true
+      source.looping.should be_true
     end
 
     # This example depends on the length of the test audio file.