Class: FMOD::ChannelControl Abstract

Inherits:
Handle
  • Object
show all
Includes:
Core, Fiddle
Defined in:
lib/fmod/channel_control.rb

Overview

This class is abstract.

The base class for both Channel and ChannelGroup objects.

Direct Known Subclasses

Channel, ChannelGroup

Defined Under Namespace

Classes: ChannelDelay, DistanceFilter, DspChain, FadePoint

3D Sound collapse

Instance Attribute Summary collapse

Attributes inherited from Handle

#user_data

3D Sound collapse

Callbacks collapse

Instance Method Summary collapse

Methods inherited from Handle

#int_ptr, #release, #to_s

Constructor Details

#initialize(address = nil) ⇒ ChannelControl

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

Returns a new instance of ChannelControl.



1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
 
# File 'lib/fmod/channel_control.rb', line 1032

def initialize(address = nil)
  super
  @callbacks = {}
  ret = TYPE_INT
  sig = [TYPE_VOIDP, TYPE_INT, TYPE_INT, TYPE_VOIDP, TYPE_VOIDP]
  abi = FMOD::ABI
  bc = Closure::BlockCaller.new(ret, sig, abi) do |_c, _t, cb_type, d1, d2|
    if @callbacks[cb_type]
      case cb_type
      when 0 then @callbacks[0].each(&:call)
      when 1
        virtual = d1.to_s(SIZEOF_INT).unpack1('l') != 0
        @callbacks[1].each { |cb| cb.call(virtual) }
      when 2
        index = d1.to_s(SIZEOF_INT).unpack1('l')
        @callbacks[2].each { |cb| cb.call(index) }
      when 3 then @callbacks[3].each { |cb| cb.call(d1, d2) }
      else raise FMOD::Error, "Invalid channel callback type."
      end
    end
    Result::OK
  end
  FMOD.invoke(:ChannelGroup_SetCallback, self, bc)
end

Instance Attribute Details

#audibility ⇒ Float (readonly)

The combined volume after 3D spatialization and geometry occlusion calculations including any volumes set via the API.

This does not represent the waveform, just the calculated result of all volume modifiers. This value is used by the virtual channel system to order its channels between real and virtual.

Returns:

  • (Float) —

    the combined volume after 3D spatialization and geometry occlusion.



290
 
# File 'lib/fmod/channel_control.rb', line 290

float_reader(:audibility, :ChannelGroup_GetAudibility)

#cone_orientation ⇒ Vector

Returns the orientation of the sound projection cone.

Returns:

  • (Vector) —

    the orientation of the sound projection cone.



521
522
523
524
525
 
# File 'lib/fmod/channel_control.rb', line 521

def cone_orientation
  vector = FMOD::Core::Vector.new
  FMOD.invoke(:ChannelGroup_Get3DConeOrientation, self, vector)
  vector
end

#cone_settings ⇒ ConeSettings

The angles that define the sound projection cone including the volume when outside the cone.

Returns:

Since:

  • 0.9.2



539
540
541
542
543
 
# File 'lib/fmod/channel_control.rb', line 539

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

#custom_rolloff ⇒ Array<Vector>

Must be used in conjunction with FMOD::Core::Mode::CUSTOM_ROLLOFF_3D flag to be activated.

Points must be sorted by distance! Passing an unsorted list to FMOD will result in an error.

Returns:

  • (Array<Vector>) —

    the rolloff curve.



432
433
434
435
436
437
438
439
440
441
 
# File 'lib/fmod/channel_control.rb', line 432

def custom_rolloff
  count = "\0" * SIZEOF_INT
  FMOD.invoke(:ChannelGroup_Get3DCustomRolloff, self, nil, count)
  count = count.unpack1('l')
  return [] if count.zero?
  size = SIZEOF_FLOAT * 3
  FMOD.invoke(:ChannelGroup_Get3DCustomRolloff, self, ptr = int_ptr, nil)
  buffer = Pointer.new(ptr.unpack1('J'), count * size).to_str
  (0...count).map { |i| Vector.new(*buffer[i * size, size].unpack('fff')) }
