FreeChannelInstruments

Frees all of a MIDI channel's instruments.

Synopsis

Err FreeChannelInstruments( ScoreContext *scon,int32 Channel )

Description

This function frees all instruments currently allocated to a MIDI channel of a score context, an action that abruptly stops any notes the instruments may be playing.

This call is useful because allocated instruments may accumulate in a channel as dynamic voice allocation creates instruments to handle simultaneous note playback within the channel. As notes stop, the instruments used to play the notes are abandoned, but not freed, remaining in existence so they can be used to immediately play incoming notes. These abandoned instruments use up system resources.

If a task knows that it will not play notes in a MIDI channel for a period of time, it can use FreeChannelInstruments() to free all allocated instruments dedicated to a channel. This frees all of the system resources used to support those instruments, making them available for other audio jobs. When notes are played in a channel after all of its voices are freed, dynamic voice allocation immediately allocates new instruments to play those notes.

Arguments

scon: Pointer to a ScoreContext data structure.

Channel: The number of the MIDI channel for which to free instruments.

Return Value

This macro returns 0 if successful or an error code (a negative value) if an error occurs.

Implementation

Library call implemented in music.lib V20.

Associated Files

score.h, music.lib