Class: FMOD::System

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

Overview

The primary central class of FMOD. This class acts as a factory for creation of other core FMOD objects, and a centralized control interface. All core FMOD objects belong to a System object.

Defined Under Namespace

Classes: CpuUsage, DspBuffer, FileUsage, Plugin, RamUsage, SoftwareFormat, Speaker, StreamBuffer

Recording collapse

Sound Card Drivers collapse

3D Sound collapse

Plugin Support collapse

Network collapse

Instance Attribute Summary collapse

Attributes inherited from Handle

#user_data

Speaker Positioning collapse

Object Creation collapse

System Resources collapse

Recording collapse

Sound Card Drivers collapse

3D Sound collapse

Plugin Support collapse

Instance Method Summary collapse

Methods inherited from Handle

#int_ptr, #release, #to_s

Constructor Details

#initialize(address) ⇒ System

Returns a new instance of System.

Parameters:

  • address (Pointer, Integer, String) —

    The address of a native FMOD pointer.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/fmod/system.rb', line 94

def initialize(address)
  super
  @rolloff_callbacks = []
  sig = [TYPE_VOIDP, TYPE_FLOAT]
  # noinspection RubyResolve
  abi = FMOD::ABI
  cb = Closure::BlockCaller.new(TYPE_FLOAT, sig, abi) do |channel, distance|
    unless @rolloff_callbacks.empty?
      chan = Channel.new(channel)
      @rolloff_callbacks.each { |proc| proc.call(chan, distance) }
    end
    distance
  end
  FMOD.invoke(:System_Set3DRolloffCallback, self, cb)
end

Instance Attribute Details

#current_driver ⇒ Integer

Returns the currently selected driver number. 0 represents the primary or default driver.

Returns:

  • (Integer) —

    the currently selected driver number. 0 represents the primary or default driver.



592
 
# File 'lib/fmod/system.rb', line 592

integer_reader(:current_driver, :System_GetDriver)

#distance_factor ⇒ Float

The FMOD 3D engine relative distance factor, compared to 1.0 meters.

Another way to put it is that it equates to “how many units per meter does your engine have”. For example, if you are using feet then “scale” would equal 3.28.

Returns:

  • (Float) —

    the relative distance factor.



667
668
669
670
671
 
# File 'lib/fmod/system.rb', line 667

def distance_factor
  factor = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:System_Get3DSettings, self, nil, factor, nil)
  factor.unpack1('f')
end

#doppler_scale ⇒ Float

The general scaling factor for how much the pitch varies due to doppler shifting in 3D sound.

Doppler is the pitch bending effect when a sound comes towards the listener or moves away from it, much like the effect you hear when a train goes past you with its horn sounding. With “doppler scale” you can exaggerate or diminish the effect. FMOD’s effective speed of sound at a doppler factor of 1.0 is 340 m/s.

Returns:

  • (Float) —

    the scaling factor.



646
647
648
649
650
 
# File 'lib/fmod/system.rb', line 646

def doppler_scale
  scale = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:System_Get3DSettings, self, scale, nil, nil)
  scale.unpack1('f')
end

#driver_count ⇒ Integer (readonly)

Returns the number of sound-card devices on the machine, specific to the output mode set with #output.

Returns:

  • (Integer) —

    the number of sound-card devices on the machine, specific to the output mode set with #output.



586
 
# File 'lib/fmod/system.rb', line 586

integer_reader(:driver_count, :System_GetNumDrivers)

#drivers ⇒ Array<Driver> (readonly)

Returns the array of available drivers.

Returns:

  • (Array<Driver>) —

    the array of available drivers.



625
626
627
 
# File 'lib/fmod/system.rb', line 625

def drivers
  (0...driver_count).map { |id| driver_info(id) }
end

#listeners ⇒ Integer

The number of 3D “listeners” in the 3D sound scene. This is useful mainly for split-screen game purposes.

If the number of listeners is set to more than 1, then panning and doppler are turned off. All sound effects will be mono. FMOD uses a “closest sound to the listener” method to determine what should be heard in this case.

Returns:

  • (Integer) 


788
 
# File 'lib/fmod/system.rb', line 788

integer_reader(:listeners, :System_Get3DNumListeners)

#network_proxy ⇒ String

Returns proxy server to use for internet connections.

Returns:

  • (String) —

    proxy server to use for internet connections.



1010
1011
1012
1013
1014
1015
 
# File 'lib/fmod/system.rb', line 1010

def network_proxy
  buffer = "\0" * 512
  FMOD.invoke(:System_GetNetworkProxy, self, buffer, 512)
  # noinspection RubyResolve
  buffer.delete("\0").force_encoding(Encoding::UTF_8)
end

#network_timeout ⇒ Integer

Returns the timeout, in milliseconds, for network streams.

Returns:

  • (Integer) —

    the timeout, in milliseconds, for network streams.



1024
 
# File 'lib/fmod/system.rb', line 1024

integer_reader(:network_timeout, :System_GetNetworkTimeout)

#output ⇒ Integer

The output mode for the platform. This is for selecting different OS specific APIs which might have different features.

Changing this is only necessary if you want to specifically switch away from the default output mode for the operating system. The most optimal mode is selected by default for the operating system.

Returns:

  • (Integer) —

    the output mode for the platform.

See Also:

  • OutputMode


579
 
# File 'lib/fmod/system.rb', line 579

integer_reader(:output, :System_GetOutput)

#output_handle ⇒ Pointer

Retrieves a pointer to the system level output device module. This means a pointer to a DirectX “LPDIRECTSOUND”, or a WINMM handle, or with something like with Core::OutputType::NO_SOUND output, the handle will be NULL.

Returns:

  • (Pointer) —

    the handle to the output mode’s native hardware API object.



617
618
619
620
 
# File 'lib/fmod/system.rb', line 617

def output_handle
  FMOD.invoke(:System_GetOutputHandle, self, handle = int_ptr)
  Pointer.new(handle.unpack1('J'))
end

#plugin_output ⇒ Integer

Returns the currently selected output as an ID in the list of output plugins.

Returns:

  • (Integer) —

    the currently selected output as an ID in the list of output plugins.



958
 
# File 'lib/fmod/system.rb', line 958

integer_reader(:plugin_output, :System_GetOutputByPlugin)

#record_drivers ⇒ Array<Driver> (readonly)

Returns the array of available record drivers.

Returns:

  • (Array<Driver>) —

    the array of available record drivers.



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

def record_drivers(connected = true)
  (0...record_driver_count(connected)).map { |i| record_driver(i) }
end

#rolloff_scale ⇒ Float

The global attenuation rolloff factor for Core::Mode::INVERSE_ROLLOFF_3D based sounds only (which is the default).

