fmod 0.9.0

data/lib/fmod/dsp_connection.rb

@@ -0,0 +1,113 @@
+
+module FMOD
+  class DspConnection < Handle
+
+    ##
+    # Default connection type. Audio is mixed from the input to the output DSP's
+    # audible buffer.
+    STANDARD = 0
+    ##
+    # Sidechain connection type. Audio is mixed from the input to the output
+    # DSP's sidechain buffer.
+    SIDECHAIN = 1
+    ##
+    # Send connection type. Audio is mixed from the input to the output DSP's
+    # audible buffer, but the input is *NOT* executed, only copied from. A
+    # standard connection or sidechain needs to make an input execute to
+    # generate.rb data.
+    SEND = 2
+    ##
+    # Send sidechain connection type. Audio is mixed from the input to the
+    # output DSP's sidechain buffer, but the input is *NOT* executed, only
+    # copied from. A standard connection or sidechain needs to make an input
+    # execute to generate.rb data.
+    SEND_SIDECHAIN = 3
+
+    ##
+    # @!attribute [r] type
+    # @return [Integer] the type of the connection between 2 DSP units.
+    #
+    #   Will be one of the following:
+    #   * {STANDARD}
+    #   * {SIDECHAIN}
+    #   * {SEND}
+    #   * {SEND_SIDECHAIN}
+    integer_reader(:type, :DSPConnection_GetType)
+
+    ##
+    # @!attribute mix
+    # The volume of the connection - the scale level of the input before being
+    # passed to the output.
+    # * *Minimum:* 0.0 (silent)
+    # * *Maximum:* 1.0 (full volume)
+    # * *Default:* 1.0
+    # @return [Float] the volume or mix level.
+    float_reader(:mix, :DSPConnection_GetMix)
+    float_writer(:mix=, :DSPConnection_SetMix, 0.0, 1.0)
+
+    ##
+    # @!attribute [r] input
+    # @return [Dsp] the DSP unit that is the input of this connection.
+    def input
+      dsp = int_ptr
+      FMOD.invoke(:DSPConnection_GetInput, self, dsp)
+      Dsp.from_handle(dsp)
+    end
+
+    ##
+    # @!attribute [r] input
+    # @return [Dsp] the DSP unit that is the output of this connection.
+    def output
+      dsp = int_ptr
+      FMOD.invoke(:DSPConnection_GetOutput, self, dsp)
+      Dsp.from_handle(dsp)
+    end
+
+    ##
+    # @!attribute matrix
+    # A 2D pan matrix that maps input channels (columns) to output speakers
+    # (rows).
+    #
+    # Levels can be below 0 to invert a signal and above 1 to amplify the
+    # signal. Note that increasing the signal level too far may cause audible
+    # distortion.
+    #
+    # The matrix size will generally be the size of the number of channels in
+    # the current speaker mode. Use {System.software_format }to determine this.
+    #
+    # If a matrix already exists then the matrix passed in will applied over the
+    # top of it. The input matrix can be smaller than the existing matrix.
+    #
+    # A "unit" matrix allows a signal to pass through unchanged. For example for
+    # a 5.1 matrix a unit matrix would look like this:
+    #   [[ 1, 0, 0, 0, 0, 0 ]
+    #    [ 0, 1, 0, 0, 0, 0 ]
+    #    [ 0, 0, 1, 0, 0, 0 ]
+    #    [ 0, 0, 0, 1, 0, 0 ]
+    #    [ 0, 0, 0, 0, 1, 0 ]
+    #    [ 0, 0, 0, 0, 0, 1 ]]
+    #
+    # @return [Array<Array<Float>>] a 2-dimensional array of volume levels in
+    #   row-major order. Each row represents an output speaker, each column
+    #   represents an input channel.
+    def matrix
+      o, i = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
+      FMOD.invoke(:DSPConnection_GetMixMatrix, self, nil, o, i, 0)
+      o, i = o.unpack1('l'), i.unpack1('l')
+      return [] if o.zero? || i.zero?
+      buffer = "\0" * (SIZEOF_FLOAT * o * i)
+      FMOD.invoke(:DSPConnection_GetMixMatrix, self, buffer, nil, nil, 0)
+      buffer.unpack('f*').each_slice(i).to_a
+    end
+
+    def matrix=(matrix)
+      out_count, in_count = matrix.size, matrix.first.size
+      unless matrix.all? { |ary| ary.size == in_count }
+        raise Error, "Matrix contains unequal length input channels."
+      end
+      data = matrix.flatten.pack('f*')
+      FMOD.invoke(:DSPConnection_SetMixMatrix, self, data,
+        out_count, in_count, 0)
+    end
+  end
+end

