fmod 0.9.1 → 0.9.2

data/lib/fmod/dsp_connection.rb

@@ -1,5 +1,8 @@
 
 module FMOD
+
+  ##
+  # Represents a connection between two DSP units
   class DspConnection < Handle
 
     ##

data/lib/fmod/effects.rb

@@ -1,38 +1,52 @@
 
-require_relative 'effects/channel_mix.rb'
-require_relative 'effects/chorus.rb'
-require_relative 'effects/compressor.rb'
-require_relative 'effects/convolution_reverb.rb'
-require_relative 'effects/delay.rb'
-require_relative 'effects/distortion.rb'
-require_relative 'effects/dsps.rb'
-require_relative 'effects/echo.rb'
-require_relative 'effects/envelope_follower.rb'
-require_relative 'effects/fader.rb'
-require_relative 'effects/fft.rb'
-require_relative 'effects/flange.rb'
-require_relative 'effects/high_pass.rb'
-require_relative 'effects/high_pass_simple.rb'
-require_relative 'effects/it_echo.rb'
-require_relative 'effects/it_lowpass.rb'
-require_relative 'effects/ladspa_plugin.rb'
-require_relative 'effects/limiter.rb'
-require_relative 'effects/loudness_meter.rb'
-require_relative 'effects/low_pass.rb'
-require_relative 'effects/low_pass_simple.rb'
-require_relative 'effects/mixer.rb'
-require_relative 'effects/multiband_eq.rb'
-require_relative 'effects/normalize.rb'
-require_relative 'effects/object_pan.rb'
-require_relative 'effects/oscillator.rb'
-require_relative 'effects/pan.rb'
-require_relative 'effects/param_eq.rb'
-require_relative 'effects/pitch_shift.rb'
-require_relative 'effects/return.rb'
-require_relative 'effects/send.rb'
-require_relative 'effects/sfx_reverb.rb'
-require_relative 'effects/three_eq.rb'
-require_relative 'effects/transceiver.rb'
-require_relative 'effects/tremolo.rb'
-require_relative 'effects/vst_plugin.rb'
-require_relative 'effects/winamp_plugin.rb'
+module FMOD
+
+  ##
+  # Namespace containing all of the built-in DSP effects.
+  module Effects
+
+    require_relative 'effects/channel_mix.rb'
+    require_relative 'effects/chorus.rb'
+    require_relative 'effects/compressor.rb'
+    require_relative 'effects/convolution_reverb.rb'
+    require_relative 'effects/delay.rb'
+    require_relative 'effects/distortion.rb'
+    require_relative 'effects/dsps.rb'
+    require_relative 'effects/echo.rb'
+    require_relative 'effects/envelope_follower.rb'
+    require_relative 'effects/fader.rb'
+    require_relative 'effects/fft.rb'
+    require_relative 'effects/flange.rb'
+    require_relative 'effects/high_pass.rb'
+    require_relative 'effects/high_pass_simple.rb'
+    require_relative 'effects/it_echo.rb'
+    require_relative 'effects/it_lowpass.rb'
+    require_relative 'effects/ladspa_plugin.rb'
+    require_relative 'effects/limiter.rb'
+    require_relative 'effects/loudness_meter.rb'
+    require_relative 'effects/low_pass.rb'
+    require_relative 'effects/low_pass_simple.rb'
+    require_relative 'effects/mixer.rb'
+    require_relative 'effects/multiband_eq.rb'
+    require_relative 'effects/normalize.rb'
+    require_relative 'effects/object_pan.rb'
+    require_relative 'effects/oscillator.rb'
+    require_relative 'effects/pan.rb'
+    require_relative 'effects/param_eq.rb'
+    require_relative 'effects/pitch_shift.rb'
+    require_relative 'effects/return.rb'
+    require_relative 'effects/send.rb'
+    require_relative 'effects/sfx_reverb.rb'
+    require_relative 'effects/three_eq.rb'
+    require_relative 'effects/transceiver.rb'
+    require_relative 'effects/tremolo.rb'
+    require_relative 'effects/vst_plugin.rb'
+    require_relative 'effects/winamp_plugin.rb'
+
+    deprecate_constant :HighPass
+    deprecate_constant :HighPassSimple
+    deprecate_constant :LowPass
+    deprecate_constant :LowPassSimple
+    deprecate_constant :LadspaPlugin
+  end
+end

data/lib/fmod/error.rb

@@ -1,4 +1,7 @@
 module FMOD
+
+  ##
+  # Exception class for FMOD errors.
   class Error < StandardError
 
     include FMOD::Core

data/lib/fmod/geometry.rb

