Class: FMOD::Dsp

Inherits:
Handle
  • Object
show all
Defined in:
lib/fmod/dsp.rb

Overview

Represents a digital signal processor. This allows for monitoring and applying effects to the sound in real-time.

Defined Under Namespace

Classes: ChannelFormat, DspInfo, WetDryMix

Instance Attribute Summary collapse

Attributes inherited from Handle

#user_data

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Handle

#initialize, #int_ptr, #release

Constructor Details

This class inherits a constructor from FMOD::Handle

Instance Attribute Details

#active ⇒ Boolean

Gets or sets the enabled state of a unit for being processed.

This does not connect or disconnect a unit in any way, it just disables it so that it is not processed.

If a unit is disabled, and has inputs, they will also cease to be processed.

To disable a unit but allow the inputs of the unit to continue being processed, use #bypass instead.

Returns:

  • (Boolean) 


235
 
# File 'lib/fmod/dsp.rb', line 235

bool_reader(:active, :DSP_GetActive)

#bypass ⇒ Boolean

Enables or disables the read callback of a DSP unit so that it does or doesn’t process the data coming into it.

A DSP unit that is disabled still processes its inputs, it will just be “dry”.

If a unit is bypassed, it will still process its inputs.

To disable the unit and all of its inputs, use #active instead.

Returns:

  • (Boolean) 


250
 
# File 'lib/fmod/dsp.rb', line 250

bool_reader(:bypass, :DSP_GetBypass)

#channel_format ⇒ ChannelFormat

Returns The signal format of a DSP unit so that the signal is processed on the speakers specified.

Returns:

  • (ChannelFormat) —

    The signal format of a DSP unit so that the signal is processed on the speakers specified.

See Also:



328
329
330
331
332
333
 
# File 'lib/fmod/dsp.rb', line 328

def channel_format
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT]
  FMOD.invoke(:DSP_GetChannelFormat, self, *args)
  args.map! { |arg| arg.unpack1('L') }
  ChannelFormat.new(*args)
end

#input_count ⇒ Integer (readonly)

Note:

Because this function needs to flush the DSP queue before it can determine how many units are available, this function may block significantly while the background mixer thread operates.

Retrieves the number of inputs connected to the DSP unit.

Inputs are units that feed data to this unit. When there are multiple inputs, they are mixed together.

Returns:

  • (Integer) 


196
 
# File 'lib/fmod/dsp.rb', line 196

integer_reader(:input_count, :DSP_GetNumInputs)

#output_count ⇒ Integer (readonly)

Note:

Because this function needs to flush the DSP queue before it can determine how many units are available, this function may block significantly while the background mixer thread operates.

Retrieves the number of outputs connected to the DSP unit.

Outputs are units that this unit feeds data to. When there are multiple outputs, the data is split and sent to each unit individually.

Returns:

  • (Integer) 


210
 
# File 'lib/fmod/dsp.rb', line 210

integer_reader(:output_count, :DSP_GetNumOutputs)

#parameter_count ⇒ Integer (readonly)

Retrieves the number of parameters a DSP unit has to control its behavior.

Returns:

  • (Integer) 


183
 
# File 'lib/fmod/dsp.rb', line 183

integer_reader(:parameter_count, :DSP_GetNumParameters)

#parent ⇒ System (readonly)

Returns the parent System object that was used to create this object.

Returns:

  • (System) —

    the parent System object that was used to create this object.



376
377
378
379
 
# File 'lib/fmod/dsp.rb', line 376

def parent
  FMOD.invoke(:DSP_GetSystemObject, self, system = int_ptr)
  System.new(system)
end

#type ⇒ Integer (readonly)

Retrieves the pre-defined type of a FMOD registered DSP unit.

Returns:

  • (Integer)

See Also:



175
 
# File 'lib/fmod/dsp.rb', line 175

integer_reader(:type, :DSP_GetType)

#wet_dry_mix ⇒ WetDryMix

Allows the user to scale the affect of a DSP effect, through control of the “wet” mix, which is the post-processed signal and the “dry” which is the pre-processed signal.

The dry signal path is silent by default, because DSP effects transform the input and pass the newly processed result to the output. It does not add to the input.

Returns:

See Also:



283
284
285
286
287
288
 
# File 'lib/fmod/dsp.rb', line 283

