2.4 Using Synchronization Markers

You can use Sound Tools to set synchronization markers in songs. Synchronization markers are meant for use by the programmer, and have no effect on the songs themselves. They make it easier to synchronize audio with events on screen in the application. In this section we explain how to use synchronization markers.

There are two ways of using synchronization markers. The first is to start playback from some place within the song using MusStartSongFromMarker. This function starts the song from an arbitrary synchronization marker.

Start song from specified synchronization marker
Function name: MusStartSongFromMarker
Syntax: musHandle MusStartSongFromMarker(void *addr, s32 marker)
Arguments: addr Address of song
  marker The number of the marker to start from (0 to 255)
Return value: Sound handle value

Be careful, because the system will hang if you specify a synchronization marker that does not exist here.

The other way of using synchronization markers is as signposts for the progress of a song, letting the programmer know where a song is and signaling that it is time to start some other program. To utilize this method you must register a callback function with MusSetMarkerCallback.

Set a callback function for a synchronization marker
Function name: MusSetMarkerCallback
Syntax: void MusSetMarkerCallback(void *callback)
Arguments: callback Address of the callback function
Return value: None

Below is an example of a callback function registered for a synchronization marker:

  
musHandle target_handle;
s32       target_marker;

void CallBackProcess(musHandle handle, s32 marker)     
{
    if(handle==target_handle)
               target_marker = marker;
}

Here target_handle and target_marker are global variables. When the programmer specifies a sound handle in target_handle, the last passed synchronization marker is set in target_marker by the callback function. The callback function is executed on an audio thread that has higher priority than the game thread, so be careful not to overlap processes. You can change the callback function by calling MusSetMarkerCallback again. You can release the callback function by calling this function with NULL set in the arguments.