end

#delay ⇒ ChannelDelay

The start (and/or stop) time relative to the parent channel group DSP clock, with sample accuracy.

Every channel and channel group has its own DSP Clock. A channel or channel group can be delayed relatively against its parent, with sample accurate positioning. To delay a sound, use the ‘parent’ channel group DSP clock to reference against when passing values into this function.

If a parent channel group changes its pitch, the start and stop times will still be correct as the parent clock is rate adjusted by that pitch.

Returns:

See Also:



919
920
921
922
923
924
925
926
 
# File 'lib/fmod/channel_control.rb', line 919

def delay
  clock_start = "\0" * SIZEOF_LONG_LONG
  clock_end = "\0" * SIZEOF_LONG_LONG
  stop = "\0" * SIZEOF_INT
  FMOD.invoke(:ChannelGroup_GetDelay, self, clock_start, clock_end, stop)
  stop = stop.unpack1('l') != 0
  ChannelDelay.new(clock_start.unpack1('Q'), clock_end.unpack1('Q'), stop)
end

#direct_occlusion ⇒ Float

Returns the occlusion factor for the direct path.

Returns:

  • (Float) —

    the occlusion factor for the direct path.



338
339
340
341
342
 
# File 'lib/fmod/channel_control.rb', line 338

def direct_occlusion
  direct = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:ChannelGroup_Get3DOcclusion, self, direct, nil)
  direct.unpack1('f')
end

#distance_filter ⇒ DistanceFilter

Returns the behaviour of a 3D distance filter, whether to enable or disable it, and frequency characteristics.

Returns:

  • (DistanceFilter) —

    the behaviour of a 3D distance filter, whether to enable or disable it, and frequency characteristics.



406
407
408
409
410
411
412
 
# File 'lib/fmod/channel_control.rb', line 406

def distance_filter
  args = ["\0" * SIZEOF_INT, "\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT]
  FMOD.invoke(:ChannelGroup_Get3DDistanceFilter, self, *args)
  args = args.join.unpack('lff')
  args[0] = args[0] != 0
  DistanceFilter.new(*args)
end

#doppler3D ⇒ Float

The doppler scale.

  • Minimum: 0.0 (none)

  • Maximum: 5.0 (exaggerated)

  • Default: 1.0 (normal)

Returns:

  • (Float) —

    the amount by which doppler is scaled.



331
 
# File 'lib/fmod/channel_control.rb', line 331

float_reader(:doppler3D, :ChannelGroup_Get3DDopplerLevel)

#dsps ⇒ DspChain

Returns the DSP chain of the FMOD::ChannelControl, containing the effects currently applied.

Returns:



812
813
814
 
# File 'lib/fmod/channel_control.rb', line 812

def dsps
  DspChain.send(:new, self)
end

#level3D ⇒ Float

The 3D pan level.

  • Minimum: 0.0 (attenuation is ignored and panning as set by 2D panning functions)

  • Maximum: 1.0 (pan and attenuate according to 3D position)

  • Default: 0.0

Returns:

  • (Float) —

    the 3D pan level.



311
 
# File 'lib/fmod/channel_control.rb', line 311

float_reader(:level3D, :ChannelGroup_Get3DLevel)

#low_pass_gain ⇒ Float

The dry signal when low-pass filtering is applied.

  • Minimum: 0.0 (silent, full filtering)

  • Maximum: 1.0 (full volume, no filtering)

  • Default: 1.0

Returns:

  • (Float) —

    the linear gain level.



298
 
# File 'lib/fmod/channel_control.rb', line 298

float_reader(:low_pass_gain, :ChannelGroup_GetLowPassGain)

#matrix ⇒ Array<Array<Float>>

A 2D pan matrix that maps input channels (columns) to output speakers (rows).

Levels can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.

The matrix size will generally be the size of the number of channels in the current speaker mode. Use {System.software_format }to determine this.

If a matrix already exists then the matrix passed in will applied over the top of it. The input matrix can be smaller than the existing matrix.

A “unit” matrix allows a signal to pass through unchanged. For example for a 5.1 matrix a unit matrix would look like this:

[[ 1, 0, 0, 0, 0, 0 ]
 [ 0, 1, 0, 0, 0, 0 ]
 [ 0, 0, 1, 0, 0, 0 ]
 [ 0, 0, 0, 1, 0, 0 ]
 [ 0, 0, 0, 0, 1, 0 ]
 [ 0, 0, 0, 0, 0, 1 ]]

Returns:

  • (Array<Array<Float>>) —

    a 2-dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel.



708
709
710
711
712
713
714
715
716
 
# File 'lib/fmod/channel_control.rb', line 708

def matrix
  o, i = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:ChannelGroup_GetMixMatrix, self, nil, o, i, 0)
  o, i = o.unpack1('l'), i.unpack1('l')
  return [] if o.zero? || i.zero?
  buffer = "\0" * (SIZEOF_FLOAT * o * i)
  FMOD.invoke(:ChannelGroup_GetMixMatrix, self, buffer, int_ptr, int_ptr, 0)
  buffer.unpack('f*').each_slice(i).to_a