Volume for a sound set to Core::Mode::INVERSE_ROLLOFF_3D will scale at minimum distance / distance. This gives an inverse attenuation of volume as the source gets further away (or closer). Setting this value makes the sound drop off faster or slower. The higher the value, the faster volume will attenuate, and conversely the lower the value, the slower it will attenuate. For example a rolloff factor of 1 will simulate the real world, where as a value of 2 will make sounds attenuate 2 times quicker.

Returns:

  • (Float) —

    the global rolloff factor.



693
694
695
696
697
 
# File 'lib/fmod/system.rb', line 693

def rolloff_scale
  scale = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:System_Get3DSettings, self, nil, nil, scale)
  scale.unpack1('f')
end

#software_channels ⇒ Integer

Returns the maximum number of software mixed channels possible.

Returns:

  • (Integer) —

    the maximum number of software mixed channels possible.



1397
 
# File 'lib/fmod/system.rb', line 1397

integer_reader(:software_channels, :System_GetSoftwareChannels)

#software_format ⇒ SoftwareFormat

The output format for the software mixer.

If loading Studio banks, this must be set with speaker mode corresponding to the project’s output format if there is a possibility of the output audio device not matching the project’s format. Any differences between the project format and the system’s speaker mode will cause the mix to sound wrong.

If not loading Studio banks, do not set this unless you explicitly want to change a setting from the default. FMOD will default to the speaker mode and sample rate that the OS / output prefers.

Returns:



1182
1183
1184
1185
1186
1187
 
# File 'lib/fmod/system.rb', line 1182

def software_format
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT]
  FMOD.invoke(:System_GetSoftwareFormat, self, *args)
  args.map! { |arg| arg.unpack1('l') }
  SoftwareFormat.new(*args)
end

#stream_buffer ⇒ DspBuffer

Returns the internal buffer-size for DSP units.

Returns:

  • (DspBuffer) —

    the internal buffer-size for DSP units.



1403
1404
1405
1406
1407
 
# File 'lib/fmod/system.rb', line 1403

def stream_buffer
  size, type = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetStreamBufferSize, self, size, type)
  StreamBuffer.new(size.unpack1('L'), type.unpack1('l'))
end

#version ⇒ String (readonly)

Returns the current version of FMOD being used.

Returns:

  • (String) —

    the current version of FMOD being used.



1230
1231
1232
1233
 
# File 'lib/fmod/system.rb', line 1230

def version
  FMOD.invoke(:System_GetVersion, self, version = "\0" * SIZEOF_INT)
  FMOD.uint2version(version)
end

#world_size ⇒ Float

The maximum world size for the geometry engine for performance / precision reasons

This setting should be done first before creating any geometry. It can be done any time afterwards but may be slow in this case.

Objects or polygons outside the range of this value will not be handled efficiently. Conversely, if this value is excessively large, the structure may loose precision and efficiency may drop.

Returns:

  • (Float) —

    the maximum world size for the geometry engine.



804
 
# File 'lib/fmod/system.rb', line 804

float_reader(:world_size, :System_GetGeometrySettings)

Class Method Details

.create(**options) ⇒ System

Note:

This must be called to create an FMOD::System object before you can do anything else.

FMOD::System creation function. Use this function to create one, or multiple instances of system objects.

Parameters:

  • options (Hash) —

    Options hash.

Options Hash (**options):

  • :max_channels (Integer) — default: 32 —

    The maximum number of channels to be used in FMOD. They are also called “virtual channels” as you can play as many of these as you want, even if you only have a small number of software voices.

  • :flags (Integer) — default: InitFlags::NORMAL —

    See Core::InitFlags. This can be a selection of flags bitwise OR’ed together to change the behavior of FMOD at initialization time.

  • :driver_data (Pointer|String) — default: FMOD::NULL —

    Driver specific data that can be passed to the output plugin. For example the filename for the wav writer plugin.

Returns:



237
238
239
240
241
242
243
244
245
 
# File 'lib/fmod/system.rb', line 237

def self.create(**options)
  max = [options[:max_channels] || 32, 4093].min
  flags = options[:flags] || InitFlags::NORMAL
  driver = options[:driver_data] || FMOD::NULL
  FMOD.invoke(:System_Create, address = "\0" * SIZEOF_INTPTR_T)
  system = new(address)
  FMOD.invoke(:System_Init, system, max, flags, driver)
  system
end

Instance Method Details

#[](index) ⇒ Reverb Also known as: get_reverb

Retrieves the current reverb environment for the specified reverb instance.

Parameters:

  • index (Integer) —

    Index of the particular reverb instance to target, from 0 to MAX_REVERB inclusive.

Returns:

  • (Reverb) —

    The specified Reverb instance.



1370
1371
1372
1373
1374
 
# File 'lib/fmod/system.rb', line 1370

def [](index)
  reverb = Reverb.new
  FMOD.invoke(:System_GetReverbProperties, self, index, reverb)
  reverb
end

#[]=(index, reverb) ⇒ Reverb Also known as: set_reverb

Sets parameters for the global reverb environment.

Parameters:

  • index (Integer) —

    Index of the particular reverb instance to target, from 0 to MAX_REVERB inclusive.

  • reverb (Reverb) —

    A structure which defines the attributes for the reverb. Passing NULL or nil to this function will delete the physical reverb.

Returns:

  • (Reverb) —

    the specified reverb.



1386
1387
1388
1389
 
# File 'lib/fmod/system.rb', line 1386

def []=(index, reverb)
  FMOD.type?(reverb, Reverb)
  FMOD.invoke(:System_SetReverbProperties, self, index, reverb)
end

#attach_to_port(group, port_type, port_index, pass_thru) ⇒ void

This method returns an undefined value.

Route the signal from a channel group into a separate audio port on the output driver.

Note that an FMOD port is a hardware specific reference, to hardware devices that exist on only certain platforms (like a console headset, or dedicated hardware music channel for example). It is not supported on all platforms.

Parameters:

  • group (ChannelGroup) —

    Channel group to route away to the new port.

  • port_type (Integer) —

    Output driver specific audio port type. See extra platform specific header (if it exists) for port numbers

  • port_index (Integer) —

    Output driver specific index of the audio port. Use PORT_INDEX_NONE if this is not required.

  • pass_thru (Boolean) —

    If true the signal will continue to be passed through to the main mix, if false the signal will be entirely to the designated port.



1048
1049
1050
1051
1052
 
# File 'lib/fmod/system.rb', line 1048

def attach_to_port(group, port_type, port_index, pass_thru)
  FMOD.type?(group, ChannelGroup)
  FMOD.invoke(:System_AttachChannelGroupToPort, self, port_type,
              port_index, group, pass_thru.to_i)
end

#channel(id) ⇒ Channel

Retrieves a handle to a channel by ID.

Parameters:

  • id (Integer) —

    Index in the FMOD channel pool. Specify a channel number from 0 to the maximum number of channels specified in create minus 1.

