Module Rubygame::Mixer
In: ext/rubygame/rubygame_mixer.c

**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.

Methods

Classes and Modules

Class Rubygame::Mixer::Music
Class Rubygame::Mixer::Sample

Constants

AUDIO_U8 = INT2NUM(AUDIO_U8)
AUDIO_S8 = INT2NUM(AUDIO_S8)
AUDIO_U16SYS = INT2NUM(AUDIO_U16SYS)
AUDIO_S16SYS = INT2NUM(AUDIO_S16SYS)

Public Class methods

**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.

[Source]

/* call-seq:
 *  close_audio()
 *
 *  **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.
 */
VALUE rbgm_mixer_closeaudio(VALUE module)
{
  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  Mix_CloseAudio();
  return Qnil;
}

**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 an SDLError if initialization fails.

[Source]

/* call-seq:
 *  driver_name -> string 
 *
 *  **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 an SDLError if initialization fails.
 */

VALUE rbgm_mixer_getdrivername(VALUE module)
{
  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  char driver_name[1024];
  if(SDL_AudioDriverName(driver_name, sizeof(driver_name)) == NULL)
  {     
    rb_raise(eSDLError, "Error fetching audio driver name: %s", SDL_GetError());
  }
  return rb_str_new2(driver_name);
}

**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=().

[Source]

/* call-seq:
 *  #mix_channels()  ->  integer
 *
 *  **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=().
 */
VALUE rbgm_mixer_getmixchans(VALUE module)
{
  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  int result;
  result = Mix_AllocateChannels(-1);

  return INT2NUM(result);
}

**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.

[Source]

/* call-seq:
 *  #mix_channels = num_channels 
 *
 *  **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.
 */
VALUE rbgm_mixer_setmixchans(VALUE module, VALUE channelsv)
{
  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  int desired;
  int allocated;

  desired = NUM2INT(channelsv);
  allocated = Mix_AllocateChannels(desired);

  return INT2NUM(allocated);
}

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

[Source]

/* call-seq:
 *  open_audio( frequency=nil, format=nil, channels=nil, buffer=nil)
 *
 *  **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).
 *
 */
VALUE rbgm_mixer_openaudio(int argc, VALUE *argv, VALUE module)
{

  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  VALUE vfreq, vformat, vchannels, vbuffer;
  int freq = MIX_DEFAULT_FREQUENCY;
  Uint16 format = MIX_DEFAULT_FORMAT;
  int channels = 2;
  int buffer = 1024;

  rb_scan_args(argc, argv, "04", &vfreq, &vformat, &vchannels, &vbuffer);

  if( RTEST(vfreq) )
  {
    freq = NUM2INT(vfreq);
  }

  if( RTEST(vformat) )
  {
    format = NUM2UINT(vformat);
  }

  if( RTEST(vchannels) )
  {
    channels = NUM2INT(vchannels);
  }

  if( RTEST(vbuffer) )
  {
    buffer = NUM2INT(vbuffer);
  }

  if ( Mix_OpenAudio(freq, format, channels, buffer) < 0 )
  {
    rb_raise(eSDLError, "Error initializing SDL_mixer: %s", Mix_GetError());
  }

  return Qnil;
}

Pause playback of a currently-playing mixing channel. Playback can be resumed from the current point with resume. See also stop.

[Source]

/* call-seq:
 *  pause( channel_num )
 *
 *  Pause playback of a currently-playing mixing channel.
 *  Playback can be resumed from the current point with #resume.
 *  See also #stop.
 */
VALUE rbgm_mixchan_pause( VALUE self, VALUE chanv )
{
  Mix_Pause(NUM2INT(chanv));
  return Qnil;
}

**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.

[Source]

/* call-seq:
 *  play(sample, channel_num, repeats )  ->  integer
 *
 *  **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.
 */
VALUE rbgm_mixchan_play( VALUE self, VALUE samplev, VALUE chanv, VALUE loopsv )
{

  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer", "3.0");

  Mix_Chunk* sample;
  int loops, channel, result;

  channel = NUM2INT(chanv);
  Data_Get_Struct( samplev, Mix_Chunk, sample );
  loops = NUM2INT(loopsv);
  
  result = Mix_PlayChannel(channel, sample, loops);

  if ( result < 0 )
  {
    rb_raise(eSDLError, "Error playing sample on channel %d: %s", 
             channel, Mix_GetError());
  }

  return INT2NUM( result );
}

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.

[Source]

/* call-seq:
 *  resume( channel_num )
 *
 *  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.
 *  
 */
VALUE rbgm_mixchan_resume( VALUE self, VALUE chanv )
{
  Mix_Resume(NUM2INT(chanv));
  return Qnil;
}

Stop playback of a playing or paused mixing channel. Unlike pause, playback cannot be resumed from the current point. See also play.

[Source]

/* call-seq:
 *  stop( channel_num )
 *
 *  Stop playback of a playing or paused mixing channel.
 *  Unlike #pause, playback cannot be resumed from the current point.
 *  See also #play.
 */
VALUE rbgm_mixchan_stop( VALUE self, VALUE chanv )
{
  Mix_HaltChannel(NUM2INT(chanv));
  return Qnil;
}

[Validate]