end

#max_distance ⇒ Float

Returns Maximum volume distance in “units”. (Default: 10000.0).

Returns:

  • (Float) —

    Maximum volume distance in “units”. (Default: 10000.0)

See Also:



472
473
474
475
476
 
# File 'lib/fmod/channel_control.rb', line 472

def max_distance
  max = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:ChannelGroup_Get3DMinMaxDistance, self, nil, max)
  max.unpack1('f')
end

#min_distance ⇒ Float

Returns Minimum volume distance in “units”. (Default: 1.0).

Returns:

  • (Float) —

    Minimum volume distance in “units”. (Default: 1.0)

See Also:



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

def min_distance
  min = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:ChannelGroup_Get3DMinMaxDistance, self, min, nil)
  min.unpack1('f')
end

#mode ⇒ Integer

Changes some attributes for a FMOD::ChannelControl based on the mode passed in.

Supported flags:

When changing the loop mode, sounds created with FMOD::Core::Mode::CREATE_STREAM may have already been pre-buffered and executed their loop logic ahead of time before this call was even made. This is dependant on the size of the sound versus the size of the stream decode buffer. If this happens, you may need to re-flush the stream buffer by calling FMOD::Channel#seek. Note this will usually only happen if you have sounds or loop points that are smaller than the stream decode buffer size.

Returns:

  • (Integer) —

    Mode bits.



261
 
# File 'lib/fmod/channel_control.rb', line 261

integer_reader(:mode, :ChannelGroup_GetMode)

#parent ⇒ System (readonly)

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

Returns:

  • (System) —

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



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

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

#pitch ⇒ Float

Sets the pitch value.

This function scales existing frequency values by the pitch.

  • 0.5: One octave lower

  • 2.0: One octave higher

  • 1.0: Normal pitch

Returns:

  • (Float) 


230
 
# File 'lib/fmod/channel_control.rb', line 230

float_reader(:pitch, :ChannelGroup_GetPitch)

#position3D ⇒ Vector

Returns the position used to apply panning, attenuation and doppler.

Returns:

  • (Vector) —

    the position used to apply panning, attenuation and doppler.



373
374
375
376
377
 
# File 'lib/fmod/channel_control.rb', line 373

def position3D
  position = Vector.zero
  FMOD.invoke(:ChannelGroup_Get3DAttributes, self, position, nil, nil)
  position
end

#reverb_occlusion ⇒ Float

Returns the occlusion factor for the reverb mix.

Returns:

  • (Float) —

    the occlusion factor for the reverb mix.



