fmod 0.9.0

data/lib/fmod/effects/envelope_follower.rb

@@ -0,0 +1,31 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Deprecated and will be removed in a future release.
+    #
+    # This unit tracks the envelope of the input/side-chain signal.
+    #
+    # @attr attack [Float] Attack time (milliseconds).
+    #   * *Minimum:* 0.1
+    #   * *Maximum:* 1000.0
+    #   * *Default:* 20.0
+    # @attr release [Float] Release time (milliseconds).
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 5000.0
+    #   * *Default:* 100.0
+    # @attr_reader envelope [Float] Current value of the envelope.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    # @attr side_chain [Fiddle::Pointer|String] Whether to analyse the
+    #   side-chain signal instead of the input signal.
+    # @note This unit does not affect the incoming signal.
+    class EnvelopeFollower < Dsp
+      float_param(0, :attack, min: 0.1, max: 1000.0)
+      float_param(1, :release, min: 10.0, max: 5000.0)
+      float_param(2, :envelope, readonly: true)
+      data_param(3, :side_chain)
+    end
+  end
+end

data/lib/fmod/effects/fader.rb

@@ -0,0 +1,16 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit pans and scales the volume of a unit.
+    #
+    # @attr gain [Float] Signal gain in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 0.0
+    class Fader < Dsp
+      float_param(0, :gain, min: -80.0, max: 10.0)
+    end
+  end
+end

data/lib/fmod/effects/fft.rb

@@ -0,0 +1,38 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit simply analyzes the signal and provides spectrum information.
+    #
+    # Set the attributes for the spectrum analysis with {#window_size} and
+    # {#window_type}, and retrieve the results with {#spectrum} and
+    # {#dominant_frequency}.
+    #
+    # @attr window_size [Integer] The size of the FFT window. Must be a power of
+    #   2.
+    #   * *Minimum:* 128
+    #   * *Maximum:* 16384
+    #   * *Default:* 2048
+    #   * *Valid:* 128, 256, 512, 1024, 2048, 4096, 8192, 16384
+    # @attr window_type [Integer] The shape of the FFT window.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 5
+    #   * *Default:* {WindowType::HAMMING}
+    #   @see WindowType
+    # @attr_reader spectrum [Pointer] Retrieves a pointer to the current
+    #   spectrum values between 0 and 1 for each "FFT bin".
+    # @attr_reader dominant_frequency [Float] The dominant frequencies for each
+    #   channel.
+    #
+    # @see SpectrumData
+    class FFT < Dsp
+      integer_param(0, :window_size, min: 128, max: 16384)
+      integer_param(1, :window_type, min: 0, max: 5)
+      data_param(2, :spectrum, readonly: true)
+      float_param(3, :dominant_frequency, readonly: true)
+
+      # TODO Get SpectrumData structs
+
+    end
+  end
+end

data/lib/fmod/effects/flange.rb

@@ -0,0 +1,37 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit produces a flange effect on the sound.
+    #
+    # Flange is an effect where the signal is played twice at the same time, and
+    # one copy slides back and forth creating a whooshing or flanging effect.
+    #
+    # As there are 2 copies of the same signal, by default each signal is given
+    # 50% mix, so that the total is not louder than the original unaffected
+    # signal.
+    #
+    # Flange depth is a percentage of a 10ms shift from the original signal.
+    # Anything above 10ms is not considered flange because to the ear it begins
+    # to "echo" so 10ms is the highest value possible.
+    #
+    # @attr mix [Float] Percentage of wet signal in mix.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 100.0
+    #   * *Default:* 50.0
+    # @attr depth [Float] Flange depth (percentage of 40ms delay).
+    #   * *Minimum:* 0.01
+    #   * *Maximum:* 1.0
+    #   * *Default:* 1.0
+    # @attr rate [Float] Flange speed in Hz.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 20.0
+    #   * *Default:* 0.1
+    class Flange < Dsp
+      float_param(0, :mix, min: 0.0, max: 100.0)
+      float_param(1, :depth, min: 0.01, max: 1.0)
+      float_param(2, :rate, min: 0.0, max: 20.0)
+    end
+  end
+end

data/lib/fmod/effects/high_pass.rb

@@ -0,0 +1,24 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Will be removed in a future FMOD version. See {MultibandEq}
+    #   for alternatives.
+    #
+    # This unit filters sound using a resonant high-pass filter algorithm.
+    #
+    # @attr cutoff [Float] High-pass cutoff frequency in Hz.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 5000.0
+    # @attr resonance [Float] High-pass resonance Q value.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 1.0
+    class HighPass < Dsp
+      float_param(0, :cutoff, min: 1.0, max: 22000.0)
+      float_param(1, :resonance, min: 1.0, max: 10.0)
+    end
+  end
+end