@@ -1,5 +1,12 @@
 
 module FMOD
+
+  ##
+  # FMOD supports the supply of polygon mesh data, that can be processed in
+  # realtime to create the effect of occlusion in a real 3D world. In real world
+  # terms, the user can stop sounds travelling through walls, or even confine
+  # reverb inside a geometric volume so that it doesn't leak out into other
+  # areas.
   class Geometry < Handle
 
     include Enumerable

data/lib/fmod/handle.rb

@@ -2,16 +2,28 @@ require 'fiddle'
 require 'fiddle/import'
 
 module FMOD
+
+  ##
+  # @abstract The superclass for all core FMOD classes.
+  # Contains a reference handle to an unmanaged object, and as such it is
+  # crucial to call {#release} on any derived class to prevent memory leaks.
   class Handle < Fiddle::Pointer
 
     include Fiddle
     include FMOD::Core
 
+    ##
+    # @param address [Pointer, Integer, String] The address of a native FMOD
+    #   pointer.
     def initialize(address)
       address = address.unpack1('J') if address.is_a?(String)
       super(address.to_i)
     end
 
+    ##
+    # Releases the native handle.
+    # Failure to call this function may result in memory leaks.
+    # @return [void]
     def release
       case self
       when Sound then FMOD.invoke(:Sound_Release, self)
@@ -26,6 +38,9 @@ module FMOD
 
     alias_method :dispose, :release
 
+    # @!attribute user_data
+    # @return [Pointer] a user value stored within the object.
+
     def user_data
       pointer = int_ptr
       case self
@@ -71,16 +86,30 @@ module FMOD
       pointer
     end
 
+    ##
+    # @return [String] the string representation of the object.
     def to_s
       inspect # TODO
     end
 
+    ##
+    # @return [String] an empty string buffer the size of the platforms pointer
+    #   size.
     def int_ptr
       "\0" * SIZEOF_INTPTR_T
     end
 
     private
 
+    ##
+    # Dynamically links a Ruby method to get a boolean value from a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix may be omitted.
+    #
+    # @return [void]
     def self.bool_reader(name, function)
       self.send(:define_method, name) do
         FMOD.invoke(function, self, buffer = "\0" * SIZEOF_INT)
@@ -88,12 +117,30 @@ module FMOD
       end
     end
 
+    ##
+    # Dynamically links a Ruby method to set a boolean value in a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix can be omitted.
+    #
+    # @return [void]
     def self.bool_writer(name, function)
       self.send(:define_method, name) do |bool|
         FMOD.invoke(function, self, bool.to_i)
       end
     end
 
+    ##
+    # Dynamically links a Ruby method to get an integer value from a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix may be omitted.
+    #
+    # @return [void]
     def self.integer_reader(name, function)
       self.send(:define_method, name) do
         FMOD.invoke(function, self, buffer = "\0" * SIZEOF_INT)
@@ -101,6 +148,19 @@ module FMOD
       end
     end
 
+    ##
+    # Dynamically links a Ruby method to set an integer value in a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix can be omitted.
+    # @param min [Numeric] The minimum permitted value that can be passed to
+    #   the defined method. Values out of range will be clamped.
+    # @param max [Numeric] The maximum permitted value that can be passed to
+    #   the defined method. Values out of range will be clamped.
+    #
+    # @return [void]
     def self.integer_writer(name, function, min = nil, max = nil)
       self.send(:define_method, name) do |int|
         int = min if min && int < min
@@ -110,6 +170,15 @@ module FMOD
       end
     end
 
+    ##
+    # Dynamically links a Ruby method to get a float value from a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix may be omitted.
+    #
+    # @return [void]
     def self.float_reader(name, function)
       self.send(:define_method, name) do
         FMOD.invoke(function, self, buffer = "\0" * SIZEOF_FLOAT)
@@ -117,6 +186,19 @@ module FMOD
       end
     end
 
+    ##
+    # Dynamically links a Ruby method to set a float value in a native
+    # FMOD function.
+    #
+    # @param name [Symbol] The Ruby method name to be defined.
+    # @param function [Symbol] The native FMOD function to import.
+    #   The "FMOD_" prefix can be omitted.
+    # @param min [Numeric] The minimum permitted value that can be passed to
+    #   the defined method. Values out of range will be clamped.
+    # @param max [Numeric] The maximum permitted value that can be passed to
+    #   the defined method. Values out of range will be clamped.
+    #
+    # @return [void]
     def self.float_writer(name, function, min = nil, max = nil)
       self.send(:define_method, name) do |float|
         float = min if min && float < min

data/lib/fmod/reverb3D.rb