355
356
357
358
359
 
# File 'lib/fmod/channel_control.rb', line 355

def reverb_occlusion
  reverb = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:ChannelGroup_Get3DOcclusion, self, nil, reverb)
  reverb.unpack1('f')
end

#spread3D ⇒ Float

The speaker spread angle.

  • Minimum: 0.0

  • Maximum: 360.0

  • Default: 0.0

Returns:

  • (Float) —

    the spread of a 3D sound in speaker space.



321
 
# File 'lib/fmod/channel_control.rb', line 321

float_reader(:spread3D, :ChannelGroup_Get3DSpread)

#velocity3D ⇒ Vector

Returns the velocity used to apply panning, attenuation and doppler.

Returns:

  • (Vector) —

    the velocity used to apply panning, attenuation and doppler.



390
391
392
393
394
 
# File 'lib/fmod/channel_control.rb', line 390

def velocity3D
  velocity = Vector.zero
  FMOD.invoke(:ChannelGroup_Get3DAttributes, self, nil, velocity, nil)
  velocity
end

#volume ⇒ Float

Gets or sets the linear volume level.

Volume level can be below 0.0 to invert a signal and above 1.0 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.

Returns:

  • (Float) 


205
 
# File 'lib/fmod/channel_control.rb', line 205

float_reader(:volume, :ChannelGroup_GetVolume)

#volume_ramp ⇒ Boolean

Gets or sets flag indicating whether the channel automatically ramps when setting volumes.

When changing volumes on a non-paused channel, FMOD normally adds a small ramp to avoid a pop sound. This function allows that setting to be overridden and volume changes to be applied immediately.

Returns:

  • (Boolean) 


218
 
# File 'lib/fmod/channel_control.rb', line 218

bool_reader(:volume_ramp, :ChannelGroup_GetVolumeRamp)

Instance Method Details

#add_fade(fade_point) ⇒ self #add_fade(clock, volume) ⇒ self

Add a volume point to fade from or towards, using a clock offset and 0.0 to 1.0 volume level.

Overloads:

  • #add_fade(fade_point) ⇒ self

    Parameters:

    • fade_point (FadePoint) —

      Fade point structure defining the values.

  • #add_fade(clock, volume) ⇒ self

    Parameters:

    • clock (Integer) —

      DSP clock of the parent channel group to set the fade point volume.

    • volume (Float) —

      Volume level where 0.0 is silent and 1.0 is normal volume. Amplification is supported.

Returns:

  • (self) 


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

def add_fade(*args)
  args = args[0].values if args.size == 1 && args[0].is_a?(FadePoint)
  FMOD.invoke(:ChannelGroup_AddFadePoint, self, *args)
  self
end

#dsp_clock ⇒ Integer

Retrieves the DSP clock value which count up by the number of samples per second in the software mixer, i.e. if the default sample rate is 48KHz, the DSP clock increments by 48000 per second.

Returns:

  • (Integer) —

    the current clock value.



845
846
847
848
849
 
# File 'lib/fmod/channel_control.rb', line 845

def dsp_clock
  buffer = "\0" * SIZEOF_LONG_LONG
  FMOD.invoke(:ChannelGroup_GetDSPClock, self, buffer, nil)
  buffer.unpack1('Q')
end

#fade_point_count ⇒ Integer

Retrieves the number of fade points set within the FMOD::ChannelControl.

Returns:

  • (Integer) —

    The number of fade points.



592
593
594
595
596
 
# File 'lib/fmod/channel_control.rb', line 592

def fade_point_count
  count = "\0" * SIZEOF_INT
  FMOD.invoke(:ChannelGroup_GetFadePoints, self, count, nil, nil)
  count.unpack1('l')
end

#fade_points ⇒ Array<FadePoint>

Retrieve information about fade points stored within a FMOD::ChannelControl.

Returns:

  • (Array<FadePoint>) —

    An array of FadePoint objects, or an empty array if no fade points are present.



