IDirectMusicPerformance8::PlaySegmentEx

The PlaySegmentEx method begins playback of a segment. The method offers greater functionality than IDirectMusicPerformance8::PlaySegment.

Syntax

HRESULT PlaySegmentEx(
  IUnknown* pSource,
  WCHAR *pwzSegmentName,
  IUnknown* pTransition,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState,
  IUnknown* pFrom, 
  IUnknown* pAudioPath
);

Parameters

pSource

Address of the IUnknown interface of the object to play.

pwzSegmentName

Reserved. Set to NULL.

pTransition

IUnknown interface pointer of a template segment to use in composing a transition to this segment. Can be NULL. See Remarks.

dwFlags

Flags that modify the method's behavior. See DMUS_SEGF_FLAGS.

i64StartTime

Performance time at which to begin playing the segment, adjusted to any resolution boundary specified in dwFlags. The time is in music time unless the DMUS_SEGF_REFTIME flag is set. A value of zero causes the segment to start playing as soon as possible.

ppSegmentState

Address of a variable that receives an IDirectMusicSegmentState interface pointer for this instance of the playing segment. Use QueryInterface to obtain IDirectMusicSegmentState8. The reference count of the interface is incremented. This parameter can be NULL if no segment state pointer is wanted.

pFrom

IUnknown interface pointer of a segment state or audiopath to stop when the new segment begins playing. If it is an audiopath, all segment states playing on that audiopath are stopped. This value can be NULL. See Remarks.

pAudioPath

IUnknown interface pointer of an object that represents the audiopath on which to play, or NULL to play on the default path.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the error values shown in the following table.

Remarks

Do not play segments from untrusted sources. Improperly written segments can make excessive demands on system resources, resulting in degradation of performance or system failure.

Segments should be greater than 250 milliseconds in length.

The boundary resolutions in dwFlags are relative to the primary segment.

If a primary segment is scheduled to play while another primary segment is playing, the first one stops unless you set the DMUS_SEGF_QUEUE flag for the second segment, in which case it plays as soon as the first one finishes.

For more information on the exact start time of segments, see Segment Timing. For information on how the start time of segments can be affected by tempo changes, see Clock Time and Music Time.

If DMUS_SEGF_AUTOTRANSITION is specified in dwFlags and a segment is already playing at i64StartTime and is being interrupted, the method composes a transition between the two segments and plays it before playing pSource. The transition is based on a template provided at pTransition.

The method can be used to play on a performance that does not use audiopaths; that is, one initialized by using IDirectMusicPerformance8::Init. In this case the pAudioPath parameter must be NULL.

When the segment is being cued as a secondary segment, the pFrom parameter can be used to specify the segment state of another secondary segment against which to cue the new segment, as in the following example function.

HRESULT CueOneAfterAnother(IDirectMusicSegment8* pSegmentA,
        IDirectMusicSegmentState8* pSegmentStateB, 
        IDirectMusicPerformance8* pPerf)
{
  HRESULT hr = pPerf->PlaySegmentEx(
    pSegmentA,
    NULL, NULL,
    DMUS_SEGF_QUEUE | DMUS_SEGF_SECONDARY,
    0, NULL,
    pSegmentStateB,
    NULL);
  return hr;
}

In the example, pSegmentStateB plays to the end before stopping because the DMUS_SEGF_QUEUE flag has been set. If you set a different flag such as DMUS_SEGF_MEASURE, pSegmentStateB stops as soon as the boundary is reached and the new secondary segment begins playing.

Requirements

  Header: Declared in dmusici.h.

See Also

• IDirectMusicPerformance8 Interface
• Playing Segments