Class: FMOD::Channel

Inherits:
ChannelControl show all
Defined in:
lib/fmod/channel.rb

Overview

Represents a sound-card channel and a interface to sound playback.

Instance Attribute Summary collapse

Attributes inherited from ChannelControl

#audibility, #cone_orientation, #cone_settings, #custom_rolloff, #delay, #direct_occlusion, #distance_filter, #doppler3D, #dsps, #level3D, #low_pass_gain, #matrix, #max_distance, #min_distance, #mode, #parent, #pitch, #position3D, #reverb_occlusion, #spread3D, #velocity3D, #volume, #volume_ramp

Attributes inherited from Handle

#user_data

Instance Method Summary collapse

Methods inherited from ChannelControl

#add_fade, #dsp_clock, #fade_point_count, #fade_points, #fade_ramp, #get_reverb_level, #initialize, #input_mix, #min_max_distance, #mute, #muted?, #on_occlusion, #on_stop, #on_sync_point, #on_voice_swap, #output_mix, #pan, #parent_clock, #pause, #paused?, #playing?, #remove_fade_points, #resume, #set_cone, #set_delay, #set_reverb_level, #stop, #unmute

Methods inherited from Handle

#initialize, #int_ptr, #release, #to_s

Constructor Details

This class inherits a constructor from FMOD::ChannelControl

Instance Attribute Details

#current_sound ⇒ Sound? (readonly)

Returns the currently playing sound for this channel, or nil if no sound is playing.

Returns:

  • (Sound, nil) —

    the currently playing sound for this channel, or nil if no sound is playing.



55
56
57
58
 
# File 'lib/fmod/channel.rb', line 55

def current_sound
  FMOD.invoke(:Channel_GetCurrentSound, self, sound = int_ptr)
  sound.unpack1('J').zero? ? nil : Sound.new(sound)
end

#frequency ⇒ Float

This value can also be negative to play the sound backwards (negative frequencies allowed with non-stream sounds only).

When a sound is played, it plays at the default frequency of the sound which can be set by Sound#default_frequency.

For most file formats, the default frequency is determined by the audio format.

Returns:

  • (Float) —

    the channel frequency or playback rate, in Hz.



20
 
# File 'lib/fmod/channel.rb', line 20

float_reader(:frequency, :Channel_GetFrequency)

#group ⇒ ChannelGroup

Returns the currently assigned channel group for this FMOD::Channel.

Returns:



99
100
101
102
 
# File 'lib/fmod/channel.rb', line 99

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

#index ⇒ Integer (readonly)

Returns the internal channel index for a channel.

Returns:

  • (Integer) —

    the internal channel index for a channel.



26
 
# File 'lib/fmod/channel.rb', line 26

integer_reader(:index, :Channel_GetIndex)

#loop_count ⇒ Integer

Sets a sound, by default, to loop a specified number of times before stopping if its mode is set to FMOD::Core::Mode::LOOP_NORMAL or FMOD::Core::Mode::LOOP_BIDI.

Returns:

  • (Integer) —

    the number of times to loop a sound before stopping.



48
 
# File 'lib/fmod/channel.rb', line 48

integer_reader(:loop_count, :Channel_GetLoopCount)

#priority ⇒ Integer

The channel priority.

When more channels than available are played the virtual channel system will choose existing channels to steal. Lower priority sounds will always be stolen before higher priority sounds. For channels of equal priority, that with the quietest FMOD::ChannelControl#audibility value will be stolen.

  • Minimum: 0

  • Maximum: 256

  • Default: 128

Returns:

  • (Integer) —

    the current priority.



40
 
# File 'lib/fmod/channel.rb', line 40

integer_reader(:priority, :Channel_GetPriority)

Instance Method Details

#loop_points(start_unit = TimeUnit::MS, end_unit = TimeUnit::MS) ⇒ Array(Integer, Integer)

Retrieves the loop points for a sound.

Parameters:

  • start_unit (Integer) (defaults to: TimeUnit::MS) —

    The time format used for the returned loop start point. @see TimeUnit

  • end_unit (Integer) (defaults to: TimeUnit::MS) —

    The time format used for the returned loop end point. @see TimeUnit

Returns:

  • (Array(Integer, Integer)) —

    the loop points in an array where the first element is the start loop point, and second element is the end loop point in the requested time units.



120
121
122
123
124
125
 
# File 'lib/fmod/channel.rb', line 120

def loop_points(start_unit = TimeUnit::MS, end_unit = TimeUnit::MS)
  loop_start, loop_end = "\0" * SIZEOF_INT, "\0" * SIZEOF_INT
  FMOD.invoke(:Channel_GetLoopPoints, self, loop_start,
    start_unit, loop_end, end_unit)
  [loop_start.unpack1('L'), loop_end.unpack1('L')]
end

#position(unit = TimeUnit::MS) ⇒ Integer

Returns the current playback position.

Parameters:

  • unit (Integer) (defaults to: TimeUnit::MS) —

    Time unit to retrieve into the position in. @see TimeUnit

Returns:

  • (Integer) —

    the current playback position.



74
75
76
77
78
 
# File 'lib/fmod/channel.rb', line 74

def position(unit = TimeUnit::MS)
  buffer = "\0" * SIZEOF_INT
  FMOD.invoke(:Channel_SetPosition, self, buffer, unit)
  buffer.unpack1('L')
end

#seek(position, unit = TimeUnit::MS) ⇒ self

Sets the playback position for the currently playing sound to the specified offset.

Parameters:

  • position (Integer) —

    Position of the channel to set in specified units.

  • unit (Integer) (defaults to: TimeUnit::MS) —

    Time unit to set the channel position by. @see TimeUnit

Returns:

  • (self) 


88
89
90
91
92
 
# File 'lib/fmod/channel.rb', line 88

def seek(position, unit = TimeUnit::MS)
  position = 0 if position < 0
  FMOD.invoke(:Channel_SetPosition, self, position, unit)
  self
end

#set_loop(loop_start, loop_end, start_unit = TimeUnit::MS, end_unit = TimeUnit::MS) ⇒ Object

Sets the loop points within a sound

If a sound was 44100 samples long and you wanted to loop the whole sound, loop_start would be 0, and loop_end would be 44099, not 44100. You wouldn’t use milliseconds in this case because they are not sample accurate.

If loop end is smaller or equal to loop start, it will result in an error.

If loop start or loop end is larger than the length of the sound, it will result in an error

Parameters:

  • loop_start (Integer) —

    The loop start point. This point in time is played, so it is inclusive.

  • loop_end (Integer) —

    The loop end point. This point in time is played, so it is inclusive

  • start_unit (Integer) (defaults to: TimeUnit::MS) —

    The time format used for the loop start point. @see TimeUnit

  • end_unit (Integer) (defaults to: TimeUnit::MS) —

    The time format used for the loop end point. @see TimeUnit



148
149
150
151
152
 
# File 'lib/fmod/channel.rb', line 148

def set_loop(loop_start, loop_end, start_unit = TimeUnit::MS, end_unit = TimeUnit::MS)
  FMOD.invoke(:Channel_SetLoopPoints, self, loop_start,
    start_unit, loop_end, end_unit)
  self
end

#virtual? ⇒ Boolean

Retrieves whether the channel is virtual (emulated) or not due to the virtual channel management system

Returns:

  • (Boolean) —

    the current virtual state.

    • true: Inaudible and currently being emulated at no CPU cost

    • false: Real voice that should be audible.



67
 
# File 'lib/fmod/channel.rb', line 67

bool_reader(:virtual?, :Channel_IsVirtual)