602
603
604
605
606
607
608
609
610
 
# File 'lib/fmod/channel_control.rb', line 602

def fade_points
  count = fade_point_count
  return [] if count.zero?
  clocks = "\0" * (count * SIZEOF_LONG_LONG)
  volumes = "\0" * (count * SIZEOF_FLOAT)
  FMOD.invoke(:ChannelGroup_GetFadePoints, self, int_ptr, clocks, volumes)
  args = clocks.unpack('Q*').zip(volumes.unpack('f*'))
  args.map { |values| FadePoint.new(*values) }
end

#fade_ramp(clock, volume) ⇒ void

This method returns an undefined value.

Add a short 64 sample volume ramp to the specified time in the future using fade points.

Parameters:

  • clock (Integer) —

    DSP clock of the parent channel group when the volume will be ramped to.

  • volume (Float) —

    Volume level where 0 is silent and 1.0 is normal volume. Amplification is supported.



835
836
837
 
# File 'lib/fmod/channel_control.rb', line 835

def fade_ramp(clock, volume)
  FMOD.invoke(:ChannelGroup_SetFadePointRamp, self, clock, volume)
end

#get_reverb_level(index) ⇒ Float

Retrieves the wet level (or send level) for a particular reverb instance.

Parameters:

  • index (Integer) —

    Index of the particular reverb instance to target.

Returns:

  • (Float) —

    the send level for the signal to the reverb, from 0 (none) to 1.0 (full).

See Also:



871
872
873
874
875
 
# File 'lib/fmod/channel_control.rb', line 871

def get_reverb_level(index)
  wet = "\0" * SIZEOF_FLOAT
  FMOD.invoke(:ChannelGroup_GetReverbProperties, self, index, wet)
  wet.unpack1('f')
end

#input_mix(*levels) ⇒ self

Sets the incoming volume level for each channel of a multi-channel sound. This is a helper to avoid calling #matrix.

A multi-channel sound is a single sound that contains from 1 to 32 channels of sound data, in an interleaved fashion. If in the extreme case, a 32 channel wave file was used, an array of 32 floating point numbers denoting their volume levels would be passed in to the levels parameter.

Parameters:

  • levels (Array<Float>) —

    Array of volume levels for each incoming channel.

Returns:

  • (self) 


674
675
676
677
678
679
 
# File 'lib/fmod/channel_control.rb', line 674

def input_mix(*levels)
  count = levels.size
  binary = levels.pack('f*')
  FMOD.invoke(:ChannelGroup_SetMixLevelsInput, self, binary, count)
  self
end

#min_max_distance(min, max) ⇒ void

This method returns an undefined value.

Sets the minimum and maximum audible distance.

When the listener is in-between the minimum distance and the sound source the volume will be at its maximum. As the listener moves from the minimum distance to the maximum distance the sound will attenuate following the rolloff curve set. When outside the maximum distance the sound will no longer attenuate.

Minimum distance is useful to give the impression that the sound is loud or soft in 3D space. An example of this is a small quiet object, such as a bumblebee, which you could set a small minimum distance such as 0.1. This would cause it to attenuate quickly and disappear when only a few meters away from the listener. Another example is a jumbo jet, which you could set to a minimum distance of 100.0 causing the volume to stay at its loudest until the listener was 100 meters away, then it would be hundreds of meters more before it would fade out.

Maximum distance is effectively obsolete unless you need the sound to stop fading out at a certain point. Do not adjust this from the default if you dont need to. Some people have the confusion that maximum distance is the point the sound will fade out to zero, this is not the case.

Parameters:

  • min (Float) —

    Minimum volume distance in “units”.

    • Default: 1.0

  • max (Float) —

    Maximum volume distance in “units”.

    • Default: 10000.0

See Also:



513
514
515
 
# File 'lib/fmod/channel_control.rb', line 513

def min_max_distance(min, max)
  FMOD.invoke(:ChannelGroup_Set3DMinMaxDistance, self, min, max)
