Class Rubygame::Sound
In: ext/rubygame/rubygame_event2.c
Parent: Object
      **IMPORTANT**: Sound is only available if Rubygame was compiled
      with SDL_mixer support!

      Sound holds a sound effect, loaded from an audio file (see #load for
      supported formats).

      Sound can #play, #pause/#unpause, #stop, adjust #volume,
      and #fade_out (you can fade in by passing an option to #play).

      Sound can create duplicates (with #dup or #clone) in a memory-efficient
      way -- the new Sound instance refers back to the same audio data,
      so having 100 duplicates of a sound uses only slightly more memory
      than having the first sound. Duplicates can different volume levels,
      too!

Sound includes the Rubygame::NamedResource mixin module, which can perform autoloading of sounds on demand, among other things.

Methods

autoload   fade_out   fading?   initialize_copy   load   new   pause   paused?   play   playing?   stop   stopped?   unpause   volume   volume=  

Public Class methods

Searches each directory in Sound.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Sound instance. If it doesn‘t find the file, returns nil.

See Rubygame::NamedResource for more information about this functionality.

[Source]

/*
 *  call-seq:
 *    Sound.autoload( filename )  ->  Surface or nil
 *
 *  Searches each directory in Sound.autoload_dirs for a file with
 *  the given filename. If it finds that file, loads it and returns
 *  a Sound instance. If it doesn't find the file, returns nil.
 *
 *  See Rubygame::NamedResource for more information about this
 *  functionality.
 *
 */
VALUE rg_sound_autoload( VALUE klass, VALUE namev )
{
  VALUE pathv = rb_funcall( klass, rb_intern("find_file"), 1, namev );

  if( RTEST(pathv) )
  {
    return rg_sound_load( klass, pathv );
  }
  else
  {
    return Qnil;
  }
}

Load the given audio file. Supported file formats are WAV, AIFF, RIFF, OGG (Ogg Vorbis), and VOC (SoundBlaster).

filename:Full or relative path to the file. (String, required)
Returns:The new Sound instance. (Sound)
May raise:SDLError, if the sound file could not be loaded.

[Source]

/*
 *  call-seq:
 *    load( filename )  ->  sound
 *
 *  Load the given audio file.
 *  Supported file formats are WAV, AIFF, RIFF, OGG (Ogg Vorbis), and
 *  VOC (SoundBlaster).
 *
 *  filename::    Full or relative path to the file. (String, required)
 *
 *  Returns::     The new Sound instance. (Sound)
 *  May raise::   SDLError, if the sound file could not be loaded.
 *
 */
static VALUE rg_sound_load( VALUE klass, VALUE filename )
{
        RG_Sound *sound;

        VALUE s = rg_sound_alloc( cSound );

        Data_Get_Struct( s, RG_Sound, sound );

        char *file = StringValuePtr( filename );

        int result = _rg_sound_load( sound, file );

        if( result == -1 )
        {
                rb_raise(eSDLError, "Could not load Sound file '%s': %s",
                                    file, Mix_GetError());
        }

        return s;
}

*NOTE*: Don‘t use this method. Use Sound.load.

This method is not implemented. (In the future, it might be used to create a new Sound with blank audio data.)

Raises NotImplementedError.

[Source]

/*
 *
 *  call-seq:
 *    new
 *
 *  **NOTE**: Don't use this method. Use Sound.load.
 *
 *  This method is not implemented. (In the future, it might be
 *  used to create a new Sound with blank audio data.)
 *
 *  Raises NotImplementedError.
 *
 */
static VALUE rg_sound_new( int argc, VALUE *ARGV, VALUE self )
{
        rb_raise(rb_eNotImpError, "Sound.new is not implemented yet. Use Sound.load to load a sound file.");
}

Public Instance methods

Fade out to silence over the given number of seconds. Once the sound is silent, it is automatically stopped.

Returns:The receiver (self).

*NOTE*: If the sound is currently paused, the fade will start, but you won‘t be able to hear it happening unless you unpause during the fade. Does nothing if the sound is currently stopped.

[Source]

/*
 *  call-seq:
 *    fade_out( fade_time )  ->  self
 *
 *  Fade out to silence over the given number of seconds. Once the sound
 *  is silent, it is automatically stopped.
 *
 *  Returns::     The receiver (self).
 *
 *  **NOTE**: If the sound is currently paused, the fade will start,
 *  but you won't be able to hear it happening unless you #unpause during
 *  the fade. Does nothing if the sound is currently stopped.
 *
 */
static VALUE rg_sound_fadeout( VALUE self, VALUE fade_time )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;
        int fade_ms = (int)(1000 * NUM2DBL(fade_time));

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                Mix_FadeOutChannel( channel, fade_ms );
        }

        return self;
}