Returns:

  • (Channel) —

    the requested channel.



1151
1152
1153
1154
 
# File 'lib/fmod/system.rb', line 1151

def channel(id)
  FMOD.invoke(:System_GetChannel, self, id, handle = int_ptr)
  Channel.new(handle)
end

#close ⇒ void

This method returns an undefined value.

Closes the FMOD::System object without freeing the object’s memory, so the system handle will still be valid.

Closing the output renders objects created with this system object invalid. Make sure any sounds, channel groups, geometry and DSP objects are released before closing the system object.



1223
1224
1225
 
# File 'lib/fmod/system.rb', line 1223

def close
  FMOD.invoke(:System_Close, self)
end

#cpu_usage ⇒ CpuUsage

Retrieves in percent of CPU time - the amount of CPU usage that FMOD is taking for streaming/mixing and #update combined.

Returns:

  • (CpuUsage) —

    the current CPU resource usage at the time of the call.



428
429
430
431
432
433
 
# File 'lib/fmod/system.rb', line 428

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

#create_channel_group(name = nil) ⇒ ChannelGroup

Creates a ChannelGroup object. These objects can be used to assign channels to for group channel settings, such as volume.

Channel groups are also used for sub-mixing. Any channels that are assigned to a channel group get sub-mixed into that channel group’s DSP.

Parameters:

  • name (String, nil) (defaults to: nil) —

    Optional label to give to the channel group for identification purposes.

Returns:



398
399
400
401
 
# File 'lib/fmod/system.rb', line 398

def create_channel_group(name = nil)
  FMOD.invoke(:System_CreateChannelGroup, self, name, group = int_ptr)
  ChannelGroup.new(group)
end

#create_dsp(type) ⇒ Dsp

Creates an FMOD defined built in DSP unit object to be inserted into a DSP network, for the purposes of sound filtering or sound generation.

This function is used to create special effects that come built into FMOD.

Parameters:

  • type (Integer, Class) —

    A pre-defined DSP effect or sound generator described by in Core::DspType, or a Class found within the Effects module.

Returns:

  • (Dsp) —

    the created DSP.



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/fmod/system.rb', line 299

def create_dsp(type)
  unless FMOD.type?(type, Integer, false)
    unless FMOD.type?(type, Class) && type < Dsp
      raise TypeError, "#{type} must either be or inherit from #{Dsp}."
    end
  end
  if type.is_a?(Integer)
    klass = Dsp.type_map(type)
  else type.is_a?(Class)
  klass = type
  type = Dsp.type_map(type)
  end
  dsp = int_ptr
  FMOD.invoke(:System_CreateDSPByType, self, type, dsp)
  klass.new(dsp)
end

#create_geometry(max_polygons, max_vertices) ⇒ Object

Geometry creation function. This function will create a base geometry object which can then have polygons added to it.

Polygons can be added to a geometry object using Geometry#add_polygon.

A geometry object stores its list of polygons in a structure optimized for quick line intersection testing and efficient insertion and updating. The structure works best with regularly shaped polygons with minimal overlap. Many overlapping polygons, or clusters of long thin polygons may not be handled efficiently. Axis aligned polygons are handled most efficiently.

The same type of structure is used to optimize line intersection testing with multiple geometry objects.

It is important to set the value of max world-size to an appropriate value using #world_size. Objects or polygons outside the range of max world-size will not be handled efficiently. Conversely, if max world-size is excessively large, the structure may lose precision and efficiency may drop.

Parameters:

  • max_polygons (Integer) —

    Maximum number of polygons within this object.

  • max_vertices (Integer) —

    Maximum number of vertices within this object.



353
354
355
356
357
 
# File 'lib/fmod/system.rb', line 353

def create_geometry(max_polygons, max_vertices)
  geometry = int_ptr
  FMOD.invoke(:System_CreateGeometry, self, max_polygons, max_vertices, geometry)
  Geometry.new(geometry)
end

#create_reverb ⇒ Reverb3D

Creates a “virtual reverb” object. This object reacts to 3D location and morphs the reverb environment based on how close it is to the reverb object’s center.

Multiple reverb objects can be created to achieve a multi-reverb environment. 1 Physical reverb object is used for all 3D reverb objects (slot 0 by default).

The 3D reverb object is a sphere having 3D attributes (position, minimum distance, maximum distance) and reverb properties. The properties and 3D attributes of all reverb objects collectively determine, along with the listener’s position, the settings of and input gains into a single 3D reverb DSP. When the listener is within the sphere of effect of one or more 3D reverbs, the listener’s 3D reverb properties are a weighted combination of such 3D reverbs. When the listener is outside all of the reverbs, no reverb is applied.

Creating multiple reverb objects does not impact performance. These are “virtual reverbs”. There will still be only 1 physical reverb DSP running that just morphs between the different virtual reverbs.

Returns:



382
383
384
385
386
 
# File 'lib/fmod/system.rb', line 382

def create_reverb
  reverb = int_ptr
  FMOD.invoke(:System_CreateReverb3D, self, reverb)
  Reverb3D.new(reverb)
end

#create_sound(source, **options) ⇒ Sound

Loads a sound into memory, or opens it for streaming.

Parameters:

Options Hash (**options):

  • :mode (Integer) — default: Mode::DEFAULT —

    Behavior modifier for opening the sound. See Core::Mode for explanation of flags.

  • :extra (SoundExInfo) — default: FMOD::NULL —

    Extra data which lets the user provide extended information while playing the sound.

Returns:

  • (Sound) —

    the created sound.



259
260
261
262
263
264
265
 
# File 'lib/fmod/system.rb', line 259

def create_sound(source, **options)
  mode = options[:mode] || Mode::DEFAULT
  extra = options[:extra] || FMOD::NULL
  sound = int_ptr
  FMOD.invoke(:System_CreateSound, self, source, mode, extra, sound)
  Sound.new(sound)
end

#create_sound_group(name) ⇒ SoundGroup

Creates a sound group, which can store handles to multiple FMOD::Sound objects.

Parameters:

  • name (String) —

    Name of sound group.

Returns:



321
322
323
324
325
326
 
# File 'lib/fmod/system.rb', line 321

def create_sound_group(name)
  utf8 = name.encode('UTF-8')
  group = int_ptr
  FMOD.invoke(:System_CreateSoundGroup, self, utf8, group)
  SoundGroup.new(group)
end

#create_stream(source, **options) ⇒ Sound

Opens a sound for streaming. This function is a helper function that is the same as #create_sound but has the Core::Mode::CREATE_STREAM flag added internally.

Parameters:

Options Hash (**options):

  • :mode (Integer) — default: Mode::DEFAULT —

    Behavior modifier for opening the sound. See Core::Mode for explanation of flags.

  • :extra (SoundExInfo) — default: FMOD::NULL —

    Extra data which lets the user provide extended information while playing the sound.