end

#mute ⇒ self

Sets the mute state effectively silencing it or returning it to its normal volume.

Returns:

  • (self)

See Also:



792
793
794
795
 
# File 'lib/fmod/channel_control.rb', line 792

def mute
  FMOD.invoke(:ChannelGroup_SetMute, self, 1)
  self
end

#muted? ⇒ Boolean

Returns the mute state.

Returns:

  • (Boolean) —

    the mute state.



277
 
# File 'lib/fmod/channel_control.rb', line 277

bool_reader(:muted?, :ChannelGroup_GetMute)

#on_occlusion(proc = nil) {|direct, reverb| ... } ⇒ self

Binds the given block so that it will be invoked when the occlusion is calculated.

Parameters:

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

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

Yields:

  • (direct, reverb) —

    The block to call when occlusion is calculated, with pointers to the direct and reverb occlusion values passed to it.

Yield Parameters:

  • direct (Pointer) —

    A pointer to a floating point direct value that can be read (de-referenced) and modified after the geometry engine has calculated it for this channel.

  • reverb (Pointer) —

    A pointer to a floating point reverb value that can be read (de-referenced) and modified after the geometry engine has calculated it for this channel.

Yield Returns:

Returns:

  • (self) 


1024
1025
1026
 
# File 'lib/fmod/channel_control.rb', line 1024

def on_occlusion(proc = nil, &block)
  set_callback(3, &(block_given? ? block : proc))
end

#on_stop(proc = nil) { ... } ⇒ self

Binds the given block so that it will be invoked when the channel is stopped, either by #stop or when playback reaches an end.

Examples:

>> channel.on_stop do
>>   puts "Channel stop"
>> end
>> channel.stop

"Channel stop"

Parameters:

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

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

Yields:

Yield Returns:

Returns:

  • (self) 


978
979
980
 
# File 'lib/fmod/channel_control.rb', line 978

def on_stop(proc = nil, &block)
  set_callback(0, &(block_given? ? block : proc))
end

#on_sync_point(proc = nil) {|index| ... } ⇒ self

Binds the given block so that it will be invoked when a sync-point is encountered.

Parameters:

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

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

Yields:

  • (index) —

    The block to call when a sync-point is encountered, with the index of the sync-point passed to it.

Yield Parameters:

  • index (Integer) —

    The sync-point index.

Yield Returns:

Returns:

  • (self) 


1006
1007
1008
 
# File 'lib/fmod/channel_control.rb', line 1006

def on_sync_point(proc = nil, &block)
  set_callback(2, &(block_given? ? block : proc))
end

#on_voice_swap(proc = nil) {|emulated| ... } ⇒ self

Binds the given block so that it will be invoked when the a voice is swapped to or from emulated/real.

Parameters:

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

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

Yields:

  • (emulated) —

    The block to call when a voice is swapped, with flag indicating if voice is emulated passed to it.

Yield Parameters:

  • emulated (Boolean) —

    • true: Swapped from real to emulated

    • false: Swapped from emulated to real

Yield Returns:

Returns:

  • (self) 


993
994
995
 
# File 'lib/fmod/channel_control.rb', line 993

def on_voice_swap(proc = nil, &block)
  set_callback(1, &(block_given? ? block : proc))
end

#output_mix(fl, fr, center, lfe, sl, sr, bl, br) ⇒ self

Note:

This function overwrites any pan/mix-level by overwriting the

Sets the speaker volume levels for each speaker individually, this is a helper to avoid having to set the mix matrix.

Levels can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion. Speakers specified that don’t exist will simply be ignored. For more advanced speaker control, including sending the different channels of a stereo sound to arbitrary speakers, see #matrix.

FMOD::ChannelControl‘s matrix.

