Notification and Event Handling

From time to time, your application may need to respond to a performance event. For example, you might need to know when the end of a segment has been reached, or you might want to synchronize graphics with the beat of the music. You get the desired information by asking DirectMusic to notify you when a certain type of event has taken place.

Note   Performance notifications are not to be confused with DirectSound buffer notifications, which are used only by applications that are streaming wave data directly to or from buffers. See Play Buffer Notification and Capture Buffer Notification.

Specify what types of events you want to be notified of by calling the DirectMusicPerformance8.AddNotificationType method once for each desired type of event. The following code example, in which perf is a DirectMusicPerformance8 object, requests notifications for segment events. The type of event (such as a segment start or a segment end) will be derived later from the notification message.

Call perf.AddNotificationType(DMUS_NOTIFY_ON_SEGMENT)

Notifications are sent in the form of a DMUS_NOTIFICATION_PMSG message type. You can poll for any pending notification messages by calling the DirectMusicPerformance8.GetNotificationPMSG method in Sub Main, or you can have DirectMusic signal an event when a message is pending.

To have DirectMusic signal events, use DirectX8.CreateEvent to obtain an event handle, and then pass this handle to DirectMusicPerformance8.SetNotificationHandle. The module that you pass to CreateEvent must implement the DirectXEvent8 class and must also provide an implementation of the DirectXEvent8.DXCallback method, which is called by DirectMusic whenever an event is signaled.

The following code example sets up notifications for a form module called frmMain:

' DX is a DirectX8 object; perf is a DirectMusicPerformance8 object.
 
Dim hEvent As Long
hEvent = DX.CreateEvent(frmMain)
Call perf.SetNotificationHandle(hEvent)

The form module contains code to intercept any message indicating that the segment has finished playing:

Implements DirectXEvent8
 
Private Sub DirectXEvent8_DXCallback(ByVal eventid As Long)
 
  Dim GotMSG As Boolean
  Dim PMsg As DMUS_NOTIFICATION_PMSG
 
  Do
  GotMSG = gobjDMPerformance.GetNotificationPMSG(PMsg)
  If GotMSG Then
  If PMsg.lNotificationOption = DMUS_NOTIFICATION_SEGEND Then
 
    ' Segment has finished playing, so do something.
    .
    .
    .
  End If
  End If
  Loop Until Not GotMSG
 
End Sub

It isn't necessary to create an event in order to retrieve notification messages in your application's main loop. As long as you have requested notifications by calling the DirectMusicPerformance8.AddNotificationType method, the performance sends messages that can be retrieved by calling DirectMusicPerformance8.GetNotificationPMSG.

More than one message might be waiting when an event is signaled or when you call GetNotificationPMSG in the loop. To be sure of catching all notifications, call GetNotificationPMSG repeatedly until it returns False.

Multiple messages with the same time stamp are not queued in any particular order.