Module: FMOD

Includes:
Fiddle
Defined in:
lib/fmod.rb,
lib/fmod/dsp.rb,
lib/fmod/core.rb,
lib/fmod/error.rb,
lib/fmod/sound.rb,
lib/fmod/handle.rb,
lib/fmod/system.rb,
lib/fmod/channel.rb,
lib/fmod/effects.rb,
lib/fmod/version.rb,
lib/fmod/core/tag.rb,
lib/fmod/geometry.rb,
lib/fmod/reverb3D.rb,
lib/fmod/core/guid.rb,
lib/fmod/core/mode.rb,
lib/fmod/core/driver.rb,
lib/fmod/core/result.rb,
lib/fmod/core/reverb.rb,
lib/fmod/core/vector.rb,
lib/fmod/effects/fft.rb,
lib/fmod/effects/pan.rb,
lib/fmod/sound_group.rb,
lib/fmod/effects/dsps.rb,
lib/fmod/effects/echo.rb,
lib/fmod/effects/send.rb,
lib/fmod/channel_group.rb,
lib/fmod/core/dsp_type.rb,
lib/fmod/core/tag_type.rb,
lib/fmod/effects/delay.rb,
lib/fmod/effects/fader.rb,
lib/fmod/effects/mixer.rb,
lib/fmod/core/dsp_index.rb,
lib/fmod/core/structure.rb,
lib/fmod/core/time_unit.rb,
lib/fmod/dsp_connection.rb,
lib/fmod/effects/chorus.rb,
lib/fmod/effects/flange.rb,
lib/fmod/effects/return.rb,
lib/fmod/channel_control.rb,
lib/fmod/core/init_flags.rb,
lib/fmod/core/sound_type.rb,
lib/fmod/core/structures.rb,
lib/fmod/effects/it_echo.rb,
lib/fmod/effects/limiter.rb,
lib/fmod/effects/tremolo.rb,
lib/fmod/core/file_system.rb,
lib/fmod/core/filter_type.rb,
lib/fmod/core/output_type.rb,
lib/fmod/core/window_type.rb,
lib/fmod/effects/low_pass.rb,
lib/fmod/effects/param_eq.rb,
lib/fmod/effects/three_eq.rb,
lib/fmod/core/channel_mask.rb,
lib/fmod/core/reverb_index.rb,
lib/fmod/core/sound_format.rb,
lib/fmod/core/speaker_mode.rb,
lib/fmod/effects/high_pass.rb,
lib/fmod/effects/normalize.rb,
lib/fmod/core/sound_ex_info.rb,
lib/fmod/core/speaker_index.rb,
lib/fmod/core/spectrum_data.rb,
lib/fmod/core/tag_data_type.rb,
lib/fmod/effects/compressor.rb,
lib/fmod/effects/distortion.rb,
lib/fmod/effects/it_lowpass.rb,
lib/fmod/effects/object_pan.rb,
lib/fmod/effects/oscillator.rb,
lib/fmod/effects/sfx_reverb.rb,
lib/fmod/effects/vst_plugin.rb,
lib/fmod/core/parameter_info.rb,
lib/fmod/core/parameter_type.rb,
lib/fmod/effects/channel_mix.rb,
lib/fmod/effects/pitch_shift.rb,
lib/fmod/effects/transceiver.rb,
lib/fmod/core/dsp_description.rb,
lib/fmod/effects/multiband_eq.rb,
lib/fmod/core/bool_description.rb,
lib/fmod/core/data_description.rb,
lib/fmod/effects/ladspa_plugin.rb,
lib/fmod/effects/winamp_plugin.rb,
lib/fmod/core/advanced_settings.rb,
lib/fmod/core/float_description.rb,
lib/fmod/effects/loudness_meter.rb,
lib/fmod/effects/low_pass_simple.rb,
lib/fmod/core/integer_description.rb,
lib/fmod/effects/high_pass_simple.rb,
lib/fmod/core/sound_group_behavior.rb,
lib/fmod/effects/envelope_follower.rb,
lib/fmod/effects/convolution_reverb.rb

Overview

Top-level namespace containing the entirety of the FMOD API.

Author:

  • Eric “ForeverZer0” Freed

Defined Under Namespace

Modules: Core, Effects Classes: Channel, ChannelControl, ChannelGroup, Dsp, DspConnection, Error, Geometry, Handle, Reverb3D, Sound, SoundGroup, System

Constant Summary collapse

NULL =

Null-pointer (address of 0)

Pointer.new(0).freeze
WAVE_FORMAT_VERSION =

Version number of the wave format codec.

Use this for binary compatibility and for future expansion.

3
SUPPORTED_EXTENSIONS =

Array of extensions for supported formats.

Additional formats may be supported, or added via plug-ins.

%w(.aiff .asf .asx .dls .flac .fsb .it .m3u .midi .mod .mp2 .mp3 .ogg .pls .s3m .vag .wav .wax .wma .xm .xma)
MAX_CHANNEL_WIDTH =

The maximum number of channels per frame of audio supported by audio files, buffers, connections and DSPs.

32
MAX_LISTENERS =

The maximum number of listeners supported.

8
MAX_SYSTEMS =

The maximum number of System objects allowed.

8
MAX_REVERB =

The maximum number of global/physical reverb instances.

Each instance of a physical reverb is an instance of a {Effects::SfxReverb } DSP in the mix graph. This is unrelated to the number of possible Reverb3D objects, which is unlimited.

4
PORT_INDEX_NONE =

Null value for a port index. Use when a port index is not required.