True if the Sound is currently fading in or out. See also play and fade_out.

direction:Check if it is fading :in, :out, or :either. (Symbol, required)

[Source]

/*
 *  call-seq:
 *    fading?( direction=:either )  ->  true or false
 *
 *  True if the Sound is currently fading in or out.
 *  See also #play and #fade_out.
 *
 *  direction::  Check if it is fading :in, :out, or :either.
 *               (Symbol, required)
 *
 */
static VALUE rg_sound_fadingp( int argc, VALUE *argv, VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        VALUE vdirection;
        rb_scan_args(argc, argv, "01", &vdirection);
        
        int direction;
        int channel = sound->channel;

        /* If it's not actually on a channel, return false right away. */
        if( !(_rg_sound_channel_check(sound)) )
        {
                return Qfalse;
        }

        if( RTEST(vdirection) )
        {
                if( make_symbol("in") == vdirection )
                {
                        return ( (Mix_FadingChannel(channel) == MIX_FADING_IN)  ? Qtrue : Qfalse );
                }
                
                else if( make_symbol("out") == vdirection )
                {
                        return ( (Mix_FadingChannel(channel) == MIX_FADING_OUT) ? Qtrue : Qfalse );
                }
                
                else if( make_symbol("either") == vdirection )
                {
                        return ( (Mix_FadingChannel(channel) != MIX_NO_FADING)  ? Qtrue : Qfalse );
                }
        }

        /* default */
        return ( (Mix_FadingChannel(channel) != MIX_NO_FADING)  ? Qtrue : Qfalse );
}

Create a copy of the given Sound instance. Much more memory-efficient than using load to load the sound file again.

other:An existing Sound instance. (Sound, required)
Returns:The new Sound instance. (Sound)

*NOTE*: clone and dup do slightly different things; clone will copy the ‘frozen’ state of the object, while dup will create a fresh, un-frozen object.

[Source]

/*
 *  call-seq:
 *    clone( other )  ->  sound
 *    dup( other )  ->  sound
 *
 *  Create a copy of the given Sound instance. Much more memory-efficient
 *  than using #load to load the sound file again.
 *
 *  other::       An existing Sound instance. (Sound, required)
 *
 *  Returns::     The new Sound instance. (Sound)
 *
 *  **NOTE**: #clone and #dup do slightly different things; #clone will copy
 *  the 'frozen' state of the object, while #dup will create a fresh, un-frozen
 *  object.
 *
 */
static VALUE rg_sound_initialize_copy( VALUE self, VALUE other )
{
        RG_Sound *soundA, *soundB;
        Data_Get_Struct(self,  RG_Sound, soundA);
        Data_Get_Struct(other, RG_Sound, soundB);

        _rg_sound_copy( soundA, soundB );

        return self;
}

Pause the Sound. Unlike stop, it can be unpaused later to resume from where it was paused. See also unpause and paused?.

Returns:The receiver (self).

*NOTE*: Does nothing if the sound is not currently playing.

[Source]

/*
 *  call-seq:
 *    pause  ->  self
 *
 *  Pause the Sound. Unlike #stop, it can be unpaused later to resume
 *  from where it was paused. See also #unpause and #paused?.
 *
 *  Returns::     The receiver (self).
 *
 *  **NOTE**: Does nothing if the sound is not currently playing.
 *
 */
static VALUE rg_sound_pause( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                Mix_Pause( channel );
        }

        return self;
}

True if the Sound is currently paused (not playing or stopped). See also playing? and stopped?.

[Source]