def wet_dry_mix
  args = ["\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT]
  FMOD.invoke(:DSP_GetWetDryMix, self, *args)
  args.map! { |arg| arg.unpack1('f') }
  WetDryMix.new(*args)
end

Class Method Details

.bool_param(index, name, **options) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Dynamically creates a method for getting and/or setting a named boolean parameter of a DSP unit.

Parameters:

  • index (Integer) —

    The parameter index.

  • name (Symbol) —

    The name of the attribute to define.

  • options (Hash) —

    The options hash.

Options Hash (**options):

  • :readonly (Boolean) — default: false —

    Flag indicating if a setter function will be defined or not.

  • :write_only (Boolean) — default: false —

    Flag indicating if a getter will be defined or not.



812
813
814
815
816
817
 
# File 'lib/fmod/dsp.rb', line 812

def bool_param(index, name, **options)
  define_method(name) { get_bool(index) } unless options[:write_only]
  unless options[:readonly]
    define_method("#{name}=") { |value| set_bool(index, value) }
  end
end

.data_param(index, name, **options) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Dynamically creates a method for getting and/or setting a named data parameter of a DSP unit.

Parameters:

  • index (Integer) —

    The parameter index.

  • name (Symbol) —

    The name of the attribute to define.

  • options (Hash) —

    The options hash.

Options Hash (**options):

  • :readonly (Boolean) — default: false —

    Flag indicating if a setter function will be defined or not.

  • :write_only (Boolean) — default: false —

    Flag indicating if a getter will be defined or not.



834
835
836
837
838
839
 
# File 'lib/fmod/dsp.rb', line 834

def data_param(index, name, **options)
  define_method(name) { get_data(index) } unless options[:write_only]
  unless options[:readonly]
    define_method("#{name}=") { |value| set_data(index, value) }
  end
end

.float_param(index, name, **options) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Dynamically creates a method for getting and/or setting a named float parameter of a DSP unit.

Parameters:

  • index (Integer) —

    The parameter index.

  • name (Symbol) —

    The name of the attribute to define.

  • options (Hash) —

    The options hash.

Options Hash (**options):

  • :readonly (Boolean) — default: false —

    Flag indicating if a setter function will be defined or not.

  • :write_only (Boolean) — default: false —

    Flag indicating if a getter will be defined or not.

  • :min (Float) — default: nil —

    If defined will clamp any given value to the specified minimum value.

  • :max (Float) — default: nil —

    If defined will clamp any given value to the specified maximum value.



756
757
758
759
760
761
762
763
764
765
 
# File 'lib/fmod/dsp.rb', line 756

def float_param(index, name, **options)
  define_method(name) { get_float(index) } unless options[:write_only]
  unless options[:readonly]
    define_method("#{name}=") do |value|
      value = options[:min] if options[:min] && value < options[:min]
      value = options[:max] if options[:max] && value > options[:max]
      set_float(index, value)
    end
  end
end

.from_handle(address) ⇒ Dsp

Converts the specified memory address to a DSP of the appropriate sub-type instead of generic FMOD::Dsp type.

Parameters:

  • address (Integer|String|Pointer) —

    The memory address of the DSP.

Returns:



161
162
163
164
165
166
167
 
# File 'lib/fmod/dsp.rb', line 161

def self.from_handle(address)
  address = address.unpack1('J') if address.is_a?(String)
  type = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetType, address.to_i, type)
  klass = type_map(type.unpack1('l')) rescue Dsp
  klass.new(address)
end

.integer_param(index, name, **options) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Dynamically creates a method for getting and/or setting a named integer parameter of a DSP unit.

Parameters:

  • index (Integer) —

    The parameter index.

  • name (Symbol) —

    The name of the attribute to define.

  • options (Hash) —

    The options hash.

Options Hash (**options):

  • :readonly (Boolean) — default: false —

    Flag indicating if a setter function will be defined or not.

  • :write_only (Boolean) — default: false —

    Flag indicating if a getter will be defined or not.

  • :min (Integer) — default: nil —

    If defined will clamp any given value to the specified minimum value.

  • :max (Integer) — default: nil —

    If defined will clamp any given value to the specified maximum value.



786
787
788
789
790
791
792
793
794
795
 
# File 'lib/fmod/dsp.rb', line 786