0xFFFFFFFFFFFFFFFF
VERSION =

The FMOD gem version.

"0.9.6"

Class Method Summary collapse

Class Method Details

.import_symbols(library) ⇒ void

Note:

This function is called automatically, not to be called by the user.

This method returns an undefined value.

Imports the FMOD functions from the loaded library.



502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/fmod.rb', line 502

def self.import_symbols(library)
  @functions = {}
  @function_signatures.each_pair do |sym, signature|
    name = "FMOD_#{sym}"
    begin
      @functions[sym] = Function.new(library[name], signature, TYPE_INT)
    rescue Fiddle::DLError
      warn("Failed to import #{name}.")
    end
  end
  const_set(:ABI, @functions.values.sample.abi)
end

.invoke(function, *args) ⇒ void

This method returns an undefined value.

Invokes the specified native function.

Parameters:

  • function (Symbol) —

    Symbol name of an FMOD function, without the the leading “FMOD_” prefix.

Raises:

  • (Error) —

    if the result code returned by FMOD is not 0.

See Also:



439
440
441
442
 
# File 'lib/fmod.rb', line 439

def self.invoke(function, *args)
  result = @functions[function].call(*args)
  raise Error, result unless result.zero?
end

.invoke_protect(function, *args) ⇒ Integer

Invokes the specified native function.

The same as invoke, but returns the result code instead of raising an

exception.

Parameters:

  • function (Symbol) —

    Symbol name of an FMOD function, without the the leading “FMOD_” prefix.

Returns:

  • (Integer) —

    the result code.

See Also:

  • Result


454
455
456
 
# File 'lib/fmod.rb', line 454

def self.invoke_protect(function, *args)
  @functions[function].call(*args)
end

.load_library(library = nil, directory = nil) ⇒ true

Note:

This must be called before ANY other function is called.

Loads the native FMOD library.

Parameters:

  • library (String) (defaults to: nil) —

    The name of the library to load. If omitted, the default platform-specific library name will be used.

  • directory (String) (defaults to: nil) —

    The directory where the library will be loaded from. By default this will be the “./ext” folder relative to the gem installation folder.

Returns:

  • (true) —

    if no errors occurred, otherwise exception will be raised.



470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/fmod.rb', line 470

def self.load_library(library = nil, directory = nil)
  if library.nil?
    library =  case platform
    when :WINDOWS then SIZEOF_INTPTR_T == 4 ? 'fmod.dll' : 'fmod64.dll'
    when :MACOSX then 'libfmod.dylib'
    when :LINUX then 'libfmod.so'
    else 'fmod'  # Will probably fail...
    end
  end
  path = File.expand_path(File.join(directory || Dir.getwd, library))
  lib = Fiddle.dlopen(path)
  import_symbols(lib)
  true
end

.platform ⇒ Symbol

Returns a symbol representing the operating system. Will be either :WINDOWS, :MACOSX, or :LINUX.

Returns:

  • (Symbol) —

    a symbol representing the operating system. Will be either :WINDOWS, :MACOSX, or :LINUX.



487
488
489
490
491
492
493
494
 
# File 'lib/fmod.rb', line 487

def self.platform
  @platform ||= case RbConfig::CONFIG['host_os']
  when /mswin|msys|mingw|cygwin/ then :WINDOWS
  when /darwin/ then :MACOSX
  when /linux/ then :LINUX
  else raise RuntimeError, 'Unsupported operating system.'
  end
end

.type?(object, type, exception = true) ⇒ Boolean

Checks that the object is of the given type, optionally raising an exception if it is not.

Parameters:

  • object (Object) —

    The object to check.

  • type (Class) —

    The class to ensure it either is or derives from.

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

    Flag indicating if an exception should be raised in the event the object is not the correct type.

Returns:

  • (Boolean) —

    true if object is of the specified type, otherwise false.

Raises:

  • (TypeError) —

    when the type does not match and the exception parameter is true.



527
528
529
530
531
 
# File 'lib/fmod.rb', line 527

def self.type?(object, type, exception = true)
  return true if object.is_a?(type)
  return false unless exception
  raise TypeError, "#{object} is not a #{type}."
end

.uint2version(version) ⇒ String

Converts an integer value to a version string representation.

Parameters:

  • version (Integer) —

    The version is a 32bit hexadecimal value formatted as 16:8:8, with the upper 16 bits being the major version, the middle 8bits being the minor version and the bottom 8 bits being the development version. For example a value of 00040106h is equal to 4.01.06.

Returns:

  • (String) —

    the version string.



559
560
561
562
563
 
# File 'lib/fmod.rb', line 559

def self.uint2version(version)
  version = version.unpack1('L') if version.is_a?(String)
  vs = "%08X" % version
  "#{vs[0, 4].to_i}.#{vs[4, 2].to_i}.#{vs[6, 2].to_i}"
end

.valid_range?(index, min, max, exception = true) ⇒ Boolean

Checks whether the specified index falls within the given range, optionally

raises an exception if it does not.

Parameters:

  • index (Integer) —

    The value to check.

  • min (Integer) —

    The minimum valid value.

  • max (Integer) —

    The maximum valid value.

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

    Flag indicating if an exception should be raised in the event the value is not within the specified range.

Returns:

  • (Boolean) —

    true if object is within specified range, otherwise false.

Raises:

  • (RangeError) —

    when the value is out of range and the exception parameter is true.



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

def self.valid_range?(index, min, max, exception = true)
  return true if index.between?(min, max)
  return false unless exception
  raise RangeError, "#{index} outside of valid range (#{min}..#{max})."
end