Returns:

  • (Sound) —

    the created sound.



281
282
283
284
285
286
287
 
# File 'lib/fmod/system.rb', line 281

def create_stream(source, **options)
  mode = options[:mode] || Mode::DEFAULT
  extra = options[:extra] || FMOD::NULL
  sound = int_ptr
  FMOD.invoke(:System_CreateSound, self, source, mode, extra, sound)
  Sound.new(sound)
end

#default_matrix(source, target) ⇒ <Array<Array<Float>>] the mix matrix.

Note:

source and target must not exceed MAX_CHANNEL_WIDTH.

Generates a “default” matrix based on the specified source and target speaker mode.

Parameters:

  • source (Integer) —

    The speaker mode being converted from.

  • target (Integer) —

    The speaker mode being converted to.

Returns:

  • (<Array<Array<Float>>] the mix matrix.) —

    <Array<Array<Float>>] the mix matrix.

Raises:

  • (RangeError)

See Also:



137
138
139
140
141
142
143
144
145
 
# File 'lib/fmod/system.rb', line 137

def default_matrix(source, target)
  max = FMOD::MAX_CHANNEL_WIDTH
  raise RangeError, "source channels cannot exceed #{max}" if source > max
  raise RangeError, "target channels cannot exceed #{max}" if target > max
  return [] if source < 1 || target < 1
  buffer = "\0" * (SIZEOF_FLOAT * source * target)
  FMOD.invoke(:System_GetDefaultMixMatrix, self, source, target, buffer, 0)
  buffer.unpack('f*').each_slice(source).to_a
end

#detach_from_port(group) ⇒ void

This method returns an undefined value.

Disconnect a channel group from a port and route audio back to the default port of the output driver.

Parameters:

  • group (ChannelGroup) —

    Channel group to route away back to the default audio port.



1062
1063
1064
1065
 
# File 'lib/fmod/system.rb', line 1062

def detach_from_port(group)
  FMOD.type?(group, ChannelGroup)
  FMOD.invoke(:System_DetachChannelGroupFromPort, self, group)
end

#driver_info(id) ⇒ Driver

Retrieves identification information about a sound device specified by its index, and specific to the output mode set with #output.

Parameters:

  • id (Integer) —

    Index of the sound driver device. The total number of devices can be found with #driver_count.

Returns:

  • (Driver) —

    the driver information.



603
604
605
606
607
 
# File 'lib/fmod/system.rb', line 603

def driver_info(id)
  args = [id, "\0" * 512, 512, Guid.new] + (0...3).map { "\0" * SIZEOF_INT }
  FMOD.invoke(:System_GetDriverInfo, self, *args)
  Driver.send(:new, args)
end

#dsp_buffer ⇒ DspBuffer

Returns the internal buffer-size for DSP units.

Returns:

  • (DspBuffer) —

    the internal buffer-size for DSP units.



1418
1419
1420
1421
1422
 
# File 'lib/fmod/system.rb', line 1418

def dsp_buffer
  size, count = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetDSPBufferSize, self, size, count)
  DspBuffer.new(size.unpack1('L'), count.unpack1('l'))
end

#dsp_buffer=(buffer) ⇒ Object

Raises:

  • (RangeError) 


1424
1425
1426
1427
1428
 
# File 'lib/fmod/system.rb', line 1424

def dsp_buffer=(buffer)
  FMOD.type?(buffer, DspBuffer)
  raise RangeError, "size must be greater than 0" unless buffer.size > 0
  FMOD.invoke(:System_SetDSPBufferSize, self, *buffer.values)
end

#each_dsp {|dsp| ... } ⇒ self #each_dsp ⇒ Enumerator

Helper method to create and enumerate each type of internal DSP unit.

Overloads:

  • #each_dsp {|dsp| ... } ⇒ self

    When called with a block, yields each DSP type in turn before returning self.

    Yields:

    • (dsp) —

      Yields a DSP unit to the block.

    Yield Parameters:

    • dsp (Dsp) —

      The current enumerated DSP unit.

    Returns:

    • (self)
  • #each_dsp ⇒ Enumerator

    When called without a block, returns an enumerator for the DSP units.

    Returns:

    • (Enumerator) 


1122
1123
1124
1125
1126
1127
1128
1129
 
# File 'lib/fmod/system.rb', line 1122

def each_dsp
  return to_enum(:each_dsp) unless block_given?
  FMOD::DspType.constants(false).each do |const|
    type = DspType.const_get(const)
    yield create_dsp(type) rescue next
  end
  self
end

#each_plugin(plugin_type = :all) {|plugin| ... } ⇒ self #each_plugin(plugin_type = :all) ⇒ Enumerator

Enumerates the loaded plugins, optionally specifying the type of plugins to loop through.

Overloads:

  • #each_plugin(plugin_type = :all) {|plugin| ... } ⇒ self

    When a block is passed, yields each plugin to the block in turn before returning self.

    Yields:

    • (plugin) —

      Yields a plugin to the block.

    Yield Parameters:

    • plugin (Plugin) —

      The currently enumerated plugin.

    Returns:

    • (self)
  • #each_plugin(plugin_type = :all) ⇒ Enumerator

    When no block is given, returns an enumerator for the plugins.

    Returns:

    • (Enumerator)

Parameters:

  • plugin_type (Symbol) (defaults to: :all) —

    Specifies the type of plugin(s) to enumerate.

    • :output The plugin type is an output module. FMOD mixed audio will play through one of these devices

    • :codec The plugin type is a file format codec. FMOD will use these codecs to load file formats for playback.

    • :dsp The plugin type is a DSP unit. FMOD will use these plugins as part of its DSP network to apply effects to output or generate.rb sound in realtime.



991
992
993
994
995
996
997
998
999
1000
1001
 
# File 'lib/fmod/system.rb', line 991

def each_plugin(plugin_type = :all)
  return to_enum(:each_plugin) unless block_given?
  types = plugin_type == :all ? %i[output codec dsp] : [plugin_type]
  types.each do |type|
    (0...plugin_count(type)).each do |index|
      handle = plugin(type, index)
      yield plugin_info(handle)
    end
  end
  self
end

#each_speaker {|speaker| ... } ⇒ self #each_speaker ⇒ Enumerator

Overloads:

  • #each_speaker {|speaker| ... } ⇒ self

    When called with a block, yields each speaker in turn before returning self.

    Yields:

    • (speaker) —

      Yields a speaker to the block.

    Yield Parameters:

    • speaker (Speaker) —

      The current enumerated speaker.

    Returns:

    • (self)
  • #each_speaker ⇒ Enumerator

    When called without a block, returns an enumerator for the speakers.

    Returns:

    • (Enumerator) 


