Microsoft DirectX 8.0 (C++)

IDirectMusicTrack8::Play

Causes the track to play. It performs any work that the track must do when the segment is played, such as creating and sending messages.

HRESULT Play(
  void* pStateData, 
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags, 
  IDirectMusicPerformance* pPerf, 
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

Parameters

pStateData
Pointer to state data from the IDirectMusicTrack8::InitPlay method. The format and use of the data is specific to the track.
mtStart
Start time.
mtEnd
End time.
mtOffset
Offset to add to all messages sent to IDirectMusicPerformance8::SendPMsg.
dwFlags
Flags that indicate the state of this call. See DMUS_TRACKF_FLAGS. A value of 0 indicates that this call to Play continues playback from the previous call.
pPerf
Performance used to allocate and send messages.
pSegSt
Segment state that this track belongs to. The IDirectMusicSegmentState8::QueryInterface method can be called to obtain an IDirectMusicGraph8 interface—to call IDirectMusicGraph8::StampPMsg, for instance.
dwVirtualID
Virtual identifier of the track. This value must be put in the dwVirtualTrackID member of any message (see DMUS_PMSG) that is sent by IDirectMusicPerformance8::SendPMsg.

Return Values

If the method succeeds, the return value can be S_OK or DMUS_S_END.

If it fails, the method can return one of the following error values:

DMUS_E_NOT_INIT
E_POINTER

Remarks

If the track is empty, the method returns DMUS_S_END.

Tracks generate messages in a medium-priority thread. You can call time-consuming functions, such as code to stream data from a file, from within a track's Play method. However, be sure to follow the guidelines for safe multithreading.

Requirements

  Header: Declared in dmplugin.h.

See Also

IDirectMusicTrack8::PlayEx