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

# Functions

This section describes all functions available for MIDAS module playback.

## 4.3.1 MIDASfadeMusicChannel

    BOOL MIDASfadeMusicChannel(MIDASmodulePlayHandle playHandle,
        unsigned channel, unsigned fade)

Fades a music channel.

### Input

playHandle
  Module playback handle for the music
channel
  Module channel number to control
fade
  Channel fade value: 64 is normal volume, 0 silence

### Description

This function is used to control the ``fade'' of a music channel. Channel fade acts as a channel-specific master volume: it can be used to quiet down the general volume of the sounds played on the channel, while any volume changes in the music still take effect.

channel if the module channel number for the sounds to control, not a Sound Device channel number. Module channels are numbered from zero upwards.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetMusicVolume

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

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

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

## 4.3.5 MIDASgetPlayStatus

    BOOL MIDASgetPlayStatus(MIDASmodulePlayHandle playHandle,
        MIDASplayStatus *status)

Gets module playback status.

### Input

playHandle
  Module playback handle for the music
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

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

## 4.3.7 MIDASplayModule

    MIDASmodulePlayHandle MIDASplayModule(MIDASmodule module,
        BOOL loopSong)

Starts playing a module.

### Input

module
  Module to be played
loopSong
  TRUE if the song should be looped, FALSE if not

### 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. This function plays the complete module -- to play just a section of the song data, use MIDASplayModuleSection.

Note! Currently, when multiple modules or module sections are played simultaneously, all modules should have the same (BPM) tempo. Otherwise some modules may be played at the wrong tempo. All modules can have different speed setting though.

### Return value

MIDAS module playback handle for the module, or 0 if failed.

### Operating systems

All

### See also

MIDASloadModule, MIDASstopModule, MIDASplayModuleSection

## 4.3.8 MIDASplayModuleSection

    MIDASmodulePlayHandle MIDASplayModuleSection(MIDASmodule module,
        unsigned startPos, unsigned endPos, unsigned restartPos,
        BOOL loopSong)

Starts playing a module section.

### Input

module
  Module to be played
startPos
  Start song position for the section to play
endPos
  End song position for the section to play
restartPos
  Restart position to use when the section loops
loopSong
  TRUE if the playback should be looped, FALSE if not

### Description

This module starts playing a section of 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. Playback will start from the pattern at position startPos, and after the pattern at position endPos has been played, playback will resume from the pattern at restartPos. This function can thus be used to play a section of a module, and a single module can be used to store several songs.

Note! Currently, when multiple modules or module sections are played simultaneously, all modules should have the same (BPM) tempo. Otherwise some modules may be played at the wrong tempo. All modules can have different speed setting though.

### Return value

MIDAS module playback handle for the module, or 0 if failed.

### Operating systems

All

### See also

MIDASloadModule, MIDASstopModule, MIDASplayModule

## 4.3.9 MIDASsetMusicSyncCallback

    BOOL MIDASsetMusicSyncCallback(MIDASmodulePlayHandle playHandle,
        void (MIDAS_CALL *callback)
        (unsigned syncInfo, unsigned position, unsigned row))

Sets the music synchronization callback.

### Input

playHandle
  Module playback handle for the music
callback
  Pointer to the callback function, NULL to disable

### Description

This function sets the music synchronization callback function. It will be called by the MIDAS music player each time a Wxx command is played from a FastTracker 2 or Scream Tracker 3 module, or a Zxx command from an Impulse Tracker module. The function will receive as its arguments the synchronization command infobyte (xx), the current playback position and the current playback row. Setting callback to NULL disables it.

`MIDAS_CALL` is the calling convention used for the callback function -- `__cdecl` for Watcom and Visual C/C++, empty (default) for GCC. Under MS-DOS the function will be called from the MIDAS timer interrupt, so the module containing the callback function must be compiled with the ``SS==DS'' setting disabled (command line argument ``-zu'' for Watcom C, default setting for DJGPP). Under Win32 and Linux the function will be called in the context of the MIDAS player thread.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

## 4.3.10 MIDASsetMusicVolume

    BOOL MIDASsetMusicVolume(MIDASmodulePlayHandle playHandle,
        unsigned volume)

Changes music playback volume.

### Input

playHandle
  Module playback handle for the music
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

## 4.3.11 MIDASsetPosition

    BOOL MIDASsetPosition(MIDASmodulePlayHandle playHandle,
        int newPosition)

Changes module playback position.

### Input

playHandle
  Module playback handle for the music
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

## 4.3.12 MIDASstopModule

    BOOL MIDASstopModule(MIDASmodulePlayHandle playHandle)

Stops playing a module.

### Input

playHandle
  Module playback handle for the music that should be stopped.

### Description

This function stops playing a module that has been played with MIDASplayModule. 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

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