206
207
208
209
210
211
212
213
 
# File 'lib/fmod/system.rb', line 206

def each_speaker
  return to_enum(:each_speaker) unless block_given?
  SpeakerIndex.constants(false).each do |const|
    index = SpeakerIndex.const_get(const)
    yield speaker(index) rescue next
  end
  self
end

#file_usage ⇒ FileUsage

Retrieves information about file reads by FMOD.

The values returned are running totals that never reset.

Returns:

  • (FileUsage) —

    the current total of file read resources used by FMOD at the time of the call.



456
457
458
459
460
461
 
# File 'lib/fmod/system.rb', line 456

def file_usage
  args = ["\0" * SIZEOF_LONG_LONG, "\0" * SIZEOF_LONG_LONG,
    "\0" * SIZEOF_LONG_LONG]
  FMOD.invoke(:System_GetFileUsage, self, *args)
  FileUsage.new(*args.map { |arg| arg.unpack1('q') })
end

#geometry_occlusion(listener, source) ⇒ Array(Float, Float)

Calculates geometry occlusion between a listener and a sound source.

Parameters:

  • listener (Vector) —

    The listener position.

  • source (Vector) —

    The source position.

Returns:

  • (Array(Float, Float)) —

    the occlusion values as an array, the first element being the direct occlusion value, and the second element being the reverb occlusion value.



767
768
769
770
771
772
773
 
# File 'lib/fmod/system.rb', line 767

def geometry_occlusion(listener, source)
  FMOD.type?(listener, Vector)
  FMOD.type?(source, Vector)
  args = ["\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT]
  FMOD.invoke(:System_GetGeometryOcclusion, self, listener, source, *args)
  args.join.unpack('ff')
end

#get_listener_attributes(id) ⇒ ListenerAttributes

Returns the position, velocity and orientation of the specified 3D sound listener.

Parameters:

  • id (Integer) —

    Listener ID in a multi-listener environment. Specify 0 if there is only 1 listener.

Returns:

  • (ListenerAttributes) —

    the position, velocity and orientation of the specified 3D sound listener.

Since:

  • 0.9.5



712
713
714
715
716
 
# File 'lib/fmod/system.rb', line 712

def get_listener_attributes(id)
  args = (0..3).map { FMOD::Core::Vector.new(nil) }
  FMOD.invoke(:System_Get3DListenerAttributes, self, id, *args)
  ListenerAttributes.new(*args)
end

#load_geometry(source, filename = true) ⇒ Geometry

Creates a Geometry object that was previously serialized with Geometry#save.

Parameters:

  • source (String) —

    Either a filename where object is saved, or a binary block of serialized data.

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

    true if source is a filename to be loaded, otherwise false and source will be handled as binary data.

Returns:

See Also:



412
413
414
415
416
417
 
# File 'lib/fmod/system.rb', line 412

def load_geometry(source, filename = true)
  source = IO.open(source, 'rb') { |io| io.read } if filename
  size = source.bytesize
  FMOD.invoke(:System_LoadGeometry, self, source, size, geometry = int_ptr)
  Geometry.new(geometry)
end

#load_plugin(filename, priority = 128) ⇒ Integer

Loads an FMOD plugin. This could be a DSP, file format or output plugin.

Parameters:

  • filename (String) —

    Filename of the plugin to be loaded.

  • priority (Integer) (defaults to: 128) —

    Codec plugins only, priority of the codec compared to other codecs, where 0 is the most important and higher numbers are less important.

Returns:

  • (Integer) —

    the handle to the plugin.



820
821
822
823
824
825
826
 
# File 'lib/fmod/system.rb', line 820

def load_plugin(filename, priority = 128)
  # noinspection RubyResolve
  path = filename.encode(Encoding::UTF_8)
  handle = "\0" * SIZEOF_INT
  FMOD.invoke(:System_LoadPlugin, self, path, handle, priority)
  handle.unpack1('L')
end

#lock_dsp ⇒ void #lock_dsp { ... } ⇒ void

This method returns an undefined value.

Mutual exclusion function to lock the FMOD DSP engine (which runs asynchronously in another thread), so that it will not execute. If the FMOD DSP engine is already executing, this function will block until it has completed.

The function may be used to synchronize DSP network operations carried out by the user.

An example of using this function may be for when the user wants to construct a DSP sub-network, without the DSP engine executing in the background while the sub-network is still under construction.

Once the user no longer needs the DSP engine locked, it must be unlocked with #unlock_dsp.

Note that the DSP engine should not be locked for a significant amount of time, otherwise inconsistency in the audio output may result. (audio skipping/stuttering).

Overloads:

  • #lock_dsp ⇒ void

    Locks the DSP engine, must unlock with #unlock_dsp.

  • #lock_dsp { ... } ⇒ void

    Yields:

    • Locks the DSP engine, and unlocks it when the block exits.



1092
1093
1094
1095
1096
1097
1098
 
# File 'lib/fmod/system.rb', line 1092

def lock_dsp
  FMOD.invoke(:System_LockDSP, self)
  if block_given?
    yield
    FMOD.invoke(:System_UnlockDSP, self)
  end
end

#master_channel_group ⇒ ChannelGroup

Retrieves the internal master channel group. This is the default channel group that all channels play on.

This channel group can be used to do things like set the master volume for all playing sounds. See the ChannelGroup API for more functionality.

Returns:



1201
1202
1203
1204
 
# File 'lib/fmod/system.rb', line 1201

def master_channel_group
  FMOD.invoke(:System_GetMasterChannelGroup, self, group = int_ptr)
  ChannelGroup.new(group)
end

#master_sound_group ⇒ Object

@@return [SoundGroup] the default sound group, where all sounds are placed when they are created.



1209
1210
1211
1212
 
# File 'lib/fmod/system.rb', line 1209

def master_sound_group
  FMOD.invoke(:System_GetMasterSoundGroup, self, group = int_ptr)
  SoundGroup.new(group)
end

#mixer_resume ⇒ void

This method returns an undefined value.

Resume mixer thread and reacquire access to audio hardware.

See Also:



1358
1359
1360
 
# File 'lib/fmod/system.rb', line 1358

def mixer_resume
  FMOD.invoke(:System_MixerResume, self)
end

#mixer_suspend { ... } ⇒ void #mixer_suspend ⇒ void

This method returns an undefined value.

Suspend mixer thread and relinquish usage of audio hardware while maintaining internal state.

Overloads:

  • #mixer_suspend { ... } ⇒ void

    When called with a block, automatically resumes the mixer when the block exits.

    Yields:

    • Yields control back to receiver.

  • #mixer_suspend ⇒ void

    When called without a block, user must call #mixer_resume.

See Also:



1346
1347
1348
1349
1350
1351
1352
 
# File 'lib/fmod/system.rb', line 1346

def mixer_suspend
  FMOD.invoke(:System_MixerSuspend, self)
  if block_given?
    yield
    FMOD.invoke(:System_MixerResume, self)
  end
end

#nested_plugin(handle, index) ⇒ Integer

Returns nested plugin definition for the given index.

For plugins consisting of a single definition, only index 0 is valid and the returned handle is the same as the handle passed in.

Parameters:

  • handle (Integer) —

    A handle to an existing plugin returned from #load_plugin.

  • index (Integer) —

    Index into the list of plugin definitions.

Returns:

  • (Integer) —

    the handle to the nested plugin.



913
914
915
916
917
 
# File 'lib/fmod/system.rb', line 913

def nested_plugin(handle, index)
  nested = "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetNestedPlugin, self, handle, index, nested)
  nested.unpack1('L')
end

#nested_plugin_count(handle) ⇒ Integer

Returns the number of plugins nested in the one plugin file.

Plugins normally have a single definition in them, in which case the count is always 1.

For plugins that have a list of definitions, this function returns the number of plugins that have been defined. #nested_plugin can be used to find each handle.

Parameters:

  • handle (Integer) —

    A handle to an existing plugin returned from #load_plugin.

Returns:

  • (Integer) —

    the number of nested plugins.



933
934
935
936
937
 
# File 'lib/fmod/system.rb', line 933

def nested_plugin_count(handle)
  count = "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetNumNestedPlugins, self, handle, count)
  count.unpack1('l')
end

#on_rolloff(proc = nil) {|index| ... } ⇒ void

This method returns an undefined value.

When FMOD wants to calculate 3D volume for a channel, this callback can be used to override the internal volume calculation based on distance.

Parameters:

  • proc (Proc) (defaults to: nil) —

    Proc to call. Optional, must give block if nil.

Yields:

  • (index) —

    The block to call when rolloff is calculated.

Raises:

  • (LocalJumpError) 


117
118
119
120
121
 
# File 'lib/fmod/system.rb', line 117

def on_rolloff(proc = nil, &block)
  cb = proc || block
  raise LocalJumpError, "No block given."  if cb.nil?
  @rolloff_callbacks << cb
end

#play_dsp(dsp, group = nil, paused = false) ⇒ 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.

A sound defined as Core::Mode::THREE_D will by default play at the position of the listener.

Channels are reference counted. If a channel is stolen by the FMOD priority system, then the handle to the stolen voice becomes invalid, and Channel based commands will not affect the new sound playing in its place. If all channels are currently full playing a sound, FMOD will steal a channel with the lowest priority sound. If more channels are playing than are currently available on the sound-card/sound device or software mixer, then FMOD will “virtualize” the channel. This type of channel is not heard, but it is updated as if it was playing. When its priority becomes high enough or another sound stops that was using a real hardware/software channel, it will start playing from where it should be. This technique saves CPU time (thousands of sounds can be played at once without actually being mixed or taking up resources), and also removes the need for the user to manage voices themselves. An example of virtual channel usage is a dungeon with 100 torches burning, all with a looping crackling sound, but with a sound-card that only supports 32 hardware voices. If the 3D positions and priorities for each torch are set correctly, FMOD will play all 100 sounds without any ‘out of channels’ errors, and swap the real voices in and out according to which torches are closest in 3D space. Priority for virtual channels can be changed in the sound’s defaults, or at runtime with Channel#priority.

Parameters:

  • dsp (Dsp) —

    The DSP to play.

  • 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).

  • paused (Boolean) (defaults to: false) —

    flag to specify whether to start the channel paused or not. Starting a channel paused allows the user to alter its attributes without it being audible, and un-pausing with ChannelControl.resume actually starts the sound.

