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 its shape. 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 sample code 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.

DMUS_CURVE_PMSG *pCurveMsg;
HRESULT hr = g_pPerf->AllocPMsg(sizeof(DMUS_CURVE_PMSG), 
    (DMUS_PMSG**) &pCurveMsg);
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;

g_pPerf->SendPMsg((DMUS_PMSG*) pCurveMsg);

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