def integer_param(index, name, **options)
  define_method(name) { get_integer(index) } unless options[:write_only]
  unless options[:readonly]
    define_method("#{name}=") do |value|
      value = options[:min] if options[:min] && value < options[:min]
      value = options[:max] if options[:max] && value > options[:max]
      set_float(index, value)
    end
  end
end

.type_map(type) ⇒ Hash{Integer=>Class}

Retrieves a hash mapping the class of each DSP to its corresponding integer type defined in Core::DspType.

Returns:

  • (Hash{Integer=>Class})

Raises:

  • (TypeError) 


94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/fmod/dsp.rb', line 94

def self.type_map(type)
  @type_map ||= {
    DspType::MIXER => FMOD::Effects::Mixer,
    DspType::OSCILLATOR => FMOD::Effects::Oscillator,
    DspType::LOW_PASS => FMOD::Effects::LowPass,
    DspType::IT_LOW_PASS => FMOD::Effects::ITLowPass,
    DspType::HIGH_PASS => FMOD::Effects::HighPass,
    DspType::ECHO => FMOD::Effects::Echo,
    DspType::FADER => FMOD::Effects::Fader,
    DspType::FLANGE => FMOD::Effects::Flange,
    DspType::DISTORTION => FMOD::Effects::Distortion,
    DspType::NORMALIZE => FMOD::Effects::Normalize,
    DspType::LIMITER => FMOD::Effects::Limiter,
    DspType::PARAM_EQ => FMOD::Effects::ParamEq,
    DspType::PITCH_SHIFT => FMOD::Effects::PitchShift,
    DspType::CHORUS => FMOD::Effects::Chorus,
    DspType::VST_PLUGIN => FMOD::Effects::VstPlugin,
    DspType::WINAMP_PLUGIN => FMOD::Effects::WinampPlugin,
    DspType::IT_ECHO => FMOD::Effects::ITEcho,
    DspType::COMPRESSOR => FMOD::Effects::Compressor,
    DspType::SFX_REVERB => FMOD::Effects::SfxReverb,
    DspType::LOW_PASS_SIMPLE => FMOD::Effects::LowPassSimple,
    DspType::DELAY => FMOD::Effects::Delay,
    DspType::TREMOLO => FMOD::Effects::Tremolo,
    DspType::LADSPA_PLUGIN => FMOD::Effects::LadspaPlugin,
    DspType::SEND => FMOD::Effects::Send,
    DspType::RETURN => FMOD::Effects::Return,
    DspType::HIGH_PASS_SIMPLE => FMOD::Effects::HighPassSimple,
    DspType::PAN => FMOD::Effects::Pan,
    DspType::THREE_EQ => FMOD::Effects::ThreeEq,
    DspType::FFT => FMOD::Effects::FFT,
    DspType::LOUDNESS_METER => FMOD::Effects::LoudnessMeter,
    DspType::ENVELOPE_FOLLOWER => FMOD::Effects::EnvelopeFollower,
    DspType::CONVOLUTION_REVERB => FMOD::Effects::ConvolutionReverb,
    DspType::CHANNEL_MIX => FMOD::Effects::ChannelMix,
    DspType::TRANSCEIVER => FMOD::Effects::Transceiver,
    DspType::OBJECT_PAN => FMOD::Effects::ObjectPan,
    DspType::MULTIBAND_EQ => FMOD::Effects::MultibandEq
  }
  return @type_map[type] if type.is_a?(Integer)
  return @type_map.key(type) if type.is_a?(Class)
  raise TypeError, "#{type} is not an Integer or Class."
end

Instance Method Details

#[](index) ⇒ Object

Get parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (Object) —

    the value of the parameter at the specified index.



695
696
697
698
699
700
701
702
703
704
 
# File 'lib/fmod/dsp.rb', line 695

