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.

### Input

fileName
  Module file name

### Description

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

### See also

MIDASplayModule, MIDASfreeModule

## 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

### See also

MIDASloadModule, MIDASstopModule, MIDASopenChannels

MIDASstopModule

    BOOL MIDASstopModule(MIDASmodule module)

Stops playing a module.

### 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

### See also

MIDASplayModule, MIDASopenChannels

## 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

### See also

MIDASloadModule

## 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

### See also

MIDASplayModule, MIDASplayStatus

## 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

### See also

MIDASplayModule, MIDASgetPlayStatus, MIDASgetModuleInfo

## 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

### See also

## 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

### See also

MIDASplayModule, MIDASmoduleInfo

## 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

### See also

MIDASplayModule, MIDASgetModuleInfo, MIDASmoduleInfo

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