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 in to IDirectMusicTrack::Play and IDirectMusicTrack::EndPlay.

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

Parameters

pSegmentState

Address of the calling IDirectMusicSegmentState interface.

pPerformance

Address of the calling IDirectMusicPerformance interface.

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 can return one of the following error values:

Remarks

The track must store the pSegmentState, pPerformance, or dwTrackID parameters because they are also sent in to IDirectMusicTrack::Play.

The dwFlags parameter passes the flags that were handed to the performance in the call to IDirectMusicPerformance::PlaySegment. The track determines 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.

Requirements

  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.