seal 0.1.0 → 0.1.1

data/spec/seal/stream_spec.rb

@@ -9,6 +9,13 @@ describe Stream do
 
   it_behaves_like 'an audio object with format'
 
+  specify 'open is equivalent to new' do
+    klass = described_class
+    class << klass; alias unit_test_open new; end
+    klass.method(:open).should eq klass.method(:unit_test_open)
+    class << klass; remove_method :unit_test_open; end
+  end
+
   context 'that are closed' do
     subject do
       Stream.new(WAV_PATH).tap { |stream| stream.close }

data/spec/spec_helper.rb

@@ -20,7 +20,7 @@ class Symbol
   end
 end
 
-Dir["./spec/support/**/*.rb"].each { |f| require f}
+Dir["./spec/support/**/*.rb"].each { |f| require f }
 require 'seal'
 include Seal
 
@@ -32,6 +32,7 @@ OV_PATH = File.join FIXTURE_DIR, 'heal.ogg'
 RSpec.configure do |config|
   config.include CustomMatchers
   config.alias_it_should_behave_like_to :it_validates, 'validates that'
+  config.alias_it_should_behave_like_to :it_defines, 'defines'
 
   config.instance_eval do
     before :all do

data/spec/support/boolean_reader_aliases.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+shared_examples 'boolean reader aliases' do |method_names|
+  method_names.each do |name|
+    specify "#{name}? is an alias of #{name}" do
+      subject.method(name).should eq subject.method("#{name}?")
+    end
+  end
+end

data/src/rubyext.c

@@ -1,9 +1,3 @@
-/*
- * ruby_binding.c 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.
- */
-
 #include <stdlib.h>
 #include <seal.h>
 #include "ruby.h"
@@ -138,15 +132,8 @@ set_obj_int(VALUE robj, VALUE rnum, void* set)
     check_seal_err(((seal_err_t (*)(void*, int)) set)(
         DATA_PTR(robj), NUM2INT(rnum)
     ));
-}
 
-static
-VALUE
-set_obj_ulong(VALUE robj, VALUE rnum, void* set)
-{
-    check_seal_err(((seal_err_t (*)(void*, int)) set)(
-        DATA_PTR(robj), NUM2ULONG(rnum)
-    ));
+    return rnum;
 }
 
 static
@@ -205,17 +192,6 @@ get_obj_int(VALUE robj, void* get)
     return INT2NUM(integer);
 }
 
-static
-VALUE
-get_obj_ulong(VALUE robj, void* get)
-{
-    unsigned long long_integer;
-
-    get_obj_attr(robj, &long_integer, get);
-
-    return ULONG2NUM(long_integer);
-}
-
 static
 VALUE
 get_obj_char(VALUE robj, void* get)
@@ -396,6 +372,9 @@ per_source_effect_limit()
  * specifies the format of the audio file; automatic recognition of the audio
  * format will be attempted if _format_ is not specified. See Seal::Format for
  * possible values. Sets all the attributes appropriately.
+ *
+ * There is a limit on the number of allocated buffers. This method raises an
+ * error if it is exceeding the limit.
  */
 static
 VALUE
@@ -576,6 +555,9 @@ close_stream(VALUE rstream)
  *      Seal::Source.new  -> source
  *
  * Initializes a new source.
+ *
+ * There is a limit on the number of allocated sources. This method raises an
+ * error if it is exceeding the limit.
  */
 static
 VALUE
@@ -745,6 +727,29 @@ get_src_stream(VALUE rsrc)
     return rb_iv_get(rsrc, "@stream");
 }
 
+/*
+ *  call-seq:
+ *      source.feed(effect_slot, index)  -> source
+ *
+ * Feeds an _effect_slot_ with the output of _source_ so the output is filtered
+ * based on the effect attached to _effect_slot_. Later calls to this method
+ * with a different effect slot and the same source and index will override the
+ * old association. _index_ is the zero-based index for the effect. Each
+ * different effect slot that _source_ is feeding must have a unique
+ * corresponding index. The max is <em>Seal.per_src_effect_limit - 1</em>.
+ */
+static
+VALUE
+feed_efs(VALUE rsrc, VALUE rslot, VALUE rindex)
+{
+    seal_src_t* src;
+
+    Data_Get_Struct(rsrc, seal_src_t, src);
+    check_seal_err(seal_feed_efs(src, DATA_PTR(rslot), NUM2INT(rindex)));
+
+    return rsrc;
+}
+
 /*
  *  call-seq:
  *      source.update   -> source
@@ -1081,7 +1086,7 @@ load_rvb(VALUE rrvb, VALUE rpreset)
     seal_rvb_t* rvb;
 
     Data_Get_Struct(rrvb, seal_rvb_t, rvb);
-    check_seal_err(seal_load_rvb(DATA_PTR(rrvb), NUM2INT(rpreset)));
+    check_seal_err(seal_load_rvb(rvb, NUM2INT(rpreset)));
 
     return rrvb;
 }
@@ -1093,6 +1098,9 @@ load_rvb(VALUE rrvb, VALUE rpreset)
  *
  * Initializes a new reverb effect. If a preset is specified, initializes
  * the reverb object to load the preset.
+ *
+ * There is a limit on the number of allocated reverbs. This method raises an
+ * error if it is exceeding the limit.
  */
 static
 VALUE
