BASS_Mixer_ChannelSetEnvelope

Sets an envelope to modify the sample rate, volume or pan of a mixer source channel over a period of time. 

BOOL BASS_Mixer_ChannelSetEnvelope(
    DWORD handle,
    DWORD type,
    BASS_MIXER_NODE *nodes,
    DWORD count
);

Parameters

handleThe channel handle.
typeThe attribute to modify with the envelope. One of the following.
BASS_MIXER_ENV_FREQSample rate.
BASS_MIXER_ENV_VOLVolume.
BASS_MIXER_ENV_PANPanning/balance.
BASS_MIXER_ENV_LOOPLoop the envelope. This is a flag and can be used in combination with any of the above.
BASS_MIXER_ENV_REMOVERemove the source from the mixer at the end of the envelope. This is a flag and can be used in combination with any of the above.
nodesThe array of envelope nodes, which should have sequential positions.
countThe number of elements in the nodes array... 0 = no envelope.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not a mixer source.
BASS_ERROR_ILLTYPEtype is not valid.
BASS_ERROR_NOTAVAILThe BASS_MIXER_ENV_PAN envelope is not available when matrix mixing is enabled.

Remarks

Envelopes are applied on top of the channel's attributes, as set via BASS_ChannelSetAttribute. In the case of BASS_MIXER_ENV_FREQ and BASS_MIXER_ENV_VOL, the final sample rate and volume is a product of the channel attribute and the envelope. While in the BASS_MIXER_ENV_PAN case, the final panning is a sum of the channel attribute and envelope.

BASS_Mixer_ChannelSetEnvelopePos and BASS_Mixer_ChannelGetEnvelopePos can be used to set and get the current envelope position. A BASS_SYNC_MIXER_ENVELOPE sync can be set via BASS_Mixer_ChannelSetSync to be informed of when an envelope ends. This function can be called again from such a sync, in order to set a new envelope to follow on from the old one.

Any previous envelope of the same type is replaced by the new envelope. A copy is made of the nodes array, so it does not need to persist beyond this function call.

Example

Set an envelope to bounce the pan position between left and right every 4 seconds. 
BASS_MIXER_NODE nodes[4];
nodes[0].pos = 0;
nodes[0].val = 0; // start at centre
nodes[1].pos = BASS_ChannelSeconds2Bytes(mixer, 1);
nodes[1].val = -1; // full left after 1 second
nodes[2].pos = BASS_ChannelSeconds2Bytes(mixer, 3);
nodes[2].val = 1; // full right after 3 seconds
nodes[3].pos = BASS_ChannelSeconds2Bytes(mixer, 4);
nodes[3].val = 0; // back at centre after 4 seconds
BASS_Mixer_ChannelSetEnvelope(channel, BASS_MIXER_ENV_PAN | BASS_MIXER_ENV_LOOP, nodes, 4); // apply the envelope, looped

See also

BASS_Mixer_ChannelGetEnvelopePos, BASS_Mixer_ChannelSetEnvelopePos, BASS_MIXER_NODE structure