def [](index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  case param_info(index).type
  when ParameterType::FLOAT then get_float(index)
  when ParameterType::INT then get_integer(index)
  when ParameterType::BOOL then get_integer(index)
  when ParameterType::DATA then get_data(index)
  else raise RangeError, 'Unknown data type.'
  end
end

#[]=(index, value) ⇒ Object

Note:

The value must be of the correct type for the specified parameter, no implicit conversions will be performed, i.e. passing an integer to a float parameter will fail, as it is not the correct type. It is up to the user to perform any conversions ahead before passing to this method.

Sets parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

  • value (Float, Integer, Boolean, Pointer, String) —

    The value to set.

Returns:

  • (Object) —

    the value of the parameter at the specified index.



718
719
720
721
722
723
724
725
726
727
 
# File 'lib/fmod/dsp.rb', line 718

def []=(index, value)
  return unless FMOD.valid_range?(index, 0, parameter_count, false)
  case value
  when Float then set_float(index, value)
  when Integer then set_integer(index, value)
  when TrueClass, FalseClass, NilClass then set_bool(index, value)
  when String, Pointer then set_data(index, value)
  else raise TypeError, "#{value} is not a valid DSP parameter type."
  end
end

#add_input(dsp, type) ⇒ DspConnection

Adds the specified DSP unit as an input of the DSP object.

Parameters:

Returns:



501
502
503
504
505
506
 
# File 'lib/fmod/dsp.rb', line 501

def add_input(dsp, type)
  FMOD.type?(dsp, Dsp)
  connection = int_ptr
  FMOD.invoke(:DSP_AddInput, self, dsp, connection, type)
  DspConnection.new(connection)
end

#disconnect(inputs, outputs) ⇒ void

This method returns an undefined value.

Helper function to disconnect either all inputs or all outputs of a DSP unit.

Parameters:

  • inputs (Boolean) —

    true to disconnect all inputs to this DSP unit, otherwise false to leave input connections alone.

  • outputs (Boolean) —

    true to disconnect all outputs to this DSP unit, otherwise false to leave output connections alone.



418
419
420
 
# File 'lib/fmod/dsp.rb', line 418

def disconnect(inputs, outputs)
  FMOD.invoke(:DSP_DisconnectAll, self, inputs.to_i, outputs.to_i)
end

#disconnect_from(dsp, connection = nil) ⇒ void

Note:

If you have a handle to the connection pointer that binds these 2 DSP units, then it will become invalid. The connection is then sent back to a freelist to be re-used again by a later addInput command.

This method returns an undefined value.

Disconnect the DSP unit from the specified input.

Parameters:

  • dsp (Dsp) —

    The input unit that this unit is to be disconnected from.

  • connection (DspConnection) (defaults to: nil) —

    If there is more than one connection between 2 dDSP units, this can be used to define which of the connections should be disconnected.



435
436
437
438
439
 
# File 'lib/fmod/dsp.rb', line 435

def disconnect_from(dsp, connection = nil)
  FMOD.type?(dsp, Dsp) unless dsp.nil?
  FMOD.type?(connection, DspConnection) unless connection.nil?
  FMOD.invoke(:DSP_DisconnectFrom, self, dsp, connection)
end

#enable_metering(input, output) ⇒ void

This method returns an undefined value.

Enable metering for a DSP unit.

Parameters:

  • input (Boolean) —

    Enable metering for the input signal (pre-processing). Specify true to turn on input level metering, false to turn it off.

  • output (Boolean) —

    Enable metering for the output signal (post-processing). Specify true to turn on output level metering, false to turn it off.



572
573
574
 
# File 'lib/fmod/dsp.rb', line 572

def enable_metering(input, output)
  FMOD.invoke(:DSP_SetMeteringEnabled, self, input ? 1 :0, output.to_i)
end

#get_bool(index) ⇒ Boolean?

Retrieves the unit’s boolean parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (Boolean, nil) —

    the parameter specified, or nil if index is out of range.



611
612
613
614
615
616
 
# File 'lib/fmod/dsp.rb', line 611

def get_bool(index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  buffer = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetParameterBool, self, index, buffer, nil, 0)
  buffer.unpack1('l') != 0
end

#get_data(index) ⇒ Pointer?

Retrieves the unit’s data parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (Pointer, nil) —

    the parameter specified, or nil if index is out of range.



625
626
627
628
629
630
631
 
# File 'lib/fmod/dsp.rb', line 625

def get_data(index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  pointer = int_ptr
  size = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetParameterData, self, index, pointer, size, nil, 0)
  Pointer.new(pointer.unpack('J'), size.unpack1('l'))
end

#get_float(index) ⇒ Float?

Retrieves the unit’s float parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (Float, nil) —

    the parameter specified, or nil if index is out of range.



583
584
585
586
587
588
 
# File 'lib/fmod/dsp.rb', line 583

def get_float(index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  buffer = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:DSP_GetParameterFloat, self, index, buffer, nil, 0)
  buffer.unpack1('f')
end

#get_integer(index) ⇒ Integer?

Retrieves the unit’s integer parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (Integer, nil) —

    the parameter specified, or nil if index is out of range.



597
598
599
600
601
602
 
# File 'lib/fmod/dsp.rb', line 597

def get_integer(index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  buffer = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetParameterInt, self, index, buffer, nil, 0)
  buffer.unpack1('l')
end

#idle? ⇒ Boolean

Retrieves the idle state of a DSP. A DSP is idle when no signal is coming into it. This can be a useful method of determining if a DSP sub branch is finished processing, so it can be disconnected for example.

Returns:

  • (Boolean) 


219
 
# File 'lib/fmod/dsp.rb', line 219

bool_reader(:idle?, :DSP_GetIdle)

#info ⇒ DspInfo

name, version, default channels and width and height of configuration dialog box if it exists.

Returns:

  • (DspInfo) —

    the information about the current DSP unit, including



345
346
347
348
349
350
351
352
353
 
# File 'lib/fmod/dsp.rb', line 345

def info
  name, vs = "\0" * 32, "\0" * SIZEOF_INT
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT]
  FMOD.invoke(:DSP_GetInfo, self, name, vs, *args)
  args = args.map { |arg| arg.unpack1('l') }
  vs = vs.unpack1('L').to_s(16).rjust(8, '0')
  version = "#{vs[0, 4].to_i}.#{vs[4, 4].to_i}"
  DspInfo.new(name.delete("\0"), version, *args)