@@ -1544,7 +1552,11 @@ is_rvb_hfdecay_limited(VALUE rrvb)
  *      effect_slot.effect = effect -> effect
  *
  * Fills _effect_slot_ with _effect_, then _effect_slot_ will become ready to
- * feed sources. Pass nil to unfill the slot.
+ * be fed by sources. Pass nil to unfill the slot.
+ *
+ * Changing the parameters of _effect_ after it is attached to _effect_slot_
+ * will not change the sound effect provided by _effect_slot_. To update the
+ * sound effect, the updated _effect_ must be re-attached to _effect_slot_.
  */
 static
 VALUE
@@ -1570,8 +1582,11 @@ set_efs_effect(VALUE rslot, VALUE reffect)
  *      EffectSlot.new          -> effect_slot
  *      EffectSlot.new(effect)  -> effect_slot
  *
- * Initializes a new effect slot. If an effect object is specified,
- * initializes the effect slot to have that effect object associated.
+ * Initializes a new effect slot. If an effect object is specified, initializes
+ * the effect slot to have that effect object associated.
+ *
+ * There is a limit on the number of allocated effect slots. This method raises
+ * an error if it is exceeding the limit.
  */
 static
 VALUE
@@ -1600,26 +1615,6 @@ get_efs_effect(VALUE rslot)
     return rb_iv_get(rslot, "@effect");
 }
 
-/*
- *  call-seq:
- *      slot.feed(index, source)    -> slot
- *
- * Mixes a sound effect loaded into _effect_slot_ with _source_'s output.
- * Later calls to this function with a different effect slot and the same
- * index will override the old effect slot association.
- */
-static
-VALUE
-feed_efs(VALUE rslot, VALUE rindex, VALUE rsrc)
-{
-    seal_src_t* src;
-
-    Data_Get_Struct(rsrc, seal_src_t, src);
-    check_seal_err(seal_feed_efs(DATA_PTR(rslot), NUM2INT(rindex), src));
-
-    return rslot;
-}
-
 /*
  *  call-seq:
  *      effect_slot.gain = flt  -> flt
@@ -1638,8 +1633,7 @@ set_efs_gain(VALUE refs, VALUE value)
  *  call-seq:
  *      effect_slot.gain    -> flt
  *
- * Gets the output level of _effect_slot_ in the interval. The default is
- * 1.0.
+ * Gets the output level of _effect_slot_. The default is 1.0.
  */
 static
 VALUE
@@ -1878,10 +1872,17 @@ bind_core(void)
 /*
  * Document-class:  Seal::Buffer
  *
- * 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.
+ * 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.
+ *
+ * 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.
  */
 static
 void
@@ -1901,8 +1902,19 @@ bind_buf(void)
 /*
  * Document-class:  Seal::Stream
  *
- * Streams are used by streaming sources to avoid loading big audio into
- * memory. It is the front end for various decoders.
+ * 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.
+ *
+ * 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.
  */
 static
 void
@@ -1923,20 +1935,31 @@ bind_stream(void)
 /*
  * Document-class:  Seal::Source
  *
- * 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.
  */
 
 /*
  * Document-module: Seal::Source::State
  *
  * A collection of Source states.
+ *
+ * A just-initialized source is in the _INITIAL_ state. After a call to
+ * _play_, the source will enter the _PLAYING_ state. After a call to _pause_,
+ * the source will enter the _PAUSED_ state. After a call to _stop_, the source
+ * will enter the _STOPPED_ state.
  */
 
 /*
  * Document-module: Seal::Source::Type
  *
  * A collection of Source types.
+ *
+ * A source not attached to anything is of the _UNDETERMINED_ type. A source
+ * that is attached to a buffer will become the _STATIC_ type. A source that is
+ * attached to a stream will become the _STREAMING_ type.
  */
 static
 void
