PurgeScoreInstrument

Purges an unused instrument from a ScoreContext.

Synopsis

Err PurgeScoreInstrument( ScoreContext *scon, uint8 Priority, int32 MaxLevel )

Description

This function purges an unused instrument from a ScoreContext. This call, coupled with the scon_PurgeHook allows an application to share DSP resources with the ScoreContext.

Arguments

scon
A pointer to a ScoreContext data structure controlling playback.
Priority
The maximum instrument priority to purge for instruments that are still playing (in the range of 0 to 200). Instruments of higher priority that this may be purged if they have stopped playing.
MaxLevel
The maximum activity to purge (i.e. AF_ABANDONED, AF_STOPPED, AF_RELEASED, AF_STARTED).

Return Value

This function returns a positive value if an instrument was actually purged, zero if no instrument matching the specifications could be purged, or a negative error code on failure.

Examples

This code fragment can be used to free the DSP resources used by all
instruments that have finished playing:
{
    int32 result;
        * loop until function returns no voice purged or error *
    while ( (result = PurgeScoreInstrument (scon, SCORE_MAX_PRIORITY,
                                            AF_STOPPED)) > 0 ) ;
        * catch error *
    if (result < 0) ...
}

Caveats

This function deletes items that are created by StartScoreNote(). Frequent use of this function and StartScoreNote() can consume the item table. If you simply want to stop a score note in it's tracks for later use with the same channel, use StopScoreNote() instead. It merely stops instruments and doesn't delete them.

Implementation

Library call implemented in music.lib V20.

Associated Files

score.h, music.lib

See Also

StopScoreNote()