end

#input(index) ⇒ Dsp

Retrieves a DSP unit which is acting as an input to this unit.

Parameters:

  • index (Integer) —

    Index of the input unit to retrieve.

Returns:

  • (Dsp) —

    the input unit.



447
448
449
450
451
 
# File 'lib/fmod/dsp.rb', line 447

def input(index)
  input = int_ptr
  FMOD.invoke(:DSP_GetInput, self, index, input, nil)
  Dsp.from_handle(input)
end

#input_connection(index) ⇒ DspConnection

Retrieves the connection which to a DSP acting as an input to this unit.

Parameters:

  • index (Integer) —

    Index of the input unit to retrieve the connection.

Returns:



471
472
473
474
475
 
# File 'lib/fmod/dsp.rb', line 471

def input_connection(index)
  connection = int_ptr
  FMOD.invoke(:DSP_GetInput, self, index, nil, connection)
  DspConnection.new(connection)
end

#input_metering? ⇒ Boolean

Returns a flag indicating if input metering for the DSP it is enabled or not.

Returns:

  • (Boolean) —

    a flag indicating if input metering for the DSP it is enabled or not.



546
547
548
549
550
 
# File 'lib/fmod/dsp.rb', line 546

def input_metering?
  enabled = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetMeteringEnabled, self, enabled, nil)
  enabled.unpack1('l') != 0
end

#name ⇒ String

Retrieves the name of this DSP unit.

Returns:



256
257
258
259
260
 
# File 'lib/fmod/dsp.rb', line 256

def name
  name = "\0" * 32
  FMOD.invoke(:DSP_GetInfo, self, name, nil, nil, nil, nil)
  name.delete("\0")
end

#output(index) ⇒ Dsp

Retrieves a DSP unit which is acting as an output to this unit.

Parameters:

  • index (Integer) —

    Index of the output unit to retrieve.

Returns:

  • (Dsp) —

    the output unit.



459
460
461
462
463
 
# File 'lib/fmod/dsp.rb', line 459

def output(index)
  output = int_ptr
  FMOD.invoke(:DSP_GetOutput, self, index, output, nil)
  Dsp.from_handle(output)
end

#output_connection(index) ⇒ DspConnection

Retrieves the connection which to a DSP acting as an output to this unit.

Parameters:

  • index (Integer) —

    Index of the output unit to retrieve the connection.

Returns:



483
484
485
486
487
 
# File 'lib/fmod/dsp.rb', line 483