Returns:

  • (Channel) —

    the newly playing channel.



1326
1327
1328
1329
1330
1331
 
# File 'lib/fmod/system.rb', line 1326

def play_dsp(dsp, group = nil, paused = false)
  FMOD.type?(dsp, Dsp)
  channel = int_ptr
  FMOD.invoke(:System_PlayDSP, self, dsp, group, paused.to_i, channel)
  Channel.new(channel)
end

#play_sound(sound, group = nil, paused = false) ⇒ 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.

A sound defined as Core::Mode::THREE_D will by default play at the position of the listener.

Channels are reference counted. If a channel is stolen by the FMOD priority system, then the handle to the stolen voice becomes invalid, and Channel based commands will not affect the new sound playing in its place. If all channels are currently full playing a sound, FMOD will steal a channel with the lowest priority sound. If more channels are playing than are currently available on the sound-card/sound device or software mixer, then FMOD will “virtualize” the channel. This type of channel is not heard, but it is updated as if it was playing. When its priority becomes high enough or another sound stops that was using a real hardware/software channel, it will start playing from where it should be. This technique saves CPU time (thousands of sounds can be played at once without actually being mixed or taking up resources), and also removes the need for the user to manage voices themselves. An example of virtual channel usage is a dungeon with 100 torches burning, all with a looping crackling sound, but with a sound-card that only supports 32 hardware voices. If the 3D positions and priorities for each torch are set correctly, FMOD will play all 100 sounds without any ‘out of channels’ errors, and swap the real voices in and out according to which torches are closest in 3D space. Priority for virtual channels can be changed in the sound’s defaults, or at runtime with Channel#priority.

Parameters:

  • sound (Sound) —

    The sound to play.

  • 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).

  • paused (Boolean) (defaults to: false) —

    flag to specify whether to start the channel paused or not. Starting a channel paused allows the user to alter its attributes without it being audible, and un-pausing with ChannelControl.resume actually starts the sound.

Returns:

  • (Channel) —

    the newly playing channel.



1277
1278
1279
1280
1281
1282
 
# File 'lib/fmod/system.rb', line 1277

def play_sound(sound, group = nil, paused = false)
  FMOD.type?(sound, Sound)
  channel = int_ptr
  FMOD.invoke(:System_PlaySound, self, sound, group, paused.to_i, channel)
  Channel.new(channel)
end

#playing_channels(total = true) ⇒ Integer

Retrieves the number of currently playing channels.

Parameters:

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

    true to return the number of playing channels (both real and virtual), false to return the number of playing non-virtual channels only.

Returns:

  • (Integer) —

    the number of playing channels.



1137
1138
1139
1140
1141
 
# File 'lib/fmod/system.rb', line 1137

def playing_channels(total = true)
  count, real = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetChannelsPlaying, self, count, real)
  (total ? count : real).unpack1('l')
end

#plugin(type, index) ⇒ Integer

Retrieves the handle of a plugin based on its type and relative index.