Parameters:

  • fl (Float) —

    Volume level for the front left speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • fr (Float) —

    Volume level for the front right speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • center (Float) —

    Volume level for the center speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • lfe (Float) —

    Volume level for the sub-woofer speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • sl (Float) —

    Volume level for the surround left speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • sr (Float) —

    Volume level for the surround right speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • bl (Float) —

    Volume level for the back left speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

  • br (Float) —

    Volume level for the back right speaker of a multichannel speaker setup, 0.0 (silent), 1.0 (normal volume).

Returns:

  • (self) 


656
657
658
659
660
 
# File 'lib/fmod/channel_control.rb', line 656

def output_mix(fl, fr, center, lfe, sl, sr, bl, br)
  FMOD.invoke(:ChannelGroup_SetMixLevelsOutput, self, fl,
    fr, center, lfe, sl, sr, bl, br)
  self
end

#pan(pan) ⇒ self

Sets the pan level, this is a helper to avoid setting the #matrix.

Mono sounds are panned from left to right using constant power panning (non-linear fade). This means when pan = 0.0, the balance for the sound in each speaker is 71% left and 71% right, not 50% left and 50% right. This gives (audibly) smoother pans.

Stereo sounds heave each left/right value faded up and down according to the specified pan position. This means when pan is 0.0, the balance for the sound in each speaker is 100% left and 100% right. When pan is -1.0, only the left channel of the stereo sound is audible, when pan is 1.0, only the right channel of the stereo sound is audible.

Parameters:

  • pan (Float) —

    The desired pan level.

    • Minimum: -1.0 (left)

    • Maximum: 1.0 (right)

    • Default: 0.0 (center)

Returns:

  • (self) 


748
749
750
751
 
# File 'lib/fmod/channel_control.rb', line 748

def pan(pan)
  FMOD.invoke(:ChannelGroup_SetPan, self, pan.clamp(-1.0, 1.0))
  self
end

#parent_clock ⇒ Integer

Retrieves the DSP clock value which count up by the number of samples per second in the software mixer, i.e. if the default sample rate is 48KHz, the DSP clock increments by 48000 per second.

Returns:

  • (Integer) —

    the current parent clock value.



857
858
859
860
861
 
# File 'lib/fmod/channel_control.rb', line 857

def parent_clock
  buffer = "\0" * SIZEOF_LONG_LONG
  FMOD.invoke(:ChannelGroup_GetDSPClock, self, nil, buffer)
  buffer.unpack1('Q')
end

#pause ⇒ self

Sets the paused state.

Returns:

  • (self)

See Also:



769
770
771
772
 
# File 'lib/fmod/channel_control.rb', line 769

def pause
  FMOD.invoke(:ChannelGroup_SetPaused, self, 1)
  self
end

#paused? ⇒ Boolean

Returns the paused state.

Returns:

  • (Boolean) —

    the paused state.



272
 
# File 'lib/fmod/channel_control.rb', line 272

bool_reader(:paused?, :ChannelGroup_GetPaused)

#playing? ⇒ Boolean

Returns the playing state.

Returns:

  • (Boolean) —

    the playing state.



267
 
# File 'lib/fmod/channel_control.rb', line 267

bool_reader(:playing?, :ChannelGroup_IsPlaying)

#remove_fade_points(clock_start, clock_end) ⇒ self

Remove volume fade points on the time-line. This function will remove multiple fade points with a single call if the points lay between the 2 specified clock values (inclusive).

Parameters:

  • clock_start (Integer) —

    DSP clock of the parent channel group to start removing fade points from.

  • clock_end (Integer) —

    DSP clock of the parent channel group to start removing fade points to.

Returns:

  • (self) 


621
622
623
624
 
# File 'lib/fmod/channel_control.rb', line 621

def remove_fade_points(clock_start, clock_end)
  FMOD.invoke(:ChannelGroup_RemoveFadePoints, self, clock_start, clock_end)
  self
end

#resume ⇒ self

Resumes playback from a paused state.

Returns:

  • (self)

See Also:



780
781
782
783
 
