Method: Rubygame::Sound#play

Defined in:

ext/rubygame/rubygame_sound.c

#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 );

Returns:

• (self)

# File 'ext/rubygame/rubygame_sound.c', line 412

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