Parameters:

  • type (Symbol) —

    The type of plugin type.

    • :output The plugin type is an output module. FMOD mixed audio will play through one of these devices

    • :codec The plugin type is a file format codec. FMOD will use these codecs to load file formats for playback.

    • :dsp The plugin type is a DSP unit. FMOD will use these plugins as part of its DSP network to apply effects to output or generate.rb sound in realtime.

  • index (Integer) —

    The relative index for the type of plugin.

Returns:

  • (Integer) —

    the handle to the plugin.

Raises:

  • (ArgumentError) 


894
895
896
897
898
899
900
 
# File 'lib/fmod/system.rb', line 894

def plugin(type, index)
  handle = "\0" * SIZEOF_INT
  plugin_type = %i[output codec dsp].index(type)
  raise ArgumentError, "Invalid plugin type: #{type}." if plugin_type.nil?
  FMOD.invoke(:System_GetPluginHandle, self, plugin_type, index, handle)
  handle.unpack1('L')
end

#plugin_count(type = :all) ⇒ Integer

Retrieves the number of available plugins loaded into FMOD at the current time.

Parameters:

  • type (Symbol) (defaults to: :all) —

    Specifies the type of plugin(s) to enumerate.

    • :output The plugin type is an output module. FMOD mixed audio will play through one of these devices

    • :codec The plugin type is a file format codec. FMOD will use these codecs to load file formats for playback.

    • :dsp The plugin type is a DSP unit. FMOD will use these plugins as part of its DSP network to apply effects to output or generate.rb sound in realtime.

Returns:

  • (Integer) —

    the plugin count.



851
852
853
854
855
856
857
858
859
860
861
862
863
864
 
# File 'lib/fmod/system.rb', line 851

def plugin_count(type = :all)
  plugin_type = %i[output codec dsp].index(type)
  count = "\0" * SIZEOF_INT
  unless plugin_type.nil?
    FMOD.invoke(:System_GetNumPlugins, self, plugin_type, count)
    return count.unpack1('l')
  end
  total = 0
  (0..2).each do |i|
    FMOD.invoke(:System_GetNumPlugins, self, i, count)
    total += count.unpack1('l')
  end
  total
end

#plugin_dsp_info(handle) ⇒ DspDescription

Returns the description structure for a pre-existing DSP plugin.

Parameters:

  • handle (Integer) —

    Handle to a pre-existing DSP plugin.

Returns:

  • (DspDescription) —

    the description structure for a pre-existing DSP plugin.



965
966
967
968
 
# File 'lib/fmod/system.rb', line 965

def plugin_dsp_info(handle)
  FMOD.invoke(:System_GetDSPInfoByPlugin, self, handle, address = int_ptr)
  DspDescription.new(address)
end

#plugin_info(handle) ⇒ Plugin

Retrieves information to display for the selected plugin.

Parameters:

  • handle (Integer) —

    The handle to the plugin.

Returns:

  • (Plugin) —

    the plugin information.



945
946
947
948
949
950
951
952
 
# File 'lib/fmod/system.rb', line 945

def plugin_info(handle)
  name, type, vs = "\0" * 512, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetPluginInfo, self, handle, type, name, 512, vs)
  type = %i[output codec dsp][type.unpack1('l')]
  # noinspection RubyResolve
  name = name.delete("\0").force_encoding(Encoding::UTF_8)
  Plugin.new(handle, type, name, FMOD.uint2version(vs))
end

#plugin_path(directory) ⇒ void

This method returns an undefined value.

Specify a base search path for plugins so they can be placed somewhere else than the directory of the main executable.

Parameters:

  • directory (String) —

    A string containing a correctly formatted path to load plugins from.



874
875
876
877
878
 
# File 'lib/fmod/system.rb', line 874

def plugin_path(directory)
  # noinspection RubyResolve
  path = directory.encode(Encoding::UTF_8)
  FMOD.invoke(:System_SetPluginPath, self, path)
end

#ram_usage ⇒ RamUsage

Retrieves the amount of dedicated sound ram available if the platform supports it.

Most platforms use main RAM to store audio data, so this function usually isn’t necessary.

Returns:

  • (RamUsage) —

    the current RAM resource usage at the time of the call.



443
444
445
446
447
 
# File 'lib/fmod/system.rb', line 443

def ram_usage
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_INT, "\0" * SIZEOF_INT]
  FMOD.invoke(:System_GetSoundRAM, self, *args)
  RamUsage.new(*args.map { |arg| arg.unpack1('l') })
end

#record_driver(id) ⇒ Driver

Retrieves identification information about a sound device specified by its index, and specific to the output mode set with #output.

Parameters:

  • id (Integer) —

    Index of the sound driver device. The total number of devices can be found with #record_driver_count.

Returns:

  • (Driver) —

    the specified driver information.



551
552
553
554
555
 
# File 'lib/fmod/system.rb', line 551

def record_driver(id)
  args = [id, "\0" * 512, 512, Guid.new] + (0...4).map { "\0" * SIZEOF_INT }
  FMOD.invoke(:System_GetRecordDriverInfo, self, *args)
  Driver.send(:new, args)
end

#record_driver_count(connected = true) ⇒ Integer

Retrieves the number of recording devices available for this output mode.

Use this to enumerate all recording devices possible so that the user can select one.

Parameters:

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

    • true: Retrieve the number of recording drivers currently plugged in.

    • false: Receives the number of recording drivers available for this output mode.

Returns:

  • (Integer) —

    the number of record drivers.



537
538
539
540
541
 
# File 'lib/fmod/system.rb', line 537

def record_driver_count(connected = true)
  total, present = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetRecordNumDrivers, self, total, present)
  (connected ? present : total).unpack1('l')
end

#record_position(driver_id) ⇒ Integer

Retrieves the current recording position of the record buffer in PCM samples.

Parameters:

  • driver_id (Integer) —

    Enumerated driver ID.

Returns:

  • (Integer) —

    the current recording position in PCM samples.



519
520
521
522
523
 
# File 'lib/fmod/system.rb', line 519

def record_position(driver_id)
  position = "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetRecordPosition, self, driver_id, position)
  position.unpack1('L')
end

#record_start(driver_id, sound, loop = false) ⇒ void

Note:

The specified sound must be created with Core::Mode::CREATE_SAMPLE flag.

This method returns an undefined value.

Starts the recording engine recording to the specified recording sound.

Parameters:

  • driver_id (Integer) —

    Enumerated driver ID.

  • sound (Sound) —

    User created sound for the user to record to.

  • loop (Boolean) (defaults to: false) —

    Flag to tell the recording engine whether to continue recording to the provided sound from the start again, after it has reached the end. If this is set to true the data will be continually be overwritten once every loop.



494
495
496
497
 
# File 'lib/fmod/system.rb', line 494

def record_start(driver_id, sound, loop = false)
  FMOD.type?(sound, Sound)
  FMOD.invoke(:System_RecordStart, self, driver_id, sound, loop.to_i)
