# 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`()`