# File 'lib/fmod/channel_control.rb', line 780

def resume
  FMOD.invoke(:ChannelGroup_SetPaused, self, 0)
  self
end

#set_cone(inside_angle, outside_angle, outside_volume) ⇒ void

This method returns an undefined value.

Sets the angles that define the sound projection cone including the volume when outside the cone.

Parameters:

  • inside_angle (Float) —

    Inside cone angle, in degrees. This is the angle within which the sound is at its normal volume.

  • outside_angle (Float) —

    Outside cone angle, in degrees. This is the angle outside of which the sound is at its outside volume.

  • outside_volume (Float) —

    Cone outside volume.

Since:

  • 0.9.2



561
562
563
564
565
566
567
568
 
# File 'lib/fmod/channel_control.rb', line 561

def set_cone(inside_angle, outside_angle, outside_volume)
  if outside_angle < inside_angle
    raise Error, 'Outside angle must be greater than inside angle.'
  end
  FMOD.invoke(:ChaennlGroup_Set3DConeSettings, self, inside_angle,
              outside_angle, outside_volume)
  self
end

#set_delay(clock_start, clock_end, stop) ⇒ self

The start (and/or stop) time relative to the parent channel group DSP clock, with sample accuracy.

Every channel and channel group has its own DSP Clock. A channel or channel group can be delayed relatively against its parent, with sample accurate positioning. To delay a sound, use the ‘parent’ channel group DSP clock to reference against when passing values into this function.

If a parent channel group changes its pitch, the start and stop times will still be correct as the parent clock is rate adjusted by that pitch.

Parameters:

  • clock_start (Integer) —

    DSP clock of the parent channel group to audibly start playing sound at, a value of 0 indicates no delay.

  • clock_end (Integer) —

    DSP clock of the parent channel group to audibly stop playing sound at, a value of 0 indicates no delay.

  • stop (Boolean) —

    true to stop according to #playing?, otherwise false to remain “active” and a new start delay could start playback again at a later time.

Returns:

  • (self)

See Also:



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

def set_delay(clock_start, clock_end, stop)
  stop = stop.to_i
  FMOD.invoke(:ChannelGroup_SetDelay, self, clock_start, clock_end, stop)
  self
end

#set_reverb_level(index, wet_level) ⇒ void

This method returns an undefined value.

Sets the wet level (or send level) of a particular reverb instance.

A Channel is automatically connected to all existing reverb instances due to the default wet level of 1.0. A ChannelGroup however will not send to any reverb by default requiring an explicit call to this function.

A ChannelGroup reverb is optimal for the case where you want to send 1 mixed signal to the reverb, rather than a lot of individual channel reverb sends. It is advisable to do this to reduce CPU if you have many Channels inside a ChannelGroup.

Keep in mind when setting a wet level for a ChannelGroup, any Channels under that ChannelGroup will still have their existing sends to the reverb. To avoid this doubling up you should explicitly set the Channel wet levels to 0.0.

Parameters:

  • index (Integer) —

    Index of the particular reverb instance to target.

See Also:



898
899
900
901
 
# File 'lib/fmod/channel_control.rb', line 898

def set_reverb_level(index, wet_level)
  wet = wet_level.clamp(0.0, 1.0)
  FMOD.invoke(:ChannelGroup_SetReverbProperties, self, index, wet)
end

#stop ⇒ void

This method returns an undefined value.

Stops the channel (or all channels in the channel group) from playing.

Makes it available for re-use by the priority system.



759
760
761
 
# File 'lib/fmod/channel_control.rb', line 759

def stop
  FMOD.invoke(:ChannelGroup_Stop, self)
end

#unmute ⇒ self

Resumes the volume from a muted state.

Returns:

  • (self)

See Also:



803
804
805
806
 
# File 'lib/fmod/channel_control.rb', line 803

def unmute
  FMOD.invoke(:ChannelGroup_SetMute, self, 0)
  self
end