Cleaning Up

When a task finishes playing a MIDI score and does not need the MIDI environment anymore, it should clean up behind itself. It should free allocated amplitude, disown the audio clock and reset it to its original rate, get rid of the score context and associated data structures, delete any instrument templates previously loaded (thus freeing any instruments associated with them), destroy the MIDI objects created to hold the score, terminate the Juggler, and then close the Math and Audio folios.

To free amplitude allocated for the MIDI mixer, use FreeAmplitude(), which is described in Preparing Instruments." To reset the audio clock use SetAudioRate(). And to disown the audio clock, use DisownAudioClock(). Both clock calls are described in Playing Instruments."

If your task loaded instrument templates using the LoadPIMap() call, you can delete those instrument templates using this call:

int32 UnloadPIMap( ScoreContext *scon )

It accepts a single argument: *scon, a pointer to the score context using the PIMap. When it executes, it deletes all the instrument templates listed in the PIMap. By deleting all the instrument templates, it also deletes any instruments that were created using those templates. If successful, the call returns 0. If unsuccessful, it returns a negative value (an error code).

To delete a Juggler sequence used to store a format 0 MIDI score, use DestroyObject(). To delete a Juggler collection used to store a Format 1 MIDI score (along with all sequences contained in the collection), use this call:

int32 MFUnloadCollection( Collection *ColPtr )

The call accepts one argument: *ColPtr, a pointer to the collection to be deleted. When it executes, it destroys the collection and any sequences defined as part of the collection. If successful, the call returns 0. If unsuccessful, it returns a negative value (an error code).

To delete the mixer instrument template (and the mixer instrument) used to mix the voices of a score context, use this call:

int32 TermScoreMixer( ScoreContext *ScoreCon )

It accepts one argument: *Scorecon, a pointer to the score context using the mixer. When it executes, it deletes the instrument template of the mixer specified by the score context, which also deletes the mixer instrument created using the template. If successful, the call returns 0. If unsuccessful, it returns a negative value (an error code).

To delete a score context, use this call:

int32 DeleteScoreContext( ScoreContext *scon )

It accepts one argument: *scon, a pointer to the score context to be deleted. When it executes, it deletes the score context and all of its attendant data structures, including NoteTrackers. If successful, the call returns 0. If unsuccessful, it returns a negative value (an error code).

To terminate the Juggler, use the TermJuggler() call (see Creating and Playing Juggler Objects"). To close the Math and Audio folios, use the CloseAudioFolio() and CloseMathFolio() calls.