Next: 3.4 Using samples Up: 3 Using MIDAS Digital Previous: 3.2 Uninitializing MIDAS

# 3.3 Using modules

Digital music modules provide an easy to use and space-efficient method for storing music and more complicated sound effects. MIDAS Digital Audio System supports Protracker (.mod), Scream Tracker 3 (.s3m), FastTracker 2 (.xm) and Impulse Tracker (.it) modules. All types of modules are used through the same simple API functions described in the subsections below.

## 3.3.1 Loading and deallocating modules

Loading modules with MIDAS Digital Audio System is very simple, just call MIDASloadModule, giving as an argument the name of the module file. MIDASloadModule returns a module handle of type MIDASmodule, which can then be used to refer to the module. After the module is no longer used, it should be deallocated with MIDASfreeModule.

## 3.3.2 Playing modules

Modules that have been loaded into memory can be played by calling MIDASplayModule. MIDASplayModule takes as an argument the module handle for the module, and a boolean flag that indicates whether or not the module playback should loop or not. It returns a module playback handle of type MIDASmodulePlayHandle that can be used to refer to the module as it is being played.

MIDASplayModuleSection can be used to play just a portion of the module. A single module could, for example, contain several different songs, and MIDASplayModuleSection can be used to select which one of them to play.

MIDAS is also capable of playing several modules simultaneously, or even the same module several times from different positions. There are some limitations, however, see MIDASplayModule documentation for details. This can be useful for using module sections as sound effects, or fading between two modules.

Module playback can be stopped by calling MIDASstopModule, passing it as an argument the module playback handle returned by MIDASplayModule.

## 3.3.3 Controlling module playback

Although typically module playback just proceeds without user intervention, it is also possible to control the playback of the module. MIDASsetPosition can be used to change the current playing position, MIDASsetMusicVolume to set the master volume of the music, and MIDASfadeMusicChannel to fade individual music channels in or out. All of these functions require as their first argument the module playing handle from MIDASplayModule.

## 3.3.4 Getting module information

In MIDAS Digital Audio System, it is possible to query information about a module or the status of module playback. This information can be used to update an user interface, or synchronize the program operation to the music playback.

Basic information about the module, such as its name, is available by calling MIDASgetModuleInfo. The function requires as an argument a module handle returned by MIDASloadModule, and a pointer to a MIDASmoduleInfo structure, which it then will fill with the module information. A similar function, MIDASgetInstrumentInfo, is available for reading information about individual instruments in the module.

The current status of the playback of a module can be read with MIDASgetPlayStatus. It is passed a module playback handle from MIDASplayModule, and a pointer to a MIDASplayStatus structure, which it will then fill with the playback status information. The playback status information includes the current module playback position, pattern number in that position and the current playback row, as well as the most recent music synchronization command infobyte.

MIDAS Digital Audio System also supports a music synchronization callback function, which will be called each time the player encounters a music synchronization command. The synchronization command is Wxx for Scream Tracker 3 and FastTracker 2 modules, and Zxx for Impulse Tracker modules. The callback can be set or removed with the function MIDASsetMusicSyncCallback. As the music synchronization callback is called in MIDAS player context, it should be kept as short and simple as possible, and it may not call MIDAS functions.

Next: 3.4 Using samples Up: 3 Using MIDAS Digital Previous: 3.2 Uninitializing MIDAS