/*
 *  call-seq:
 *    paused?  ->  true or false
 *
 *  True if the Sound is currently paused (not playing or stopped).
 *  See also #playing? and #stopped?.
 *
 */
static VALUE rg_sound_pausedp( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                /* Return true if it's "playing" (not stopped), as well as paused. */
                if( Mix_Playing(channel) && Mix_Paused(channel) )
                {
                        return Qtrue;
                }
                else
                {
                        return Qfalse;
                }
        }
        else
        {
                return Qfalse;
        }
}

Play the Sound, optionally fading in, repeating a certain number of times (or forever), and/or stopping automatically after a certain time.

See also pause and stop.

options:Hash of options, listed below. (Hash, required)
  :fade_in::     Fade in from silence over the given number of seconds.
                 (Numeric)
  :repeats::     Repeat the sound the given number of times, or forever
                 (or until stopped) if -1. (Integer)
  :stop_after::  Automatically stop playing after playing for the given
                 number of seconds. (Numeric)
Returns:The receiver (self).
May raise:SDLError, if the sound file could not be played.
    **NOTE**: If the sound is already playing (or paused), it will be stopped

and played again from the beginning.

Example:

  # Fade in over 2 seconds, play 4 times (1 + 3 repeats),
  # but stop playing after 5 seconds.
  sound.play( :fade_in => 2, :repeats => 3, :stop_after => 5 );

[Source]

/*
 *  call-seq:
 *    play( options={} )  ->  self
 *
 *  Play the Sound, optionally fading in, repeating a certain number of
 *  times (or forever), and/or stopping automatically after a certain time.
 *
 *  See also #pause and #stop.
 *
 *  options::     Hash of options, listed below. (Hash, required)
 *
 *    :fade_in::     Fade in from silence over the given number of seconds.
 *                   (Numeric)
 *    :repeats::     Repeat the sound the given number of times, or forever
 *                   (or until stopped) if -1. (Integer)
 *    :stop_after::  Automatically stop playing after playing for the given
 *                   number of seconds. (Numeric)
 *
 *  Returns::     The receiver (self).
 *  May raise::   SDLError, if the sound file could not be played.
 *
 *      **NOTE**: If the sound is already playing (or paused), it will be stopped
 *  and played again from the beginning.
 *
 *  Example:
 *    # Fade in over 2 seconds, play 4 times (1 + 3 repeats),
 *    # but stop playing after 5 seconds.
 *    sound.play( :fade_in => 2, :repeats => 3, :stop_after => 5 );
 *
 */
static VALUE rg_sound_play( int argc, VALUE *argv, VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        VALUE options;
        rb_scan_args(argc, argv, "01", &options);

        int fade_in    =  0;
        int repeats    =  0;
        int stop_after = -1;

        /* If we got some options */
        if( RTEST(options) )
        {
                /* Make sure options is a Hash table */
                if( TYPE(options) != T_HASH )
                {
                        rb_raise(rb_eTypeError, "wrong argument type %s (expected Hash)",
                                 rb_obj_classname(options));
                }

                VALUE temp;

                temp = rb_hash_aref(options, make_symbol("fade_in"));
                if( RTEST(temp) )
                {
                        fade_in = (int)(1000 * NUM2DBL( temp ));
                }

                temp = rb_hash_aref(options, make_symbol("repeats"));
                if( RTEST(temp) )
                {
                        repeats = NUM2INT(temp);
                }

                temp = rb_hash_aref(options, make_symbol("stop_after"));
                if( RTEST(temp) )
                {
                        stop_after = (int)(1000 * NUM2DBL( temp ));
                }

        }

        int result = _rg_sound_play( sound, fade_in, repeats, stop_after );

        if( result == -1 )
        {
                rb_raise(eSDLError, "Could not play Sound: %s", Mix_GetError());
        }

        return self;
}

True if the Sound is currently playing (not paused or stopped). See also paused? and stopped?.

[Source]

/*
 *  call-seq:
 *    playing?  ->  true or false
 *
 *  True if the Sound is currently playing (not paused or stopped).
 *  See also #paused? and #stopped?.
 *
 */
