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
 
# File 'lib/fmod/system.rb', line 94

def initialize(address)
  super
  @rolloff_callbacks = []
  sig = [TYPE_VOIDP, TYPE_FLOAT]
  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.



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

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.



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

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.



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

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.



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

integer_reader(:driver_count, :System_GetNumDrivers)

#drivers ⇒ Array<Driver> (readonly)

Returns the array of available drivers.

Returns:

  • (Array<Driver>) —

    the array of available drivers.



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

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) 


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

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.



955
956
957
958
959
960
 
# File 'lib/fmod/system.rb', line 955

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.



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

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


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

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.



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

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.



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

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.



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

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.



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

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.



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

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:



1127
1128
1129
1130
1131
1132
 
# File 'lib/fmod/system.rb', line 1127

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.



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

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.



1175
1176
1177
1178
 
# File 'lib/fmod/system.rb', line 1175

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.



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

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:



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

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.



1315
1316
1317
1318
1319
 
# File 'lib/fmod/system.rb', line 1315

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.



1331
1332
1333
1334
 
# File 'lib/fmod/system.rb', line 1331

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.



993
994
995
996
997
 
# File 'lib/fmod/system.rb', line 993

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.



1096
1097
1098
1099
 
# File 'lib/fmod/system.rb', line 1096

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.



1168
1169
1170
 
# File 'lib/fmod/system.rb', line 1168

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.



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

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:



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

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.



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

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.



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

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:



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

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.



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

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:



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

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.



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

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:



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

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.



1007
1008
1009
1010
 
# File 'lib/fmod/system.rb', line 1007

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.



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

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.



1363
1364
1365
1366
1367
 
# File 'lib/fmod/system.rb', line 1363

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) 


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

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) 


1067
1068
1069
1070
1071
1072
1073
1074
 
# File 'lib/fmod/system.rb', line 1067

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.



936
937
938
939
940
941
942
943
944
945
946
 
# File 'lib/fmod/system.rb', line 936

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) 


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

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.



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

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.



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

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

#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:



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

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.



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

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.



1037
1038
1039
1040
1041
1042
1043
 
# File 'lib/fmod/system.rb', line 1037

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:



1146
1147
1148
1149
 
# File 'lib/fmod/system.rb', line 1146

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.



1154
1155
1156
1157
 
# File 'lib/fmod/system.rb', line 1154

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:



1303
1304
1305
 
# File 'lib/fmod/system.rb', line 1303

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:



1291
1292
1293
1294
1295
1296
1297
 
# File 'lib/fmod/system.rb', line 1291

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.



858
859
860
861
862
 
# File 'lib/fmod/system.rb', line 858

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.



878
879
880
881
882
 
# File 'lib/fmod/system.rb', line 878

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) 


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

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.



1271
1272
1273
1274
1275
1276
 
# File 'lib/fmod/system.rb', line 1271

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.



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

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.



1082
1083
1084
1085
1086
 
# File 'lib/fmod/system.rb', line 1082

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) 


839
840
841
842
843
844
845
 
# File 'lib/fmod/system.rb', line 839

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.



796
797
798
799
800
801
802
803
804
805
806
807
808
809
 
# File 'lib/fmod/system.rb', line 796

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.



910
911
912
913
 
# File 'lib/fmod/system.rb', line 910

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.



890
891
892
893
894
895
896
897
 
# File 'lib/fmod/system.rb', line 890

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.



819
820
821
822
823
 
# File 'lib/fmod/system.rb', line 819

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

def recording?(driver_id)
  bool = "\0" * SIZEOF_INT
  FMOD.invoke(:System_IsRecording, self, driver_id, bool)
  bool.unpack1('l') != 0
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.



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

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:



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

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:



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

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.



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

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.



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

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.



779
780
781
 
# File 'lib/fmod/system.rb', line 779

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.



1052
1053
1054
 
# File 'lib/fmod/system.rb', line 1052

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.



1383
1384
1385
 
# File 'lib/fmod/system.rb', line 1383

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