Module: Rubygame::Mixer

Defined in:
lib/rubygame/deprecated_mixer.rb

Overview

NOTE: This module is DEPRECATED and will be removed in Rubygame 3.0.

Please use Rubygame.open_audio, Rubygame.close_audio, Rubygame::Sound,
and Rubygame::Music instead.

The Mixer module provides access to the SDL_mixer library for audio
playback and mixing. This module is still very basic, but it is
good enough to load and play WAV files on multiple mix channels.

See the Sample class for loading audio files.
See the Music class for streaming music from a file.

Defined Under Namespace

Classes: Music, Sample

Constant Summary collapse

AUDIO_U8 = 
SDL::AUDIO_U8
AUDIO_S8 = 
SDL::AUDIO_S8
AUDIO_U16SYS = 
SDL::AUDIO_U16SYS
AUDIO_S16SYS = 
SDL::AUDIO_S16SYS

Class Method Summary collapse

Class Method Details

.close_audio ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame.close_audio instead.

Close the audio device being used by the mixer. You should not use any
mixer functions after this function, unless you use #open_audio() to
re-open the audio device. See also #open_audio().

Returns nil.



109
110
111
112
113
 
# File 'lib/rubygame/deprecated_mixer.rb', line 109

def self.close_audio()
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  SDL::Mixer.CloseAudio()
  return nil
end

.driver_name ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame.audio_driver instead.

Returns the name of the audio driver that SDL is using.

May raise SDLError if initialization fails.



161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/rubygame/deprecated_mixer.rb', line 161

def self.driver_name
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )

  driver = SDL.AudioDriverName()

  if driver.nil?
    raise( Rubygame::SDLError,
           "Error fetching audio driver name: #{SDL.GetError()}" )
  end

  return driver
end

.mix_channels ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame::Sound class instead.

Returns the number of mixing channels currently allocated.
See also #mix_channels=



122
123
124
125
 
# File 'lib/rubygame/deprecated_mixer.rb', line 122

def self.mix_channels
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  return SDL::Mixer.AllocateChannels(-1)
end

.mix_channels=(num_channels) ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame::Sound class instead.

Set the number of mixer channels, allocating or deallocating channels as
needed. This can be called many times, even during audio playback. If this
call reduces the number of channels allocated, the excess channels will
be stopped automatically. See also #mix_channels

Returns the number of mixing channels allocated.

Note that 8 mixing channels are allocated when #open_audio is called.
This method only needs to be called if you want a different number (either
greater or fewer) of mixing channels.

This method takes this argument:
num_channels::  desired number of mixing channels, an integer. 
                Negative values will cause this method to behave as
                #mix_channels, returning the number of channels
                currently allocated, without changing it.



148
149
150
151
 
# File 'lib/rubygame/deprecated_mixer.rb', line 148

def self.mix_channels=( num_channels )
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  return SDL::Mixer.AllocateChannels( num_channels )
end

.open_audio(frequency = nil, format = nil, channels = nil, buffer = nil) ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame.open_audio instead.

Initializes the audio device. You must call this before using the other
mixer functions. See also #close_audio().

Returns nil. May raise an SDLError if initialization fails.

This method takes these arguments:

frequency::  output sample rate in audio samples per second (Hz).
             Affects the quality of the sound output, at the
             expense of CPU usage. If nil, the default (22050) is
             used. 22050 is recommended for most games. For
             reference, 44100 is CD quality.

             The larger the value, the more processing required.

format::     output sample format. If nil, the default recommended
             system format is used. It's _highly_ recommended you
             leave this nil!

             But if you're feeling reckless, you can use one of these
             constants located in the Rubygame::Mixer module:

             AUDIO_U16SYS:: unsigned 16-bit samples.
             AUDIO_S16SYS:: signed 16-bit samples.
             AUDIO_U8::     unsigned 8-bit samples.
             AUDIO_S8::     signed 8-bit samples.

channels::   output sound channels. Use 2 for stereo, 1 for mono.
             If nil, the default (2) is used.
             This option is not related to mixing channels.

buffer::     size of the sound buffer, in bytes. If nil, the default
             (1024) is used. Larger values have more delay before
             playing a sound, but require less CPU usage (and
             have less skipping on slow systems).



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/rubygame/deprecated_mixer.rb', line 80

def self.open_audio( frequency=nil, format=nil, channels=nil, buffer=nil )

  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )

  frequency ||= 22050
  format    ||= SDL::Mixer::DEFAULT_FORMAT
  channels  ||= 2
  buffer    ||= 1024

  result = SDL::Mixer.OpenAudio(frequency, format, channels, buffer)

  if( result < 0 )
    raise( Rubygame::SDLError,
           "Error initializing SDL_mixer: #{SDL.GetError()}" )
  end

  return nil
end

.pause(channel_num) ⇒ Object

Pause playback of a currently-playing mixing channel.

Playback can be resumed from the current point with #resume.
See also #stop.



221
222
223
224
225
 
# File 'lib/rubygame/deprecated_mixer.rb', line 221

def self.pause( channel_num )
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  SDL::Mixer.Pause( channel_num )
  return nil
end

.play(sample, channel_num, repeats) ⇒ Object

NOTE: This method is DEPRECATED and will be removed in

Rubygame 3.0. Please use the Rubygame::Sound class instead.

Play an audio Sample on a mixing channel, repeating a certain number
of extra times. Returns the number of the channel that the sample
is being played on.

Raises SDLError if something goes wrong.

This method takes these arguments:
sample::      what Sample to play
channel_num:: which mixing channel to play the sample on.
              Use -1 to play on the first unreserved channel.
repeats::     how many extra times to repeat the sample.
              Can be -1 to repeat forever until it is stopped.



191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/rubygame/deprecated_mixer.rb', line 191

def self.play( sample, channel_num, repeats )
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  
  result = SDL::Mixer.PlayChannel( channel_num, sample.struct, repeats )

  if( result < 0 )
    raise( Rubygame::SDLError,
           "Error playing sample on channel %d: %s"%
           [channel, SDL.GetError()] )
  end

  return result
end

.resume(channel_num) ⇒ Object

Resume playback of a paused mixing channel. The channel must have

been paused (via the #pause method) for this to have any effect.
Playback will resume from the point where the channel was paused.



232
233
234
235
236
 
# File 'lib/rubygame/deprecated_mixer.rb', line 232

def self.resume( channel_num )
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  SDL::Mixer.Resume( channel_num )
  return nil
end

.stop(channel_num) ⇒ Object

Stop playback of a playing or paused mixing channel.

Unlike #pause, playback cannot be resumed from the current point.
See also #play.



210
211
212
213
214
 
# File 'lib/rubygame/deprecated_mixer.rb', line 210

def self.stop( channel_num )
  Rubygame.deprecated( "Rubygame::Mixer", "3.0" )
  SDL::Mixer.HaltChannel( channel_num )
  return nil
end