Method: Rubygame::Music#play

Defined in:
lib/rubygame/music.rb

#play(options = {}) ⇒ Object

call-seq:

play( options={:fade_in => 0, :repeats => 0, :start_at => 0} )

Play the Music, optionally fading in, repeating a certain number of times (or forever), and/or starting at a certain position in the song.

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. Default: 0. (Numeric, optional)

:repeats

Repeat the music the given number of times, or forever (or until stopped) if -1. Default: 0. (Integer, optional)

:start_at

Start playing the music at the given time in the song, in seconds. Default: 0. (Numeric, optional) NOTE: Non-zero start times only work for OGG and MP3 formats! Please refer to #jump.

Returns

The receiver (self).

May raise

SDLError, if the audio device could not be opened, or if the music file could not be played, or if you used :start_at with an unsupported format.

NOTE: Only one music can be playing at once. If any music is already playing (or paused), it will be stopped before playing the new music.

Example:

# Fade in over 2 seconds, play 4 times (1 + 3 repeats),
# starting at 60 seconds since the beginning of the song.
music.play( :fade_in => 2, :repeats => 3, :start_at => 60 );



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/rubygame/music.rb', line 184

def play( options={} )

  fade_in  = (options[:fade_in]  or 0)
  repeats  = (options[:repeats]  or 0)
  start_at = (options[:start_at] or 0)


  fade_in =
    if( fade_in < 0 )
      raise ArgumentError, ":fade_in cannot be negative (got %.2f)"%fade_in
    elsif( fade_in < 0.05 )
      # Work-around for a bug with SDL_mixer not working with small
      # non-zero fade-ins
      0
    else
      (fade_in * 1000).to_i
    end


  repeats =
    if( repeats < -1 )
      raise( ArgumentError,
             ":repeats cannot be negative, except -1 (got #{repeats})" )
    elsif( repeats > -1 )
      # Adjust so repeats means the same as it does for Sound
      (repeats + 1).to_i
    else
      -1
    end


  start_at =
    if( start_at < 0 )
      raise( ArgumentError,
             ":start_at cannot be negative, (got %.2f)"%start_at )
    else
      start_at.to_f
    end


  Rubygame.open_audio


  # Doing a little restart dance to please the SDL_mixer gods.
  SDL::Mixer.PlayMusic( @struct, 0 )
  SDL::Mixer.HaltMusic()

  # Set music channel volume before we play
  SDL::Mixer.VolumeMusic( (SDL::Mixer::MAX_VOLUME * @volume).to_i )


  @repeats = repeats

  result = SDL::Mixer.FadeInMusicPos( @struct, repeats, fade_in, start_at )

  if( result == -1 )
    raise Rubygame::SDLError, "Could not play Music: #{SDL.GetError()}"
  end

  self.class.__current_music = self

  return self

end