data/lib/fmod/effects/high_pass_simple.rb

@@ -0,0 +1,25 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Will be removed in a future FMOD version. See {MultibandEq}
+    #   for alternatives.
+    #
+    # This unit filters sound using a simple high-pass with no resonance, but
+    # has flexible cutoff and is fast.
+    #
+    # This is a very simple single-order high pass filter.
+    #
+    # The emphasis is on speed rather than accuracy, so this should not be used
+    # for task requiring critical filtering.
+    #
+    # @attr cutoff [Float] High-pass cutoff frequency in Hz.
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 1000.0
+    class HighPassSimple < Dsp
+      float_param(0, :cutoff, min: 10.0, max: 22000.0)
+    end
+  end
+end

data/lib/fmod/effects/it_echo.rb

@@ -0,0 +1,56 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit produces an echo on the sound and fades out at the desired rate
+    # as is used in Impulse Tracker.
+    #
+    # This is effectively a software based echo filter that emulates the DirectX
+    # DMO echo effect. Impulse tracker files can support this, and FMOD will
+    # produce the effect on ANY platform, not just those that support DirectX
+    # effects!
+    #
+    # @note Every time the delay is changed, the plugin re-allocates the echo
+    #   buffer. This means the echo will disappear at that time while it refills
+    #   its new buffer.
+    #
+    #   Larger echo delays result in larger amounts of memory allocated.
+    #
+    #   As this is a stereo filter made mainly for IT playback, it is targeted
+    #   for stereo signals. With mono signals only the {#left_delay} is used.
+    #
+    #   For multichannel signals (>2) there will be no echo on those channels.
+    # @attr wet_dry_mix [Float] Ratio of wet (processed) signal to dry
+    #   (unprocessed) signal.
+    #   * *Minimum:* 0.0 (all dry)
+    #   * *Maximum:* 100.0 (all wet)
+    #   * *Default:* 50.0
+    # @attr feedback [Float] Percentage of output fed back into input.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 100.0
+    #   * *Default:* 50.0
+    # @attr left_delay [Float] Delay for left channel, in milliseconds.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 2000.0
+    #   * *Default:* 500.0
+    # @attr right_delay [Float] Delay for right channel, in milliseconds.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 2000.0
+    #   * *Default:* 500.0
+    # @attr pan_delay [Float] Value that specifies whether to swap left and
+    #   right delays with each successive echo. Ranges from 0.0 (equivalent to
+    #   +false+) to 1.0 (equivalent to +true+), meaning no swap.
+    #   @note Currently not supported within the FMOD API.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    #   * *Default:* 0.0
+    class ITEcho < Dsp
+      float_param(0, :wet_dry_mix, min: 0.0, max: 100.0)
+      float_param(1, :feedback, min: 0.0, max: 100.0)
+      float_param(2, :left_delay, min: 1.0, max: 2000.0)
+      float_param(3, :right_delay, min: 1.0, max: 2000.0)
+      float_param(4, :pan_delay , min: 0.0, max: 1.0)
+    end
+  end
+end

data/lib/fmod/effects/it_lowpass.rb

@@ -0,0 +1,36 @@
+
+
+module FMOD
+  module Effects
+
+    ##
+    # 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).
+    #
+    # This is different to the default {LowPass} filter in that it uses a
+    # different quality algorithm and is the filter used to produce the correct
+    # sounding playback in .IT files.
+    #
+    # FMOD Studio's .IT playback uses this filter.
+    #
+    # @note This filter actually has a limited cutoff frequency below the
+    #   specified maximum, due to its limited design, so for a more open range
+    #   filter use {LowPass} or if you don't mind not having resonance,
+    #   {LowPassSimple}.
+    #
+    #   The effective maximum cutoff is about 8060hz.
+    #
+    # @attr cutoff [Float] Low-pass cutoff frequency in Hz.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 5000.0
+    # @attr resonance [Float] Low-pass resonance Q value.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 127.0
+    #   * *Default:* 1.0
+    class ITLowPass < Dsp
+      float_param(0, :cutoff, min: 1.0, max: 22000.0)
+      float_param(1, :resonance, min: 0.0, max: 127.0)
+    end
+  end
+end

