/*
 *  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;
}