next up previous contents
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 up previous contents
Next: 5 Sample playback Up: 4 Module playback Previous: Data types

Petteri Kangaslampi
Sun Mar 1 22:15:08 EET 1998