data/lib/fmod/effects/ladspa_plugin.rb

@@ -0,0 +1,14 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated  Unsupported / Deprecated.
+    class LadspaPlugin < Dsp
+
+      def initialize
+        raise NotImplementedError, "LADSPA Plugins are no longer supported."
+      end
+    end
+  end
+end

data/lib/fmod/effects/limiter.rb

@@ -0,0 +1,32 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit limits the sound to a certain level.
+    #
+    # @attr release_time [Float] Time to ramp the silence to full in ms.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 1000.0
+    #   * *Default:* 10.0
+    # @attr ceiling [Float] Maximum level of the output signal in dB.
+    #   * *Minimum:* -12.0
+    #   * *Maximum:* 0.0
+    #   * *Default:* 0.0
+    # @attr max_gain [Float] Maximum amplification allowed in dB. Higher values
+    #   allow more boost.
+    #   * *Minimum:* 0.0 (no amplification)
+    #   * *Maximum:* 12.0
+    #   * *Default:* 0.0
+    # @attr mode [Float] Channel processing mode. 0 or 1.
+    #   * *Minimum:* 0.0 (independent, limiter per channel)
+    #   * *Maximum:* 1.0 (linked)
+    #   * *Default:* 0.0
+    class Limiter < Dsp
+      float_param(0, :release_time, min: 1.0, max: 1000.0)
+      float_param(1, :ceiling, min: -12.0, max: 0.0)
+      float_param(2, :max_gain, min: 0.0, max: 12.0)
+      float_param(3, :mode, min: 0.0, max: 1.0)
+    end
+  end
+end

data/lib/fmod/effects/loudness_meter.rb

@@ -0,0 +1,19 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit analyzes the loudness and true peak of the signal.
+    # @note This DSP is not intended for public use.
+    # @attr state [Integer] Integration state
+    #   * *Minimum:* -3
+    #   * *Maximum:* 1
+    # @attr weights [Pointer] Channel weightings for loudness.
+    # @attr loudness [Pointer] Loudness info and maximum true peak level.
+    # @api private
+    class LoudnessMeter < Dsp
+      integer_param(0, :state, min: -3, max: 1)
+      data_param(1, :weights)
+      data_param(2, :loudness)
+    end
+  end
+end

data/lib/fmod/effects/low_pass.rb

@@ -0,0 +1,25 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Will be removed in a future FMOD version. See {MultibandEq}
+    #   for alternatives.
+    #
+    # This unit filters sound using a high quality, resonant low-pass filter
+    # algorithm but consumes more CPU time.
+    #
+    # @attr cutoff [Float] Low-pass cutoff frequency in Hz.
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 5000.0
+    # @attr resonance [Float] Low-pass resonance Q value.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 1.0
+    class LowPass < Dsp
+      float_param(0, :cutoff, min: 10.0, max: 22000.0)
+      float_param(1, :resonance, min: 1.0, max: 10.0)
+    end
+  end
+end

data/lib/fmod/effects/low_pass_simple.rb

@@ -0,0 +1,26 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Will be removed in a future FMOD version. See {MultibandEq}
+    #   for alternatives.
+    #
+    # This unit filters sound using a simple low-pass with no resonance, but has
+    # flexible cutoff and is fast.
+    #
+    # This is a very simple low pass filter, based on two single-pole RC
+    # time-constant modules.
+    #
+    # The emphasis is on speed rather than accuracy, so this should not be used
+    # for task requiring critical filtering.
+    #
+    # @attr cutoff [Float] Low-pass cutoff frequency in Hz.
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 1000.0
+    class LowPassSimple < Dsp
+      float_param(0, :cutoff, min: 10.0, max: 22000.0)
+    end
+  end
+end

data/lib/fmod/effects/mixer.rb

@@ -0,0 +1,11 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit does nothing but take inputs and mix them together then feed the
+    # result to the sound-card unit.
+    class Mixer < Dsp
+    end
+  end
+end

data/lib/fmod/effects/multiband_eq.rb