@@ -15,32 +15,6 @@ module FMOD
   # setting is set to the default ambient reverb setting.
   class Reverb3D < Handle
 
-    ##
-    # @!attribute properties
-    # Gets or sets the reverb parameters for the current reverb object.
-    # @return [Reverb]
-
-    ##
-    # @!attribute position
-    # A {Vector} containing the 3D position of the center of the reverb in 3D
-    # space.
-    # * *Default:* {Vector.zero}
-    # @return [Vector]
-
-    ##
-    # @!attribute min_distance
-    # The distance from the center-point that the reverb will have full effect
-    # at.
-    # * *Default:* 0.0
-    # @return [Float]
-
-    ##
-    # @!attribute max_distance
-    # The distance from the center-point that the reverb will not have any
-    # effect.
-    # * *Default:* 0.0
-    # @return [Float]
-
     ##
     # @!attribute active
     # Gets or sets the a state to disable or enable a reverb object so that it
@@ -50,6 +24,13 @@ module FMOD
     bool_reader(:active, :Reverb3D_GetActive)
     bool_writer(:active=, :Reverb3D_SetActive)
 
+    ##
+    # @!attribute min_distance
+    # The distance from the center-point that the reverb will have full effect
+    # at.
+    # * *Default:* 0.0
+    # @return [Float]
+
     def min_distance
       buffer = "\0" * SIZEOF_FLOAT
       FMOD.invoke(:Reverb3D_Get3DAttributes, self, nil, buffer, nil)
@@ -61,6 +42,13 @@ module FMOD
         distance, max_distance )
     end
 
+    ##
+    # @!attribute max_distance
+    # The distance from the center-point that the reverb will not have any
+    # effect.
+    # * *Default:* 0.0
+    # @return [Float]
+
     def max_distance
       buffer = "\0" * SIZEOF_FLOAT
       FMOD.invoke(:Reverb3D_Get3DAttributes, self, nil, nil, buffer)
@@ -72,6 +60,13 @@ module FMOD
         min_distance, distance )
     end
 
+    ##
+    # @!attribute position
+    # A {Vector} containing the 3D position of the center of the reverb in 3D
+    # space.
+    # * *Default:* {Vector.zero}
+    # @return [Vector]
+
     def position
       vector = Vector.zero
       FMOD.invoke(:Reverb3D_Get3DAttributes, self, vector, nil, nil)
@@ -84,6 +79,10 @@ module FMOD
         min_distance, max_distance )
     end
 
+    ##
+    # @!attribute properties
+    # @return [Reverb] the reverb parameters for the current reverb object.
+
     def properties
       FMOD.invoke(:Reverb3D_GetProperties, self, reverb = Reverb.new)
       reverb

data/lib/fmod/sound.rb

@@ -1,5 +1,8 @@
 
 module FMOD
+
+  ##
+  # Represents the actual data source of audio, usually an audio file or stream.
   class Sound < Handle
 
     ##
@@ -764,7 +767,8 @@ module FMOD
       parent.play_sound(self, group, false)
     end
 
-    
+    ##
+    # Emulates an Array-type container of a {Tag}'s objects within a {Sound}.
     class TagCollection
 
       include Enumerable
@@ -781,6 +785,9 @@ module FMOD
         self
       end
 
+      ##
+      # @!attribute [r] count
+      # @return [Integer] the number of tags in the collection.
       def count
         buffer = "\0" * Fiddle::SIZEOF_INT
         FMOD.invoke(:Sound_GetNumTags, @sound, buffer, nil)
@@ -789,12 +796,23 @@ module FMOD
 
       alias_method :size, :count
 
+      ##
+      # @!attribute [r] count
+      # @return [Integer] the number of updated tags in the collection since
+      #   last time this value was checked.
       def updated_count
         buffer = "\0" * Fiddle::SIZEOF_INT
         FMOD.invoke(:Sound_GetNumTags, @sound, nil, buffer)
         buffer.unpack1('l')
       end
 
+      ##
+      # Retrieves a descriptive tag stored by the sound, to describe things like
+      # the song name, author etc.
+      #
+      # @param index [Integer] Index into the collection to retrieve the tag.
+      #
+      # @return [Tag, nil] the desired {Tag} or +nil+ if index is out of range.
       def [](index)
         tag = FMOD::Core::Tag.new
         if index.is_a?(Integer)
@@ -805,6 +823,8 @@ module FMOD
         end
         tag
       end
+
+      alias_method :tag, :[]
     end
   end
 end

data/lib/fmod/sound_group.rb

@@ -1,52 +1,128 @@
 
 module FMOD
