IDirectMusicSegment::InitPlay

The IDirectMusicSegment::InitPlay method is called by the performance when the segment is about to be played.

HRESULT InitPlay(
  IDirectMusicSegmentState** ppSegState, 
  IDirectMusicPerformance* pPerformance,
  DWORD dwFlags
);
 

Parameters

ppSegState

Address of a variable to receive a pointer to the IDirectMusicSegmentState interface, which is created in response to this method call and is used to hold state data. It is returned with a reference count of 1, so a call to its Release method will fully release it.

pPerformance

Address of the IDirectMusicPerformance interface. This is needed by the segment and segment state in order to call methods on the performance object.

dwFlags

DMUS_SEGF_FLAGS that modify 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

When a segment is cued to play, it must create a state structure to store all variables that track the state of one individual performance of the segment. The InitPlay method is called by the performance engine when the segment is about to be played. The segment, in turn, collects state objects for each of the tracks, by calling their IDirectMusicTrack::InitPlay methods, and stores it all in a segment state object, accessed by using the IDirectMusicSegmentState interface. Later, when the segment is finished playing, the performance engine frees it by calling the Release method.

When the segment creates the IDirectMusicSegmentState, it should give the segment state a copy of pPerformance.

Note that a newly created segment state starts with its seek point set to 0.

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).

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.