IDirectMusicTrack::InitPlay

The IDirectMusicTrack::InitPlay method is called when a track is ready to start playing. It returns a pointer to state data, which is sent into IDirectMusicTrack::Play and IDirectMusicTrack::EndPlay.

HRESULT InitPlay(
  IDirectMusicSegmentState* pSegmentState,
  IDirectMusicPerformance* pPerformance,
  void** ppStateData,
  DWORD dwVirtualTrackID,
  DWORD dwFlags
);
 

Parameters

pSegmentState

Pointer to the calling IDirectMusicSegmentState.

pPerformance

Pointer to the calling IDirectMusicPerformance.

ppStateData

Address of a variable to receive a pointer to state information. The format and use of the data is specific to the track. The data should be created in the InitPlay method and freed in the IDirectMusicTrack::EndPlay method. The pointer is passed to the IDirectMusicTrack::Play method.

dwVirtualTrackID

Virtual track ID assigned to this track instance.

dwFlags

DMUS_SEGF_FLAGS that control the track's behavior. See Remarks.

Return Values

If the method succeeds, the return value is S_OK.

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

Remarks

It is unnecessary for the track to store the pSegmentState, pPerformance, or dwTrackID parameters, because they are also sent into IDirectMusicTrack::Play.

The dwFlags parameter passes the flags that were handed to the performance in the call to IDirectMusicPerformance::PlaySegment. The track makes decisions on how it should perform based on the DMUS_SEGF_CONTROL and DMUS_SEGF_SECONDARY flags. For example, the tempo track automatically plays the tempo changes only if it is part of a primary segment or a secondary control segment (DMUS_SEGF_SECONDARY is not set, or DMUS_SEGF_CONTROL is set).

A track can return NULL in ppStateData.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusici.h.