static VALUE rg_sound_playingp( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                /* Return true if it's playing, but not paused. */
                if( Mix_Playing(channel) && !Mix_Paused(channel) )
                {
                        return Qtrue;
                }
                else
                {
                        return Qfalse;
                }
        }
        else
        {
                return Qfalse;
        }
}

Stop the Sound. Unlike pause, the sound must be played again from the beginning, it cannot be resumed from it was stopped.

Returns:The receiver (self).

*NOTE*: Does nothing if the sound is not currently playing or paused.

[Source]

/*
 *  call-seq:
 *    stop  ->  self
 *
 *  Stop the Sound. Unlike #pause, the sound must be played again from
 *  the beginning, it cannot be resumed from it was stopped.
 *
 *  Returns::     The receiver (self).
 *
 *  **NOTE**: Does nothing if the sound is not currently playing or paused.
 *
 */
static VALUE rg_sound_stop( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                Mix_HaltChannel( channel );
        }

        return self;
}

True if the Sound is currently stopped (not playing or paused). See also playing? and paused?.

[Source]

/*
 *  call-seq:
 *    stopped?  ->  true or false
 *
 *  True if the Sound is currently stopped (not playing or paused).
 *  See also #playing? and #paused?.
 *
 */
static VALUE rg_sound_stoppedp( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                /* Return true if it's not playing. */
                if( !Mix_Playing(channel) )
                {
                        return Qtrue;
                }
                else
                {
                        return Qfalse;
                }
        }
        else
        {
                /* If it's not on a channel... it can't be playing! */
                return Qtrue;
        }
}

Unpause the Sound, if it is currently paused. Resumes from where it was paused. See also pause and paused?.

Returns:The receiver (self).

*NOTE*: Does nothing if the sound is not currently paused.

[Source]

/*
 *  call-seq:
 *    unpause  ->  self
 *
 *  Unpause the Sound, if it is currently paused. Resumes from
 *  where it was paused. See also #pause and #paused?.
 *
 *  Returns::     The receiver (self).
 *
 *  **NOTE**: Does nothing if the sound is not currently paused.
 *
 */
static VALUE rg_sound_unpause( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        int channel = sound->channel;

        /* Make sure the sound actually belongs to the channel */
        if( _rg_sound_channel_check(sound) )
        {
                Mix_Resume( channel );
        }

        return self;
}

Return the volume level of the sound. 0.0 is totally silent, 1.0 is full volume.

*NOTE*: Ignores fading in or out.

[Source]

/*
 *  call-seq:
 *    volume  -> vol
 *
 *  Return the volume level of the sound.
 *  0.0 is totally silent, 1.0 is full volume.
 *
 *  **NOTE**: Ignores fading in or out.
 *      
 */
static VALUE rg_sound_getvolume( VALUE self )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        return rb_float_new(sound->volume);
}

Set the new volume level of the sound. 0.0 is totally silent, 1.0 is full volume.

Volume cannot be set while the sound is fading in or out. Be sure to check fading? or rescue from SDLError when using this method.

May raise:SDLError if the sound is fading in or out.

[Source]

/*
 *  call-seq:
 *    volume = new_vol
 *
 *  Set the new #volume level of the sound.
 *  0.0 is totally silent, 1.0 is full volume.
 * 
 *  Volume cannot be set while the sound is fading in or out.
 *  Be sure to check #fading? or rescue from SDLError when
 *  using this method.
 *
 *  May raise::  SDLError if the sound is fading in or out.
 *      
 */
static VALUE rg_sound_setvolume( VALUE self, VALUE volume )
{
        RG_Sound *sound;
        Data_Get_Struct(self,  RG_Sound, sound);

        /* Change channel volume if Sound is currently assigned to a channel */
        if( _rg_sound_channel_check(sound) )
        {
                /* But only if it's not fading right now. */
                if( Mix_FadingChannel(sound->channel) == MIX_NO_FADING )
                {
                        sound->volume = NUM2DBL(volume);
                        Mix_Volume( sound->channel, (int)(MIX_MAX_VOLUME * sound->volume) );
                }
                else
                {
                        rb_raise(eSDLError, "cannot set Sound volume while fading");
                }
        }
        else
        {
                /* Save it for later. */
                sound->volume = NUM2DBL(volume);
        }

        return volume;
}

[Validate]