@@ -0,0 +1,153 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit is a flexible five band parametric equalizer.
+    #
+    # See detailed description of each parameter to determine its effect with
+    # each type of filter.
+    class MultibandEq < Dsp
+
+      ##
+      # Valid bands used for the equalizer.
+      BANDS = [:a, :b, :c, :d, :e].freeze
+
+      ##
+      # Retrieves the filter used for the specified band. The filter determines
+      # the behavior of the other parameters.
+      #
+      # @param band [Symbol] The band.
+      # @return [Integer] The current filter.
+      # @see BANDS
+      # @see FilterType
+      def get_filter(band)
+        index = BANDS.index(band) * 4
+        get_integer(index)
+      end
+
+      ##
+      # Retrieves the frequency for the specified band. This value has different
+      # effects determined by the current filter.
+      #
+      # * *Low-pass/High-pass/Low-shelf/High-shelf:* Significant frequency in
+      #   Hz, cutoff
+      # * *Notch/Peaking/Band-pass:* Center
+      # * *All-pass:* Phase transition point
+      # @param band [Symbol] The band.
+      # @return [Float]
+      # @see BANDS
+      # @see FilterType
+      def get_frequency(band)
+        index = (BANDS.index(band) * 4) + 1
+        get_float(index)
+      end
+
+      ##
+      # Retrieves the quality factor for the specified band. This value has
+      # different effects determined by the current filter.
+      #
+      # * *Low-pass/High-pass:* Quality factor, resonance
+      # * *Notch/Peaking/Band-pass:* Bandwidth
+      # * *All-pass:* Phase transition sharpness
+      # * *Low-shelf/High-shelf:* Unused
+      # @param band [Symbol] The band.
+      # @return [Float]
+      # @see BANDS
+      # @see FilterType
+      def get_quality(band)
+        index = (BANDS.index(band) * 4) + 2
+        get_float(index)
+      end
+
+      ##
+      # Retrieves the gain for the specified band.
+      #
+      # @note Peaking/Low-shelf/High-shelf only.
+      # @param band [Symbol] The band.
+      # @return [Float]
+      # @see BANDS
+      # @see FilterType
+      def get_gain(band)
+        index = (BANDS.index(band) * 4) + 3
+        get_float(index)
+      end
+
+      ##
+      # Sets the filter used for the specified band.
+      #
+      # The filter determines the behavior of the other parameters.
+      # @param band [Symbol] The band.
+      # @param filter [Integer] The filter to set, a {FilterType} value.
+      # @return [self]
+      # @see BANDS
+      # @see FilterType
+      def set_filter(band, filter)
+        index = BANDS.index(band) * 4
+        set_integer(index, filter.clamp(0, 12))
+        self
+      end
+
+      ##
+      # Sets the frequency for the specified band.  This value has different
+      # effects determined by the current filter.
+      #
+      # * *Low-pass/High-pass/Low-shelf/High-shelf:* Significant frequency in
+      #   Hz, cutoff
+      # * *Notch/Peaking/Band-pass:* Center
+      # * *All-pass:* Phase transition point
+      # @param band [Symbol] The band.
+      # @param frequency [Float] The frequency to set.
+      #   * *Minimum:* 20.0
+      #   * *Maximum:* 22000.0
+      #   * *Default:* 8000.0
+      # @return [self]
+      # @see BANDS
+      # @see FilterType
+      def set_frequency(band, frequency)
+        index = (BANDS.index(band) * 4) + 1
+        set_float(index, frequency.clamp(20.0, 22000.0))
+        self
+      end
+
+      ##
+      # Set the quality factor for the specified band. This value has different
+      # effects determined by the current filter.
+      #
+      # * *Low-pass/High-pass:* Quality factor, resonance
+      # * *Notch/Peaking/Band-pass:* Bandwidth
+      # * *All-pass:* Phase transition sharpness
+      # * *Low-shelf/High-shelf:* Unused
+      # @param band [Symbol] The band.
+      # @param quality [Float] The quality factor.
+      #   * *Minimum:* 0.1
+      #   * *Maximum:* 10.0
+      #   * *Default:* 0.707
+      # @return [self]
+      # @see BANDS
+      # @see FilterType
+      def set_quality(band, quality)
+        index = (BANDS.index(band) * 4) + 2
+        set_float(index, quality.clamp(0.1, 10.0))
+        self
+      end
+
+      ##
+      # Sets the gain for the specified band.
+      #
+      # @note Peaking/Low-shelf/High-shelf only.
+      # @param band [Symbol] The band.
+      # @param gain [Float] The boost or attenuation in dB.
+      #   * *Minimum:* -30.0
+      #   * *Maximum:* 30.0
+      #   * *Default:* 0.0
+      # @return [self]
+      # @see BANDS
+      # @see FilterType
+      def set_gain(band, gain)
+        index = (BANDS.index(band) * 4) + 3
+        set_float(index, gain.clamp(-30.0, 30.0))
+        self
+      end
+    end
+  end
+end