Using Motifs

A motif is a special kind of pattern in a style intended to be played on top of the basic style pattern, typically in response to an interactive event. Although a motif can be as complex as any other pattern, even containing variations and multiple instrument parts, most often it is a short, simple musical figure that will sound 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, you call the IDirectMusicStyle::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 IDirectMusicStyle::EnumMotif method.
• The number of times the motif should repeat when it is played.
• A pointer to receive the IDirectMusicSegment interface to the segment object that will be created by the method.

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

void PlayMotif(IDirectMusicPerformance* pPerf, 
         IDirectMusicStyle* pStyle, 
         WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;
 
  // Get the motif segment from the style, setting it to play once
  // through (no repeats). Check for S_OK specifically, because
  // GetMotif() returns S_FALSE if it doesn't find the motif.
 
  if (S_OK == pStyle->GetMotif(pwszMotifName, &pSeg))
  {
    /* Play the segment. DMUS_SEGF_BEAT means play on the next beat if
       there is a segment currently playing. DMUS_SEGF_SECONDARY means
       play the segment as a secondary segment, which plays on top of
       the currently playing primary segment. The 0 indicates to
       play now. The final NULL means do not return an 
       IDirectMusicSegmentState* in the last parameter,
       because we don't need to track the state of playback. */
 
    pPerf->PlaySegment(pSeg, 
                       DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                       0, 
                       NULL);
    pSeg->Release();
  }
}
 

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