AbandonInstrument

Make an instrument available for adoption.

Synopsis

Err AbandonInstrument (Item Instrument)

Description

This function together with AdoptInstrument() form a simple, but efficient, voice allocation system for a single instrument Template. AbandonInstrument() adds an instrument to a pool of unused instruments; AdoptInstrument() allocates instruments from that pool. A Template's pool can grow or shrink dynamically.

Why should you use this system when CreateInstrument() and DeleteInstrument() also do dynamic voice allocation? The answer is that CreateInstrument() and DeleteInstrument() create and delete Items and allocate and free DSP resources. AdoptInstrument() and AbandonInstrument() manage a pool of already existing Instrument Items belonging to a template. Therefore they don't have the overhead of Item creation and DSP resource management, and don't thrash the Item table.

This function stops the instrument, if it was running, and sets its status to AF_ABANDONED (see GetAudioItemInfo() AF_TAG_STATUS). This instrument is now available to be adopted from its Template by calling AdoptInstrument().

Instruments created with the AF_INSF_AUTOABANDON flag set, are automatically put into the AF_ABANDONED state when stopped.

Arguments

Instrument: The item number for the instrument to abandon.

Return Value

The function returns a non-negative value if successful or an error code (a negative value) if an error occurs.

Implementation

SWI implemented in Audio folio V20.

Associated Files

audio.h