data/lib/fmod/effects.rb

@@ -0,0 +1,38 @@
+
+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'

data/lib/fmod/effects/channel_mix.rb

@@ -0,0 +1,101 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # 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.
+    #
+    # @attr output_grouping [Integer] Determines the output mapping.
+    #
+    #   This value will set the output speaker format for the DSP, and also map
+    #   the incoming channels to the outgoing channels in a round-robin fashion.
+    #   Use this for example play a 32 channel input signal as if it were a
+    #   repeating group of output signals.
+    #
+    #   {ALL_MONO} = all incoming channels are mixed to a mono output.
+    #
+    #   {ALL_STEREO} = all incoming channels are mixed to a stereo output, ie
+    #   even incoming channels 0,2,4,6,etc are mixed to left, and odd incoming
+    #   channels 1,3,5,7,etc are mixed to right.
+    #
+    #   {ALL_5POINT1} = all incoming channels are mixed to a 5.1 output. If
+    #   there are less than 6 coming in, it will just fill the first n channels
+    #   in the 6 output channels. If there are more, then it will repeat the
+    #   input pattern to the output like it did with the stereo case, ie 12
+    #   incoming channels are mapped as 0-5 mixed to the 5.1 output and 6 to 11
+    #   mapped to the 5.1 output.
+    #
+    #   {ALL_LFE} = all incoming channels are mixed to a 5.1 output but via the
+    #   LFE channel only.
+    #   * *Default:* {DEFAULT}
+    #   @see DEFAULT
+    #   @see ALL_MONO
+    #   @see ALL_STEREO
+    #   @see ALL_QUAD
+    #   @see ALL_5POINT1
+    #   @see ALL_7POINT1
+    #   @see ALL_LFE
+    class ChannelMix < Dsp
+
+      ##
+      # Output channel count = input channel count.
+      # @see SpeakerIndex
+      DEFAULT = 0
+
+      ##
+      # Output channel count = 1. Mapping: Mono, Mono, Mono, Mono, Mono,
+      # Mono, ... (each channel all the way up to {FMOD::MAX_CHANNEL_WIDTH}
+      # channels are treated as if they were mono)
+      ALL_MONO = 1
+
+      ##
+      # Output channel count = 2. Mapping: Left, Right, Left, Right, Left,
+      # Right, ... (each pair of channels is treated as stereo all the way up to
+      # {FMOD::MAX_CHANNEL_WIDTH} channels)
+      ALL_STEREO = 2
+
+      ##
+      # Output channel count = 4. Mapping: Repeating pattern of Front Left,
+      # Front Right, Surround Left, Surround Right
+      ALL_QUAD = 3
+
+      ##
+      # Output channel count = 6. Mapping: Repeating pattern of Front Left,
+      # Front Right, Center, LFE, Surround Left, Surround Right.
+      ALL_5POINT1 = 4
+
+      ##
+      # Output channel count = 8. Mapping: Repeating pattern of Front Left,
+      # Front Right, Center, LFE, Surround Left, Surround Right, Back Left, Back
+      # Right.
+      ALL_7POINT1 = 5
+
+      ##
+      # Output channel count = 6. Mapping: Repeating pattern of LFE in a 5.1
+      # output signal.
+      ALL_LFE = 6
+
+      integer_param(0, :output_grouping, min: 0, max: 6)
+
+      ##
+      # Retrieves the gain for the specified channel.
+      # @param channel [Integer] The channel index, clamped between 0 and 31.
+      # @return [Float] The gain.
+      def [](channel)
+        get_float(channel.clamp(0, 31) + 1)
+      end
+
+      ##
+      # Sets the gain, in dB for the specified channel.
+      # @param channel [Integer] The channel index, clamped between 0 and 31.
+      # @param gain [Float] The gain, in dB, clamped between -80.0 and 10.0.
+      # @return [Float] The gain.
+      def []=(channel, gain)
+        set_float(channel.clamp(0, 31) + 1, gain.clamp(-80.0, 10.0))
+        gain
+      end
+    end
+  end
+end