def output_connection(index)
  connection = int_ptr
  FMOD.invoke(:DSP_GetOutput, self, index, nil, connection)
  DspConnection.new(connection)
end

#output_format(format) ⇒ ChannelFormat #output_format(mask, count, speaker_mode) ⇒ ChannelFormat

Call the DSP process function to retrieve the output signal format for a DSP based on input values.

A DSP unit may be an up mixer or down mixer for example. In this case if you specified 6 in for a down-mixer, it may provide you with 2 out for example.

Generally the input values will be reproduced for the output values, but some DSP units will want to alter the output format.

Overloads:

  • #output_format(format) ⇒ ChannelFormat

    Parameters:

    • format (ChannelFormat) —

      Structure describing the incoming channel format.

  • #output_format(mask, count, speaker_mode) ⇒ ChannelFormat

    Parameters:

    • mask (Integer) —

      Channel bit-mask representing the speakers enabled for the incoming signal.

    • count (Integer) —

      Number of channels for the incoming signal.

    • speaker_mode (Integer) —

      Speaker mode for the incoming signal.

Returns:



529
530
531
532
533
534
535
536
537
538
539
540
541
 
# File 'lib/fmod/dsp.rb', line 529

def output_format(*args)
  if args.size == 3 && args.all? { |arg| arg.is_a?(Integer) }
    mask, count, mode = args
  elsif args.size == 1 && FMOD.type?(args[0], ChannelFormat)
    mask, count, mode = args[0].values
  else
    mask, count, mode = channel_format.values
  end
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT]
  FMOD.invoke(:DSP_GetOutputChannelFormat, mask, count, mode, *args)
  args.map! { |arg| arg.unpack1('L') }
  ChannelFormat.new(*args)
end

#output_metering? ⇒ Boolean

Returns a flag indicating if output metering for the DSP it is enabled or not.

Returns:

  • (Boolean) —

    a flag indicating if output metering for the DSP it is enabled or not.



555
556
557
558
559
 
# File 'lib/fmod/dsp.rb', line 555

def output_metering?
  enabled = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetMeteringEnabled, self, nil, enabled)
  enabled.unpack1('l') != 0
end

#param_info(index) ⇒ ParameterInfo?

Retrieve information about a specified parameter within the DSP unit.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

Returns:

  • (ParameterInfo, nil) —

    the information about the specified parameter or nil if the index was out of range.



402
403
404
405
406
 
# File 'lib/fmod/dsp.rb', line 402

def param_info(index)
  return nil unless FMOD.valid_range?(index, 0, parameter_count, false)
  FMOD.invoke(:DSP_GetParameterInfo, self, index, info = int_ptr)
  ParameterInfo.new(info.unpack1('J'))
end

#play(group = nil) ⇒ Channel

Plays a sound object on a particular channel and ChannelGroup.

When a sound is played, it will use the sound’s default frequency and priority.

Parameters:

  • group (ChannelGroup) (defaults to: nil) —

    The ChannelGroup become a member of. This is more efficient than using Channel#group, as it does it during the channel setup, rather than connecting to the master channel group, then later disconnecting and connecting to the new ChannelGroup when specified. Specify nil to ignore (use master ChannelGroup).

Returns:

  • (Channel) —

    the newly playing channel.

See Also:



152
153
154
 
# File 'lib/fmod/dsp.rb', line 152

def play(group = nil)
  parent.play_dsp(self, group, false)
end

#reset ⇒ void

This method returns an undefined value.

Calls the DSP unit’s reset function, which will clear internal buffers and reset the unit back to an initial state.

Calling this function is useful if the DSP unit relies on a history to process itself (ie an echo filter).

If you disconnected the unit and reconnected it to a different part of the network with a different sound, you would want to call this to reset the units state (ie clear and reset the echo filter) so that you dont get left over artifacts from the place it used to be connected.



368
369
370
 
# File 'lib/fmod/dsp.rb', line 368

def reset
  FMOD.invoke(:DSP_Reset, self)
end

#set_bool(index, value) ⇒ self

Sets the unit’s boolean parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

  • value (Boolean) —

    The value to set.

Returns:

  • (self) 


666
667
668
669
670
 
# File 'lib/fmod/dsp.rb', line 666

def set_bool(index, value)
  return unless FMOD.valid_range?(index, 0, parameter_count, false)
  FMOD.invoke(:DSP_SetParameterBool, self, index, value.to_i)
  self
