fmod 0.9.1 → 0.9.2

data/lib/fmod/core/dsp_index.rb

@@ -1,8 +1,21 @@
 module FMOD
   module Core
+
+    ##
+    # Strongly-typed index values to denote special types of node within a DSP
+    # chain.
     module DspIndex
+
+      ##
+      # Head of the DSP chain. Equivalent of index 0.
       HEAD = -1
+
+      ##
+      # Built in fader DSP.
       FADER = -2
+
+      ##
+      # Tail of the DSP chain. Equivalent of the number of DSPs minus 1.
       TAIL = -3
     end
   end

data/lib/fmod/core/dsp_type.rb

@@ -1,42 +1,196 @@
 module FMOD
   module Core
+
+    ##
+    # These definitions can be used for creating FMOD defined special effects or
+    # DSP units.
     module DspType
+
+      ##
+      # This unit was created via a non FMOD plugin so has an unknown purpose.
       UNKNOWN = 0
+
+      ##
+      # This unit does nothing but take inputs and mix them together then feed
+      # the result to the sound card unit.
       MIXER = 1
+
+      ##
+      # This unit generates sine/square/saw/triangle or noise tones.
       OSCILLATOR = 2
+
+      ##
+      # @deprecated Deprecated and will be removed in a future release
+      #   (see MULTIBAND_EQ for alternatives).
+      # This unit filters sound using a high quality, resonant low-pass filter
+      # algorithm but consumes more CPU time.
       LOW_PASS = 3
+
+      deprecate_constant :LOW_PASS
+
+      ##
+      # This unit filters sound using a resonant low-pass filter algorithm that
+      # is used in Impulse Tracker, but with limited cutoff range (0 to 8060hz).
       IT_LOW_PASS = 4
+
+      ##
+      # @deprecated Deprecated and will be removed in a future release
+      #   (see MULTIBAND_EQ for alternatives).
+      # This unit filters sound using a resonant high-pass filter algorithm.
       HIGH_PASS = 5
+
+      deprecate_constant :HIGH_PASS
+
+      ##
+      # This unit produces an echo on the sound and fades out at the desired
+      # rate.
       ECHO = 6
+
+      ##
+      # This unit pans and scales the volume of a unit.
       FADER = 7
+
+      ##
+      # This unit produces a flange effect on the sound.
       FLANGE = 8
+
+      ##
+      # This unit distorts the sound.
       DISTORTION = 9
+
+      ##
+      # This unit normalizes or amplifies the sound to a certain level.
       NORMALIZE = 10
+
+      ##
+      # This unit limits the sound to a certain level.
       LIMITER = 11
+
+      ##
+      # @deprecated Deprecated and will be removed in a future release
+      #   (see MULTIBAND_EQ for alternatives).
+      # This unit attenuates or amplifies a selected frequency range.
       PARAM_EQ = 12
+
+      ##
+      # This unit bends the pitch of a sound without changing the speed of
+      # playback.
       PITCH_SHIFT = 13
+
+      ##
+      # This unit produces a chorus effect on the sound.
       CHORUS = 14
+
+      ##
+      # This unit allows the use of Steinberg VST plugins.
       VST_PLUGIN = 15
+
+      ##
+      # This unit allows the use of Nullsoft Winamp plugins.
       WINAMP_PLUGIN = 16
+
+      ##
+      # This unit produces an echo on the sound and fades out at the desired
+      # rate as is used in Impulse Tracker.
       IT_ECHO = 17
+
+      ##
+      # This unit implements dynamic compression (linked/unlinked multichannel,
+      # wide-band)
       COMPRESSOR = 18
+
+      ##
+      # This unit implements SFX reverb.
       SFX_REVERB = 19
+
+      ##
+      # @deprecated Deprecated and will be removed in a future release
+      #   (see MULTIBAND_EQ for alternatives).
+      # This unit filters sound using a simple low-pass with no resonance, but
+      # has flexible cutoff and is fast.
       LOW_PASS_SIMPLE = 20
+
+      deprecate_constant :LOW_PASS_SIMPLE
+
+      ##
+      # This unit produces different delays on individual channels of the sound.
       DELAY = 21
+
+      ##
+      # This unit produces a tremolo / chopper effect on the sound.
       TREMOLO = 22
+
+      ##
+      # @deprecated Do not use, no longer supported.
+      # Unsupported / Deprecated.
       LADSPA_PLUGIN = 23
+
+      deprecate_constant :LADSPA_PLUGIN
+
+      ##
+      # This unit sends a copy of the signal to a return DSP anywhere in the DSP
+      # tree.
       SEND = 24
+
+      ##
+      # This unit receives signals from a number of send DSPs.
       RETURN = 25