data/lib/fmod/effects/chorus.rb

@@ -0,0 +1,30 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit produces a chorus effect on the sound.
+    #
+    # Chorus is an effect where the sound is more "spacious" due to 1 to 3
+    # versions of the sound being played along side the original signal but with
+    # the pitch of each copy modulating on a sine wave.
+    #
+    # @attr mix [Float] Volume of original signal to pass to output.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 100.0
+    #   * *Default:* 50.0
+    # @attr rate [Float] Chorus modulation rate in Hz.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 20.0
+    #   * *Default:* 0.8
+    # @attr depth [Float] Chorus modulation depth.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 100.0
+    #   * *Default:* 3.0
+    class Chorus < Dsp
+      float_param(0, :mix, min: 0.0, max: 100.0)
+      float_param(1, :rate, min: 0.0, max: 20.0)
+      float_param(2, :depth, min: 0.0, max: 100.0)
+    end
+  end
+end

data/lib/fmod/effects/compressor.rb

@@ -0,0 +1,52 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit implements dynamic compression (linked/unlinked multichannel, wide-band).
+    #
+    # @attr threshold [Float] Threshold level (dB).
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 0.0
+    #   * *Default:* 0.0
+    # @attr ratio [Float] Compression Ratio (dB/dB).
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 50.0
+    #   * *Default:* 2.5
+    # @attr attack [Float] Attack time (milliseconds).
+    #   * *Minimum:* 0.1
+    #   * *Maximum:* 1000.0
+    #   * *Default:* 20.0
+    # @attr release_time [Float] Release time (milliseconds).
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 5000.0
+    #   * *Default:* 100.0
+    # @attr make_up_gain [Float] Make-up gain (dB) applied after limiting.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 30.0
+    #   * *Default:* 0.0
+    # @attr use_sidechain [Boolean] Whether to analyse the sidechain signal
+    #   instead of the input signal.
+    #   * *Default:* +false+
+    # @attr linked [Boolean]
+    #   * *true:* Linked
+    #   * *false:* Independent (compressor per channel)
+    #   * *Default:* +false+
+    class Compressor < Dsp
+      float_param(0, :threshold, min: -60.0, mix: 0.0)
+      float_param(1, :ratio, min: 1.0, max: 50.0)
+      float_param(2, :attack, min: 0.1, max: 500.0)
+      float_param(3, :release_time, min: 10.0, max: 5000.0)
+      float_param(4, :make_up_gain, min: -30.0, max: 30.0)
+      bool_param(6, :linked)
+
+      def sidechain
+        get_data(5).to_s(SIZEOF_INT).unpack1('l') != 0
+      end
+
+      def sidechain=(bool)
+        value = [bool.to_i].pack('l')
+        set_data(5, value)
+      end
+    end
+  end
+end

data/lib/fmod/effects/convolution_reverb.rb

