sdl.audio
Interface AudioCallBack

public interface AudioCallBack

Consumes handles to audio files and controls how they are mixed and played. An SDLAudioCallback is an interruptable piece of code does the actual management of the individual audio samples. You always need to have a callback method written which mixes your audio data and puts it in the audio stream .

AudioCallBack's role in "playing" sound files

There are two notions of "play" in SDL.

1. Playing an audio stream on an audio device. Controlling the stream of bytes pumped into the audio device is the job of SDLAudio. There is ONE stream per audio device.
   (Analogy: Audio Stream = A river of flowing water. Audio Device = a cave that the river flows into. )
2. Playing (Mixing) files into this stream. Playing audio files involves extracting chuncks of audio data and converting time to an appropriate format. These converted data chuncks then need to be mixed into the current audio stream. This job is supervised by the AudioCallBack.
   (Analogy: Sound files = several individual boats placed on the flowing river. The river will eventually carry them to the cave. AudioPlayBack = the river traffic controller, decides who's allowed on the river )

For review, here is the relationship between the JSDL Audio classes.

• SDLAudio - controls audio device, regulates pause and start of AudioCallBack processing.
• AudioCallBack - registered with SDLAudio. controls mixing and play state of AudioPlay objects
• AudioPlay - wrapper for individual audio file information. contains audio data's play state, WAV file name, play postion, etc

AudioCallBack waits for "unpausing" of audio

Audio playback in SDL is threaded, but started in a "paused" state To allow for time for extra initialization to take place, the audio stream is initialized in a "paused" state. Even though a user instantiates an AudioCallBack, audio playback will remain paused until the user has finished initializing everything.
(Analogy: to start with, the river is always dammed. You must prepare all your boats before undamming the river.)

This "unpausing" is performed manually by invoking a method in the SDLAudio object the callback was orginally registered with. Refer to SDLAudio.pauseAudio(false)
(Analogy: The SDLAudio object controls whether the dam is open).

Once started, the AudioCallBack will begin to "play" audio files. This is done by processing instances of AudioPlay objects in the feedMe method.
In the analogy, the AudioCallBack is a third party. As a "river traffic controller", the AudioCallBack delivers the boats to the river and controls whether they ride the river or dock on the shore for a bit (by controlling the AudioPlay state, and supervising when Mixing happens).

Using AudioCallBack

Clearly, it is a good idea to implement callbacks as SDLEventListeners so they can respond to events from your main application. The following code snippits illustrate this.

    public class ACallBack implements AudioCallBack, 
    				sdl.event.EventListener
 

Let's assume a new AudioPlay object has been created within the callback

    AudioPlay song = null;

    public ACallBack() {
    	song=audio.loadAndConvertSDLAudio("magnum.wav");
    }
    ...

 public void feedMe(int handle, int length, SDLAudio obj)
 {
 	if ( song.getActive() )
 	{
 		int position = song.getPosition();
 		int audioLen = song.getAudioData().getBufferSize();

 		if ( length < (audioLen - position) )
 		{
 			length = audioLen - position;
 			song.setActive(false);
		} 

		SDLAudio.SDLMixAudio(handle,
				song.getAudioData().getBufferHandle(),
				position,length,64);

		song.setPosition(position+length);
		if ( song.getActive()==false )
		{
			song.setPosition(0);
		}
	}	
 }
 

To affect the AudioCallBack from outside its thread, we implemented ACallBack as an event listener. When it receives a keyboard event, it will "play" the song.

  public boolean incomingEvents(SDLCustomEvent event) throws SDLEventException
  {
  	if ( event instanceof SDLKeyboardEvent )
  	{
	  	SDLKeyboardEvent keyboard = (SDLKeyboardEvent)event
	  	if ( keyboard.getKey()==SDLKeyboardEvent.SDLK_p )
  			song.setActive(true);
 		else 
  			song.setActive(false);
  	}
  }
 

See Also:

AudioPlay, SDLAudio, sdl.test.TestAudio

Method Summary

void	feedMe(int handle, int length, SDLAudio obj)

Method Detail

feedMe

public void feedMe(int handle,
                   int length,
                   SDLAudio obj)