@@ -1956,6 +1979,7 @@ bind_src(void)
     rb_define_method(cSource, "buffer", get_src_buf, 0);
     rb_define_method(cSource, "stream=", set_src_stream, 1);
     rb_define_method(cSource, "stream", get_src_stream, 0);
+    rb_define_method(cSource, "feed", feed_efs, 2);
     rb_define_method(cSource, "update", update_src, 0);
     rb_define_method(cSource, "position=", set_src_pos, 1);
     rb_define_method(cSource, "position", get_src_pos, 0);
@@ -2001,8 +2025,15 @@ bind_src(void)
 /*
  * Document-class:  Seal::Reverb
  *
- * A Reverb object is a set of parameters that define a reverberation effect.
- * 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, <em>Reverb::Preset::IcePalace::LONGPASSAGE</em> 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
  */
 static
 void
@@ -2263,8 +2294,20 @@ bind_rvb(void)
 /*
  * Document-class:  Seal::EffectSlot
  *
- * EffectSlot is the container type for effects. A source can mix an effect in
- * an effect slot to filter the output sound.
+ * 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.
+ *
+ * For more infomation about effect slots, check out the OpenAL effect
+ * extension guide at: http://zhang.su/seal/EffectsExtensionGuide.pdf
  */
 static
 void
@@ -2276,7 +2319,6 @@ bind_efs(void)
     rb_define_method(cEffectSlot, "initialize", init_efs, -1);
     rb_define_method(cEffectSlot, "effect=", set_efs_effect, 1);
     rb_define_method(cEffectSlot, "effect", get_efs_effect, 0);
-    rb_define_method(cEffectSlot, "feed", feed_efs, 2);
     rb_define_method(cEffectSlot, "gain=", set_efs_gain, 1);
     rb_define_method(cEffectSlot, "gain", get_efs_gain, 0);
     rb_define_method(cEffectSlot, "auto=", set_efs_auto, 1);
@@ -2287,8 +2329,13 @@ bind_efs(void)
 /*
  * Document-class:  Seal::Listener
  *
- * Listener has a singleton instance representing 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.
  */
 static
 void
@@ -2314,7 +2361,8 @@ bind_listener(void)
 /*
  * Document-module: Seal
  *
- * The top-level namespace of Seal.
+ * The top-level namespace of Seal. This module contains interfaces for global
+ * Seal operations.
  */
 void
 Init_seal(void)

data/src/seal/buf.c

@@ -1,9 +1,3 @@
-/*
- * buf.c 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.
- */
-
 #include <stdlib.h>
 #include <al/al.h>
 #include <seal/buf.h>

data/src/seal/core.c

@@ -1,9 +1,3 @@
-/*
- * core.c 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.
- */
-
 #include <stdlib.h>
 #include <stddef.h>
 #include <al/al.h>
@@ -137,7 +131,7 @@ seal_startup(const char* device_name)
     /* Reset OpenAL's error state. */
     alGetError();
 
-    alcGetIntegerv(device, ALC_MAX_AUXILIARY_SENDS, 1,&per_src_effect_limit);
+    alcGetIntegerv(device, ALC_MAX_AUXILIARY_SENDS, 1, &per_src_effect_limit);
 
     return SEAL_OK;
 

data/src/seal/efs.c

@@ -31,15 +31,6 @@ seal_set_efs_effect(seal_efs_t* slot, void* effect)
     return err;
 }
 
-seal_err_t
-seal_feed_efs(seal_efs_t* slot, int index, seal_src_t* src)
-{
-    alSource3i(src->id, AL_AUXILIARY_SEND_FILTER, slot->id, index,
-               AL_FILTER_NULL);
-
-    return _seal_get_openal_err();
-}
-
 seal_err_t
 seal_set_efs_gain(seal_efs_t* slot, float gain)
 {

data/src/seal/err.c

@@ -1,9 +1,3 @@
-/*
- * err.c 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.
- */
-
 #include <al/al.h>
 #include <seal/err.h>
 

data/src/seal/fmt.c

@@ -1,9 +1,3 @@
-/*
- * fmt.c 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.
- */
-
 #include <stdio.h>
 #include <stdint.h>
 #include <seal/fmt.h>

data/src/seal/listener.c

@@ -1,9 +1,3 @@
-/*
- * listener.c 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.
- */
-
 #include <al/al.h>
 #include <seal/listener.h>
 #include <seal/err.h>