@@ -0,0 +1,31 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit implements convolution reverb.
+    #
+    # @attr_writer ir [Pointer|String] Array of signed 16-bit (short) PCM data
+    #   to be used as reverb IR. First member of the array should be a 16-bit
+    #   value (short) which specifies the number of channels. Array looks like
+    #   [index 0 = channel_count][index 1+ = raw 16-bit PCM data].
+    #
+    #   Data is copied internally so source can be freed.
+    # @attr wet [Float] Volume of echo signal to pass to output in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 0.0
+    # @attr dry [Float] Original sound volume in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 0.0
+    # @attr linked [Boolean] Indicates if channels are mixed together before
+    #   processing through the reverb.
+    #   * *Default:* +true+
+    class ConvolutionReverb < Dsp
+      data_param(0, :ir, write_only: true)
+      float_param(1, :wet, min: -80.0, max: 10.0)
+      float_param(2, :dry, min: -80.0, max: 10.0)
+      bool_param(3, :linked)
+    end
+  end
+end

data/lib/fmod/effects/delay.rb

@@ -0,0 +1,44 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit produces different delays on individual channels of the sound.
+    #
+    # @note Every time MaxDelay is changed, the plugin re-allocates the delay
+    #   buffer. This means the delay will disappear at that time while it
+    #   refills its new buffer.
+    #
+    #   A larger {#max_delay} results in larger amounts of memory allocated.
+    #
+    #   Channel delays above {#max_delay} will be clipped to MaxDelay and the
+    #   delay buffer will not be re-sized.
+    #
+    # @attr max_delay [Float] Maximum delay in ms.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 10000.0
+    #   * *Default:* 10.0
+    class Delay < Dsp
+
+      ##
+      # Retrieves the delay, in ms, for the specified channel.
+      # @param channel [Integer] The channel index to retrieve (0 to 15).
+      # @return [Float]
+      def [](channel)
+        get_float(channel.clamp(0, 15))
+      end
+
+      ##
+      # Sets the delay, in ms, for the specified channel.
+      # @param channel [Integer] The channel index to set (0 to 15).
+      # @param delay [Float] The delay value, clamped between 0.0 and 10000.0.
+      # @return [Float] The delay.
+      def []=(channel, delay)
+        set_float(channel.clamp(0, 15), delay.clamp(0.0, 10000.0))
+        delay
+      end
+
+      integer_param(16, :max_delay, min: 0.0, max: 10000.0)
+    end
+  end
+end

data/lib/fmod/effects/distortion.rb

@@ -0,0 +1,16 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit distorts the sound.
+    #
+    # @attr distortion [Float] Distortion value.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    #   * *Default:* 0.5
+    class Distortion < Dsp
+      float_param(0, :distortion, min: 0.0, max: 1.0)
+    end
+  end
+end

data/lib/fmod/effects/dsps.rb

@@ -0,0 +1,10 @@
+module FMOD
+  module Effects
+
+
+
+
+    ###### TODO: MultibandE1 low and high pass examples
+
+  end
+end

data/lib/fmod/effects/echo.rb

@@ -0,0 +1,37 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit produces an echo on the sound and fades out at the desired rate.
+    #
+    # @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.
+    #
+    # @attr delay [Float] Echo delay in ms.
+    #   * *Minimum:* 10.0
+    #   * *Maximum:* 5000.0
+    #   * *Default:* 500.0
+    # @attr feedback [Float] Echo decay per delay.
+    #   * *Minimum:* 0.0 (total decay)
+    #   * *Maximum:* 100.0 (no decay)
+    #   * *Default:* 50.0
+    # @attr dry_level [Float] Original sound volume in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 0.0
+    # @attr wet_level [Float] Volume of echo signal to pass to output in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 10.0
+    #   * *Default:* 0.0
+    class Echo < Dsp
+      float_param(0, :delay, min: 10.0, max: 5000.0)
+      float_param(1, :feedback, min: 0.0, max: 100.0)
+      float_param(2, :dry_level, min: -80.0, max: 10.0)
+      float_param(3, :wet_level, min: -80.0, max: 10.0)
+    end
+  end
+end