Next: 4 Sample playback Up: 3 Module playback Previous: Data types

Functions

This section describes all functions available for MIDAS module playback.

3.3.1 MIDASloadModule

MIDASmodule MIDASloadModule(char *fileName)

Loads a module file into memory.

This function loads a module file into memory. It checks the module format based on the module file header, and invokes the correct loader to load the module into memory in GMPlayer internal format. The module can then be played using MIDASplayModule, and deallocated from memory with MIDASfreeModule.

Return value

Module handle if successful, NULL if not.

Operating systems

All

3.3.2 MIDASplayModule

BOOL MIDASplayModule(MIDASmodule module, int numEffectChannels)

Starts playing a module.

Input

module: Module to be played
numEffectChannels: Number of sound channels to leave open for effects

Description

This functions starts playing a module that has been previously loaded with MIDASloadModule. If channels have not been previously opened using MIDASopenChannels, this function opens the channels necessary to play the module, and if numEffectChannels is nonzero, it opens additional channels for sound effects. The module is always played on the last possible channels, so the first numEffectChannels are available for effects and streams.

Note! Currently only one module can be played at a time.

Return value

TRUE if successful, FALSE if not.

Operating systems

All

Input

module: Module that is being played

Description

This function stops playing a module that has been played with MIDASplayModyle. If the channels were opened automatically by MIDASplayModule, this function will close them, but if they were opened manually with MIDASopenChannels, they will be left open.

Return value

TRUE if successful, FALSE if not.

Operating systems

All

3.3.3 MIDASfreeModule

BOOL MIDASfreeModule(MIDASmodule module)

Deallocates a module.

Input

module: Module that should be deallocated

Description

This function deallocates a module loaded with MIDASloadModule. It should be called to free unused modules from memory, after they are no longer being played, to avoid memory leaks.

Return value

TRUE if successful, FALSE if not.

Operating systems

All

3.3.4 MIDASgetPlayStatus

BOOL MIDASgetPlayStatus(MIDASplayStatus *status)

Gets module playback status.

Input

status: Pointer to playback status structure where the status will be written.

Description

This function reads the current module playback status, and writes it to *status. The user needs to pass it a valid pointer to a MIDASplayStatus structure, which will be updated.

Return value

TRUE if successful, FALSE if not. The current playback status is written to *status.

Operating systems

All

3.3.5 MIDASsetPosition

BOOL MIDASsetPosition(int newPosition)

Changes module playback position.

Input

newPosition: New playback position

Description

This function changes the current module playback position. The song starts at position 0, and the length is available in the MIDASmoduleInfo structure. You should make sure that position lies inside those limits. To skip backward or forward a single position, first read the current position with MIDASgetPlayStatus, and substract or add one to the current position.

Return value

TRUE if successful, FALSE if not.

Operating systems

All

3.3.6 MIDASsetMusicVolume

BOOL MIDASsetMusicVolume(unsigned volume)

Changes music playback volume.

Input

volume: New music playback volume (0-64)

Description

This function changes the music playback master volume. It can be used, for example, for fading music in or out smoothly, or for adjusting the music volume relative to sound effects. The volume change only affects the song that is currently being played -- if a new song is started, the volume is reset. The default music volume is 64 (the maximum).

Return value

TRUE if successful, FALSE if not.

Operating systems

All

3.3.7 MIDASgetModuleInfo

BOOL MIDASgetModuleInfo(MIDASmodule module,
    MIDASmoduleInfo *info)

Gets information about a module.

Input

module: Module handle for the module
info: Pointer to a module info structure where the information willl be written

Description

This function returns information about a module, including the module name and the number of channels used. The user needs to pass it a valid pointer to a MIDASmoduleInfo structure (*info), where the information will be written.

Return value

TRUE if successful, FALSE if not. The module information is written to *info.

Operating systems

All

3.3.8 MIDASgetInstrumentInfo

BOOL MIDASgetInstrumentInfo(MIDASmodule module,
    int instNum, MIDASinstrumentInfo *info)

Gets information about an instrument in a module.

Input

module: Module handle for the module
instNum: Instrument number
info: Pointer to an instrument info structure where the information willl be written

Description

This function returns information about an instrument in a module, including the instrument name. The user needs to pass it a valid pointer to a MIDASinstrumentInfo structure (*info), where the information will be written. You should ensure that instNum is a valid instrument number. Instrument numbers start from 0, although trackers traditionally number them from 1, and you can useMIDASgetModuleInfo to get the number of instruments available in a module.

Return value

TRUE if successful, FALSE if not. The instrument information is written to *info.

Operating systems

All