+
+      ##
+      # @deprecated Deprecated and will be removed in a future release
+      #   (see MULTIBAND_EQ for alternatives).
+      # This unit filters sound using a simple high-pass with no resonance, but
+      # has flexible cutoff and is fast.
       HIGH_PASS_SIMPLE = 26
+
+      deprecate_constant :HIGH_PASS_SIMPLE
+
+      ##
+      # This unit pans the signal, possibly up-mixing or down-mixing as well.
       PAN = 27
+
+      ##
+      # This unit is a three-band equalizer.
       THREE_EQ = 28
+
+      ##
+      # This unit simply analyzes the signal and provides spectrum information
+      # back through its parameter.
       FFT = 29
+
+      ##
+      # This unit analyzes the loudness and true peak of the signal.
       LOUDNESS_METER = 30
+
+      ##
+      # This unit tracks the envelope of the input/sidechain signal. Deprecated
+      # and will be removed in a future release.
       ENVELOPE_FOLLOWER = 31
+
+      ##
+      # This unit implements convolution reverb.
       CONVOLUTION_REVERB = 32
+
+      ##
+      # This unit provides per signal channel gain, and output channel mapping
+      # to allow 1 multichannel signal made up of many groups of signals to map
+      # to a single output signal.
       CHANNEL_MIX = 33
+
+      ##
+      # This unit "sends" and "receives" from a selection of up to 32 different
+      # slots. It is like a send/return but it uses global slots rather than
+      # returns as the destination. It also has other features. Multiple
+      # transceivers can receive from a single channel, or multiple transceivers
+      # can send to a single channel, or a combination of both.
       TRANSCEIVER = 34
+
+      ##
+      # This unit sends the signal to a 3d object encoder like Dolby Atmos.
       OBJECT_PAN = 35
+
+      ##
+      # This unit is a flexible five band parametric equalizer.
       MULTIBAND_EQ = 36
     end
   end

data/lib/fmod/core/extensions.rb

@@ -1,13 +1,22 @@
 
+##
+# Extensions to Numeric.
 class Numeric
 
+  ##
+  # @return [Numeric] the value clamped between a minimum and maximum value.
+  # @param min [Numeric] The minimum permitted value.
+  # @param max [Numeric] The maximum permitted value.
   def clamp(min, max)
     [min, self, max].sort[1]
   end
 end
 
+##
+# Extensions to String.
 class String
 
+  # Not defined until Ruby 2.4.0
   unless method_defined?(:unpack1)
     def unpack1(format)
       unpack(format).first
@@ -15,13 +24,23 @@ class String
   end
 end
 
+##
+# Extensions to TrueClass.
 class TrueClass
+
+  ##
+  # @return [Integer] the object as an Integer (1).
   def to_i
     1
   end
 end
 
+##
+# Extensions to FalseClass.
 class FalseClass
+
+  ##
+  # @return [Integer] the object as an Integer (0).
   def to_i
     0
   end

data/lib/fmod/core/file_system.rb

@@ -1,5 +1,6 @@
 module FMOD
   module Core
+
     class FileSystem
 
       include Fiddle

data/lib/fmod/core/filter_type.rb

@@ -1,18 +1,80 @@
 module FMOD
   module Core
+
+    ##
+    # Filter types to be used with the MultiBandEQ DSP.
     module FilterType
+
+      ##
+      # Disabled filter, no processing.
       DISABLED = 0
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (12dB per octave) above
+      # a given point (with specified resonance) while allowing the rest to
+      # pass.
       LOW_PASS_12DB = 1
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (24dB per octave) above
+      # a given point (with specified  resonance) while allowing the rest to
+      # pass.
       LOW_PASS_24DB = 2
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (48dB per octave) above
+      # a given point (with specified resonance) while allowing the rest to
+      # pass.
       LOW_PASS_48DB = 3
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (12dB per octave) below
+      # a given point (with specified resonance) while allowing the rest to
+      # pass.
       HIGH_PASS_12DB = 4
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (24dB per octave) below
+      # a given point (with specified resonance) while allowing the rest to
+      # pass.
       HIGH_PASS_24DB = 5
+
+      ##
+      # Resonant low-pass filter, attenuates frequencies (48dB per octave) below
+      # a given point (with specified resonance) while allowing the rest to
+      # pass.
       HIGH_PASS_48DB = 6
+
+      ##
+      # Low-shelf filter, boosts or attenuates frequencies (with specified gain)
+      # below a given point while allowing the rest to pass.
       LOW_SHELF = 7
+
+      ##
+      # High-shelf filter, boosts or attenuates frequencies (with specified
+      # gain) above a given point while allowing the rest to pass.
       HIGH_SHELF = 8
