^{Using Motifs}

A motif is a special kind of pattern in a style. A motif is intended to be played over the basic style pattern, typically in response to an interactive event. Unlike other patterns, motifs are always selected and played explicitly by the application. Although a motif can be as complex as any other pattern, even containing variations and multiple instrument parts, usually it is a short, simple musical figure that sounds good against a variety of background patterns. It might also be a sound effect played by a custom DLS instrument or instruments.

All the motifs authored into a style become available to you as soon as you have loaded that style. To get a particular motif ready for playback, call the IDirectMusicStyle8::GetMotif method, passing in the following parameters:

• The name of the motif. You might know this from the documentation for the style, or you can obtain it from an index value by using the IDirectMusicStyle8::EnumMotif method.
• A pointer to receive the IDirectMusicSegment8 interface to the segment object to be created by the method.

The following example function obtains and plays the motif whose name is passed in as pwszMotifName:

HRESULT PlayMotif(IDirectMusicPerformance8* pPerf, 
   IDirectMusicStyle8* pStyle, 
   WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;
  HRESULT hr;
 
  if ((pPerf == NULL) || (pStyle == NULL))
  {
     return E_INVALIDARG;
  }

  // Get the motif segment from the style. Check for S_OK 
  // specifically, because GetMotif() returns S_FALSE if it 
  // does not find the motif.
  
  hr = pStyle->GetMotif(pwszMotifName, &pSeg);

  if (S_OK == hr)
  {
    hr = pPerf->PlaySegment(pSeg,DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                            0, NULL);
    pSeg->Release();
  }
  return hr;
}

Note that pSeg is played as a secondary segment, because a motif is normally played over a primary segment. You cannot play a motif as a primary segment, because it does not have a chord track or band track. If you do want to play a motif against silence, create a primary segment from a style that has only blank patterns, and keep that segment playing while you play the motif.