end

#recording?(driver_id) ⇒ Boolean

Retrieves the state of the FMOD recording API, ie if it is currently recording or not.

Parameters:

  • driver_id (Integer) —

    Enumerated driver ID.

Returns:

  • (Boolean) —

    the current recording state of the specified driver.



506
507
508
509
510
 
# File 'lib/fmod/system.rb', line 506

def recording?(driver_id)
  bool = "\0" * SIZEOF_INT
  FMOD.invoke(:System_IsRecording, self, driver_id, bool)
  bool.unpack1('l') != 0
end

#set_listener_attributes(id, attributes) ⇒ void #set_listener_attributes(id, position, velocity, forward, up) ⇒ void

This method returns an undefined value.

Updates the position, velocity and orientation of the specified 3D sound listener.

Overloads:

  • #set_listener_attributes(id, attributes) ⇒ void

    Parameters:

    • id (Integer) —

      Listener ID in a multi-listener environment. Specify 0 if there is only 1 listener.

    • attributes (ListenerAttributes)
  • #set_listener_attributes(id, position, velocity, forward, up) ⇒ void

    Parameters:

    • id (Integer) —

      Listener ID in a multi-listener environment. Specify 0 if there is only 1 listener.

    • position (Vector, nil) —

      The position of the listener in world space, measured in distance units. You can specify nil to not update the position.

    • velocity (Vector, nil) —

      The velocity of the listener measured in distance units *per second*. You can specify nil to not update the velocity of the listener.

    • forward (Vector, nil) —

      The forwards orientation of the listener. This vector must be of unit length and perpendicular to the up vector. You can specify nil to not update the forwards orientation of the listener.

    • up (Vector, nil) —

      The upwards orientation of the listener. This vector must be of unit length and perpendicular to the forwards vector. You can specify nil to not update the upwards orientation of the listener.

Since:

  • 0.9.5



747
748
749
750
751
752
753
754
755
756
 
# File 'lib/fmod/system.rb', line 747

def set_listener_attributes(id, *args)
  if args.size == 1 && FMOD.type?(args[0], ListenerAttributes)
    args = args[0].values
  end
  unless args.size == 4
    raise ArgumentError, "wrong number of arguments (#{args.size} for 2, 5)"
  end
  args.each { |arg| FMOD.type?(arg, Vector) unless arg.nil? }
  FMOD.invoke(:System_Set3DListenerAttributes, self, id, *args)
end

#set_speaker(speaker) ⇒ void #set_speaker(index, x, y, active = true) ⇒ void

This method returns an undefined value.

This function allows the user to specify the position of their actual physical speaker to account for non standard setups.

It also allows the user to disable speakers from 3D consideration in a game.

The function is for describing the “real world” speaker placement to provide a more natural panning solution for 3D sound. Graphical configuration screens in an application could draw icons for speaker placement that the user could position at their will.

Overloads:

  • #set_speaker(speaker) ⇒ void

    Parameters:

    • speaker (Speaker) —

      The speaker to set.

  • #set_speaker(index, x, y, active = true) ⇒ void

    Parameters:

    • index (Integer) —

      The index of the speaker to set. @see SpeakerIndex

    • x (Float) —

      The 2D X position relative to the listener.

    • y (Float) —

      The 2D Y position relative to the listener.

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

      The active state of a speaker.



186
187
188
189
190
191
192
193
194
 
# File 'lib/fmod/system.rb', line 186

def set_speaker(*args)
  unless [1, 3, 4].include?(args.size)
    message = "wrong number of arguments: #{args.size} for 1, 3, or 4"
    raise ArgumentError, message
  end
  index, x, y, active = args[0].is_a?(Speaker) ? args[0].values : args
  active = true if args.size == 3
  FMOD.invoke(:System_SetSpeakerPosition, self, index, x, y, active.to_i)
end

#speaker(index) ⇒ Speaker

Returns the current speaker position for the selected speaker.

Returns:

  • (Speaker) —

    the current speaker position for the selected speaker.

See Also:



157
158
159
160
161
162
163
 
# File 'lib/fmod/system.rb', line 157

def speaker(index)
  args = ["\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT, "\0" * SIZEOF_INT ]
  FMOD.invoke(:System_GetSpeakerPosition, self, index, *args)
  args = [index] + args.join.unpack('ffl')
  args[3] = args[3] != 0
  Speaker.new(*args)
end

#speaker_mode_channels(speaker_mode) ⇒ Integer

Returns the a speaker mode’s channel count.

Parameters:

  • speaker_mode (Integer) —

    the speaker mode to query.

Returns:

  • (Integer) —

    the a speaker mode’s channel count.

See Also:



1160
1161
1162
1163
1164
 
# File 'lib/fmod/system.rb', line 1160

def speaker_mode_channels(speaker_mode)
  count = "\0" * SIZEOF_INT
  FMOD.invoke(:System_GetSpeakerModeChannels, self, speaker_mode, count)
  count.unpack1('l')
end

#speakers ⇒ Array<Speaker>

Helper function to return the speakers as array.

Returns:

  • (Array<Speaker>) —

    the array of speakers.



150
151
152
 
# File 'lib/fmod/system.rb', line 150

def speakers
  each_speaker.to_a
end

#stop_recording(driver_id) ⇒ void

This method returns an undefined value.

Stops the recording engine from recording to the specified recording sound.

This does NOT raise an error if a the specified driver ID is incorrect or it is not recording.

Parameters:

  • driver_id (Integer) —

    Enumerated driver ID.



477
478
479
 
# File 'lib/fmod/system.rb', line 477

def stop_recording(driver_id)
  FMOD.invoke(:System_RecordStop, self, driver_id)
end

#unload_plugin(handle) ⇒ void

This method returns an undefined value.

Unloads a plugin from memory.

Parameters:

  • handle (Integer) —

    Handle to a pre-existing plugin.



834
835
836
 
# File 'lib/fmod/system.rb', line 834

def unload_plugin(handle)
  FMOD.invoke(:System_UnloadPlugin, self, handle)
end

#unlock_dsp ⇒ void

Note:

The DSP engine must be locked with #lock_dsp before this function

This method returns an undefined value.

Mutual exclusion function to unlock the FMOD DSP engine (which runs asynchronously in another thread) and let it continue executing.

is called.



1107
1108
1109
 
# File 'lib/fmod/system.rb', line 1107

def unlock_dsp
  FMOD.invoke(:System_UnlockDSP, self)
end

#update ⇒ void

Note:

Various callbacks are driven from this function, and it must be called for them to be invoked.

This method returns an undefined value.

Updates the FMOD system. This should be called once per “game tick”, or once per frame in your application.



1438
1439
1440
 
# File 'lib/fmod/system.rb', line 1438

def update
  FMOD.invoke(:System_Update, self)
end