^Curves

A curve is a series of MIDI controller changes bringing about a smooth transition from one value to another—for example, volume fade-out or fade-in.

You can execute a curve by sending a single performance message of type DMUS_CURVE_PMSG. This structure enables you to set the start and end values, the duration of the curve, and the shape of the curve. Optionally, you can also set a reset value, which is the value to which the controller will return in case of an invalidation.

The wMeasure, nOffset, bBeat, bGrid, and mtOriginalStart members of the message structure are for information only, and do not affect the timing of the message. They are set in messages sent by DirectMusic Producer segments, and can be used by tools. Applications can normally set these members to 0.

The wMergeIndex member is used to determine whether changes are cumulative or overriding. Two curve messages with different merge indexes are cumulative; otherwise, each message in turn overrides settings made by a previous message.

The bCCData member contains the MIDI controller number for controller changes, and is otherwise ignored. For information on controller numbers, see the MIDI specification.

The following example function causes the volume to fade from its current value to zero over five seconds. If an invalidation occurs during that period, which might happen if another segment replaces the currently playing segment, full volume is restored.

HRESULT SendCurveMsg(IDirectMusicPerformance8* pPerf)
{
  DMUS_CURVE_PMSG *pCurveMsg;
  HRESULT hr;

  if (NULL == pPerf) return E_INVALIDARG;
  hr = pPerf->AllocPMsg(sizeof(DMUS_CURVE_PMSG), 
      (DMUS_PMSG**) &pCurveMsg);
  if (SUCCEEDED(hr))
  {
    ZeroMemory(pCurveMsg, sizeof(DMUS_CURVE_PMSG));
    pCurveMsg->dwSize = sizeof(DMUS_CURVE_PMSG);
    pCurveMsg->rtTime = 0;
    pCurveMsg->dwFlags = DMUS_PMSGF_DX8 | DMUS_PMSGF_REFTIME
                         | DMUS_PMSGF_LOCKTOREFTIME;
    pCurveMsg->dwPChannel = DMUS_PCHANNEL_BROADCAST_PERFORMANCE;
    pCurveMsg->dwType = DMUS_PMSGT_CURVE;
    pCurveMsg->dwGroupID = 0xFFFFFFF;
    pCurveMsg->mtDuration = 5000;
    pCurveMsg->nEndValue = 0;
    pCurveMsg->bCurveShape = DMUS_CURVES_LINEAR;
    pCurveMsg->bCCData = 7;
    pCurveMsg->bFlags = DMUS_CURVE_RESET | DMUS_CURVE_START_FROM_CURRENT;
    pCurveMsg->bType = DMUS_CURVET_CCCURVE ;
    pCurveMsg->mtResetDuration = 0;
    pCurveMsg->nResetValue = 127;
    hr = pPerf->SendPMsg((DMUS_PMSG*) pCurveMsg);
  }
  return hr; 
}

Note   A simpler way to implement volume fading is by using IDirectMusicAudioPath8::SetVolume. This method always uses the linear shape for the curve.