FMUSIC_LoadSongEx

##### [API function]

## FMUSIC_LoadSongEx

To load a module or bank with a given filename. FMUSIC Supports loading of
- .MOD (protracker/fasttracker modules)
- .S3M (screamtracker 3 modules)
- .XM (fasttracker 2 modules)
- .IT (impulse tracker modules)
- .MID (MIDI files)
- .RMI (MIDI files)
- .SGT (DirectMusic segment files)
- .FSB (FMOD Sample Bank files)

FMUSIC_MODULE * F_API FMUSIC_LoadSongEx(
const char *name_or_data,
int offset,
int length,
unsigned int mode,
const int *samplelist,
int samplelistnum
);

### Parameters

name_or_data | Name of song or pointer to data containing song to load (if loading from memory and not file). On PlayStation 2 data must be 16 byte aligned if loading from memory.
offset | Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening.
length | Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading.
mode | Mode for opening song. With module files, only FSOUND_LOADMEMORY, FSOUND_NONBLOCKING, FSOUND_LOOP_NORMAL, or FSOUND_LOOP_OFF are supported. For FSB files, FSOUND_2D, FSOUND_HW3D, FSOUND_FORCEMONO also work.
samplelist | Optional. Pointer to array of sample indicies to load. Leave as NULL if you want all samples to be loaded (default behaviour). See Remarks for more on this.
samplelistnum | Optional. Number of entries in the samplelist array.

### Return Value

On success, a FMUSIC_MODULE handle is returned.
On failure, NULL is returned.

### Remarks

Loading a song from a memory handle is dangerous in one respect, if the data is corrupted or truncated, then FMUSIC could crash internally trying to load it.
On PlayStation 2 the data and length pointer must be 16 byte aligned for DMA purposes.
The samplelist and samplelistnum parameters are useful for limiting the amount of data fmod loads. This feature is for the FSB format only. It is especially useful if you have a bank of sounds and want to randomize the loading a bit by telling which sounds to load with random values, and consequently which not to load.
On PlayStation 2, samplelistnum has a limit of 1536 entries.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation2, GameCube

### See Also

FMUSIC_FreeSong , FMUSIC_LoadSong

This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.
Generated Thu Dec 15 17:31:26 2005 by SourceDoc v0.10, the automated source code documenter.