end

#set_data(index, value) ⇒ self

Sets the unit’s data parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

  • value (Pointer, String) —

    The value to set.

Returns:

  • (self) 


679
680
681
682
683
684
685
686
687
 
# File 'lib/fmod/dsp.rb', line 679

def set_data(index, value)
  return unless FMOD.valid_range?(index, 0, parameter_count, false)
  unless FMOD.type?(value, String, false)
    FMOD.type?(value, Pointer)
  end
  size = value.is_a?(String) ? value.bytesize : value.size
  FMOD.invoke(:DSP_SetParameterData, self, index, value, size)
  self
end

#set_float(index, value) ⇒ self

Sets the unit’s float parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

  • value (Float) —

    The value to set.

Returns:

  • (self) 


640
641
642
643
644
 
# File 'lib/fmod/dsp.rb', line 640

def set_float(index, value)
  return unless FMOD.valid_range?(index, 0, parameter_count, false)
  FMOD.invoke(:DSP_SetParameterFloat, self, index, value)
  self
end

#set_integer(index, value) ⇒ self

Sets the unit’s integer parameter by index.

Parameters:

  • index (Integer) —

    Parameter index for this unit.

  • value (Integer) —

    The value to set.

Returns:

  • (self) 


653
654
655
656
657
 
# File 'lib/fmod/dsp.rb', line 653

def set_integer(index, value)
  return unless FMOD.valid_range?(index, 0, parameter_count, false)
  FMOD.invoke(:DSP_SetParameterInt, self, index, value)
  self
end

#set_wet_dry_mix(pre_wet, post_wet, dry) ⇒ self

Allows the user to scale the affect of a DSP effect, through control of the “wet” mix, which is the post-processed signal and the “dry” which is the pre-processed signal.

The dry signal path is silent by default, because dsp effects transform the input and pass the newly processed result to the output. It does not add to the input.

Parameters:

  • pre_wet (Float) —

    Floating point value from 0 to 1, describing a linear scale of the “wet” (pre-processed signal) mix of the effect. Scale can be lower than 0 (negating) and higher than 1 (amplifying). *

    • Default: 1.0

  • post_wet (Float) —

    Floating point value from 0 to 1, describing a linear scale of the “wet” (post-processed signal) mix of the effect. Scale can be lower than 0 (negating) and higher than 1 (amplifying).

    • Default: 1.0

  • dry (Float) —

    Floating point value from 0 to 1, describing a linear scale of the “dry” (pre-processed signal) mix of the effect. Scale can be lower than 0 and higher than 1 (amplifying).

    • Default: 0.0

Returns:

  • (self) 


319
320
321
322
 
# File 'lib/fmod/dsp.rb', line 319

def set_wet_dry_mix(pre_wet, post_wet, dry)
  FMOD.invoke(:DSP_SetWetDryMix, self, pre_wet, post_wet, dry)
  self
end

#show_dialog(hwnd, show = true) ⇒ void

This method returns an undefined value.

Display or hide a DSP unit configuration dialog box inside the target window.

Parameters:

  • hwnd (Pointer) —

    Target HWND in windows to display configuration dialog.

  • show (Boolean) (defaults to: true) —

    true to display the window within the parent window, otherwise false to remove it.



391
392
393
 
# File 'lib/fmod/dsp.rb', line 391

def show_dialog(hwnd, show = true)
  FMOD.invoke(:DSP_ShowConfigDialog, self, hwnd, show.to_i)
end

#to_s ⇒ String

Returns the string representation of the DSP unit.

Returns:

  • (String) —

    the string representation of the DSP unit.



731
732
733
 
# File 'lib/fmod/dsp.rb', line 731

def to_s
  "#{name} v.#{version}"
end

#version ⇒ String

Retrieves the version of this DSP as string.

Returns:



265
266
267
268
269
270
 
# File 'lib/fmod/dsp.rb', line 265

def version
  vs = "\0" * SIZEOF_INT
  FMOD.invoke(:DSP_GetInfo, self, nil, vs, nil, nil, nil)
  version = vs.unpack1('L').to_s(16).rjust(8, '0')
  "#{version[0, 4].to_i}.#{version[4, 4].to_i}"
end