Platform SDK: DirectX

Using Motifs

A motif is a special kind of pattern in a style intended to be played over 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, 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.

[C++]

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 IDirectMusicStyle::GetMotif method, passing in the following parameters:

The following code example 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. Check for S_OK 
  // specifically because GetMotif() returns S_FALSE if it 
  // does not 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 over
       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 you 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 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.

[Visual Basic]

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 DirectMusicStyle.GetMotif method, passing in 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 DirectMusicStyle.GetMotifName method.

The following code example obtains and plays the first motif in the style:

' style is a DirectMusicStyle.
' perf is the DirectMusicPerformance.
Dim MotifName As String
Dim segMotif As DirectMusicSegment
 
MotifName = style.GetMotifName(0)
Set segMotif = style.GetMotif(MotifName)
Call perf.PlaySegment(segMotif, DMUS_SEGF_SECONDARY, 0)

Note that segMotif 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 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.