BASS_MIDI_FontLoad

Preloads presets from a soundfont. 

BOOL BASS_MIDI_FontLoad(
    HSOUNDFONT handle,
    int preset,
    int bank
);

Parameters

handleThe soundfont handle.
presetPreset number to load... -1 = all presets.
bankBank number to load... -1 = all banks.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_CODECA supporting BASS add-on to decode the SF2 samples is not loaded.
BASS_ERROR_FILEFORMAn SFZ sample has an unknown file format. A BASS add-on may be needed to handle it.
BASS_ERROR_NOTAVAILThe soundfont does not contain the requested preset.
BASS_ERROR_MEMThere is insufficient memory.

Remarks

Samples are normally loaded as they are needed while rendering a MIDI stream, which can result in CPU spikes, particularly with packed soundfonts. That generally will not cause any problems, but when smooth/constant performance is critical this function can be used to preload the samples before rendering, so avoiding the need to load them while rendering.

This function will fail (BASS_ERROR_FILEFORM) if an SFZ sample's format is unrecognised but will not fail if a sample is missing, as that may be used to silence other regions in the SFZ file.

When preloading samples to render a MIDI file stream, it is more efficient to use BASS_MIDI_StreamLoadSamples to preload the specific samples that the MIDI stream will use rather than preloading the entire soundfont.

Samples that are preloaded by this function are not affected by automatic compacting via the BASS_CONFIG_MIDI_COMPACT option, but can be compacted/unloaded manually with BASS_MIDI_FontCompact and BASS_MIDI_FontUnload.

It is possible to only partially preload presets to save time and memory with BASS_MIDI_FontLoadEx.

See also

BASS_MIDI_FontCompact, BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPreset, BASS_MIDI_FontInit, BASS_MIDI_FontLoadEx, BASS_MIDI_FontUnload, BASS_MIDI_StreamLoadSamples