+
+      ##
+      # Peaking filter, boosts or attenuates frequencies (with specified gain)
+      # at a given point (with specified bandwidth) while allowing the rest to
+      # pass.
       PEAKING = 9
+
+      ##
+      # Band-pass filter, allows frequencies at a given point (with specified
+      # bandwidth) to pass while attenuating frequencies outside this range.
       BANDPASS = 10
+
+      ##
+      # Notch or band-reject filter, attenuates frequencies at a given point
+      # (with specified bandwidth) while allowing frequencies outside this
+      # range to pass.
       NOTCH = 11
+      
+      ##
+      # All-pass filter, allows all frequencies to pass, but changes the phase
+      # response at a given point (with specified sharpness).
       ALL_PASS = 12
     end
   end

data/lib/fmod/core/float_description.rb

@@ -1,13 +1,51 @@
 module FMOD
   module Core
+
+    ##
+    # Structure describing a float parameter for a DSP unit.
     class FloatDescription < Structure
 
+      ##
+      # Values mapped linearly across range.
+      LINEAR = 0
+
+      ##
+      # A mapping is automatically chosen based on range and units.
+      AUTO = 1
+
+      ##
+      # Values mapped in a piecewise linear fashion.
+      PIECEWISE_LINEAR = 2
+
+      ##
+      # @param address [Pointer, Integer, String, nil] The address in memory
+      #   where the structure will be created from. If no address is given, new
+      #   memory will be allocated.
       def initialize(address = nil)
         types = [TYPE_FLOAT, TYPE_FLOAT, TYPE_FLOAT, TYPE_INT]
         members = [:min, :max, :default, :mapping]
         super(address, types, members)
       end
 
+      # @!attribute min
+      # @return [Float] the minimum parameter value.
+
+      # @!attribute max
+      # @return [Float] the maximum parameter value.
+
+      # @!attribute default
+      # @return [Float] the default parameter value.
+
+      # @!attribute mapping
+      # Value indicating how the values are distributed across dials and
+      # automation curves (e.g. linearly, exponentially etc).
+      #
+      # Will be one of the following values:
+      # * {LINEAR}
+      # * {AUTO}
+      # * {PIECEWISE_LINEAR}
+      # @return [Integer] the mapping type.
+
       [:min, :max, :default, :mapping].each do |symbol|
         define_method(symbol) { self[symbol] }
       end

data/lib/fmod/core/guid.rb

@@ -2,30 +2,52 @@
 
 module FMOD
   module Core
+
+    ##
+    # Structure describing a globally unique identifier.
     class Guid < Structure
 
+      ##
+      # @param address [Pointer, Integer, String, nil] The address in memory
+      #   where the structure will be created from. If no address is given, new
+      #   memory will be allocated.
       def initialize(address = nil)
         types = [TYPE_INT, TYPE_SHORT, TYPE_SHORT, [TYPE_CHAR, 8]]
         members = [:data1, :data2, :data3, :data4]
         super(address, types, members)
       end
 
+      ##
+      # @return [Integer] the first 8 hexadecimal digits of the GUID.
       def data1
         [self[:data1]].pack('l').unpack1('L')
       end
 
+      ##
+      # @return [Integer] the first group of 4 hexadecimal digits.
       def data2
         [self[:data2]].pack('s').unpack1('S')
       end
 
+      ##
+      # @return [Integer] the second group of 4 hexadecimal digits.
       def data3
         [self[:data3]].pack('s').unpack1('S')
       end
 
+      ##
+      # Array of 8 bytes. The first 2 bytes contain the third group of 4
+      # hexadecimal digits. The remaining 6 bytes contain the final 12.
+      #
+      # hexadecimal digits.
+      # @return [Array<Integer>] the last part if the GUID.
       def data4
         self[:data4].pack('c*').unpack('C*')
       end
 
+      ##
+      # @return [Boolean] +true+ if objects are equal, otherwise +false+.
+      # @param obj [Object] The object to compare.
       def eql?(obj)
         if obj.is_a?(Guid)
           return false unless data1 == obj.data1
@@ -36,10 +58,15 @@ module FMOD
         to_s.tr('-', '').casecmp(obj.to_s.tr('-', '')).zero?
       end
 
+      ##
+      # @return [Boolean] +true+ if objects are equal, otherwise +false+.
+      # @param obj [Object] The object to compare.
       def ==(obj)
         eql?(obj)
       end
 
+      ##
+      # @return [String] the string representation of the GUID.
       def to_s
         d4 = data4
         last = d4[2, 6].map { |byte| "%02X" % byte }.join