+
+  ##
+  # Represents a logical grouping of {Sound} objects that can be manipulated as
+  # one.
   class SoundGroup < Handle
 
     include Fiddle
     include Enumerable
 
+    ##
+    # @!attribute max_audible
+    # Limits the number of concurrent playbacks of sounds in a sound group to
+    # the specified value.
+    #
+    # After this, if the sounds in the sound group are playing this many times,
+    # any attempts to play more of the sounds in the sound group will by default
+    # fail an exception.
+    #
+    # Use {#behavior} to change the way the sound playback behaves when too many
+    # sounds are playing. Muting, failing and stealing behaviors can be
+    # specified.
+    #
+    # @return [Integer] the number of playbacks to be audible at once. -1 (the
+    #   default) denotes unlimited.
     integer_reader(:max_audible, :SoundGroup_GetMaxAudible)
-    integer_writer(:max_audible=, :SoundGroup_SetMaxAudible)
+    integer_writer(:max_audible=, :SoundGroup_SetMaxAudible, min: -1)
 
+    ##
+    # @!attribute behavior
+    # Determines the way the sound playback behaves when too many sounds are
+    # playing in a sound group. Muting, failing and stealing behaviors can be
+    # specified.
+    #
+    # @return [Integer] the current behavior.
+    # @see SoundGroupBehavior
     integer_reader(:behavior, :SoundGroup_GetMaxAudibleBehavior)
     integer_writer(:behavior=, :SoundGroup_SetMaxAudibleBehavior)
 
+    ##
+    # @!attribute volume
+    # The volume for a sound group, affecting all channels playing the sounds in
+    # this sound group.
+    #
+    # 0.0 is silent, 1.0 is full volume, though negative values and
+    # amplification are supported.
+    #
+    # @return [Float] the sound group volume.
     float_reader(:volume, :SoundGroup_GetVolume)
     float_writer(:volume=, :SoundGroup_SetVolume)
 
+    ##
+    # @!attribute fade_speed
+    # @return [Float] the time in seconds to fade with when {#behavior} is set
+    #   to {SoundGroupBehavior::MUTE}. By default there is no fade.
     float_reader(:fade_speed, :SoundGroup_GetMuteFadeSpeed)
     float_writer(:fade_speed=, :SoundGroup_SetMuteFadeSpeed)
 
-    integer_reader(:count, :SoundGroup_GetNumSounds)
+    ##
+    # @!attribute [r] playing_count
+    # @return [Integer] e number of currently playing channels for the group.
     integer_reader(:playing_count, :SoundGroup_GetNumPlaying)
 
+    ##
+    # @!attribute [r] count
+    # @return [Integer] the current number of sounds in this sound group.
+    integer_reader(:count, :SoundGroup_GetNumSounds)
+
     alias_method :size, :count
 
+    ##
+    # @!attribute [r] name
+    # @return [String] the name of the sound group.
     def name
       buffer = "\0" * 512
       FMOD.invoke(:SoundGroup_GetName, self, buffer, 512)
       buffer.delete("\0")
     end
 
+    ##
+    # Enumerates the sounds contained within the sound group.
+    #
+    # @overload each
+    #   When called with block, yields each {Sound within the object before
+    #   returning self.
+    #   @yield [sound] Yields a sound to the block.
+    #   @yieldparam sound [Sound] The current enumerated polygon.
+    #   @return [self]
+    # @overload each
+    #   When no block specified, returns an Enumerator for the {SoundGroup}.
+    #   @return [Enumerator]
     def each
       return to_enum(:each) unless block_given?
       (0...count).each { |i| yield self[i] }
       self
     end
 
+    ##
+    # Retrieves a sound from within a sound group.
+    #
+    # @param index [Integer] Index of the sound that is to be retrieved.
+    #
+    # @return [Sound, nil] the desired Sound object, or +nil+ if index was out
+    #   of range.
     def [](index)
-      FMOD.valid_range?(0, 0, count - 1)
+      return nil unless FMOD.valid_range?(0, 0, count - 1, false)
       FMOD.invoke(:SoundGroup_GetSound, self, index, sound = int_ptr)
       Sound.new(sound)
     end
 
     alias_method :sound, :[]
 
+    ##
+    # @!attribute [r] parent
+    # @return [System] the parent {System} object that was used to create this
+    #   object.
     def parent
       FMOD.invoke(:SoundGroup_GetSystemObject, self, system = int_ptr)
       System.new(system)
     end
 
+    ##
+    # Stops all sounds within this sound group.
+    # @return [void]
     def stop
       FMOD.invoke(:SoundGroup_Stop, self)
     end