Next: 4 Module playback Up: 3 System control Previous: Data types

# Functions

This section describes all functions available for MIDAS system control. This includes error handling.

## 3.3.1 MIDASallocateChannel

    DWORD MIDASallocateChannel(void)

Allocates a single Sound Device channel.

### Input

None.

### Description

This function allocates a single Sound Device channel, and returns its number. Sound Device are used for all sound playback, but most functions take care of allocating and deallocating channels automatically. If you wish to play a sample on a specific channel, to ensure it won't be replaced by other samples, you'll need to pass MIDASplaySample a specific channel number, and this function is used to allocate those channels.

Channels allocated with this function need to be deallocated with MIDASfreeChannel. Before any channels can be allocated, some sound channels need to be opened with MIDASopenChannels.

### Return value

Channel number for the allocated channel, or MIDAS_ILLEGAL_CHANNEL if failed.

### Operating systems

All

### See also

MIDASopenChannels, MIDASfreeChannel.

## 3.3.2 MIDAScloseChannels

    BOOL MIDAScloseChannels(void)

Closes Sound Device channels opened with MIDASopenChannels.

### Input

None.

### Description

This function closes Sound Device channels that were opened with MIDASopenChannels. Note that you may not use this function to close channels that were opened by MIDASplayModule -- MIDASstopModule will do that automatically.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASopenChannels, MIDASplayModule, MIDASstopModule

## 3.3.3 MIDASfreeChannel

    BOOL MIDASfreeChannel(DWORD channel)

Deallocates a single Sound Device channel.

### Input

channel
  The channel number to deallocate, from MIDASallocateChannel

### Description

This function deallocates a single Sound Device channel that has previously been allocated with MIDASallocateChannel. Any sound playback on the channel should be stopped before deallocating it.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASallocateChannel

## 3.3.4 MIDASgetErrorMessage

    char *MIDASgetErrorMessage(int errorCode)

Gets an error message corresponding to an error code.

### Input

errorCode
  The error code from MIDASgetLastError

### Description

This function returns a textual error message corresponding to a MIDAS error code. It can be used for displaying an error message to the user. Use MIDASgetLastError to determine the error code.

This function can be called at any point after MIDASstartup has been called.

### Return value

Error message string corresponding to the error code.

### Operating systems

All

### See also

MIDASgetLastError

## 3.3.5 MIDASgetLastError

    int MIDASgetLastError(void)

Gets the MIDAS error code for last error.

### Input

None.

### Description

This function can be used to read the error code for most recent failure. When a MIDAS API function returns an error condition, this function can be used to determine the actual cause of the error, and this error can then be reported to the user or ignored, depending on the kind of response needed. Use MIDASgetErrorMessage to get a textual message corresponding to an error code.

This function can be called at any point after MIDASstartup has been called.

### Return value

MIDAS error code for the most recent error.

### Operating systems

All

### See also

MIDASgetErrorMessage

## 3.3.6 MIDASgetVersionString

    char *MIDASgetVersionString(void)

Gets the current MIDAS version as a string.

### Input

None.

### Description

This function can be used to determine the MIDAS version being loaded. It returns a text string description of the version. Version numbers are usually of form ``x.y.z'', where ``x'' is the major version number, ``y'' minor version number and ``z'' patch level. In some occasions, ``z'' can be replaced with a textual message such as ``rc1'' for Release Candidate 1. All MIDAS versions with the major and minor version numbers equal have a compatible DLL API, and can be used interchangeably.

### Return value

MIDAS Sound System version number as a string.

### Operating systems

Win32, Linux

### See also

## 3.3.7 MIDASopenChannels

    BOOL MIDASopenChannels(int numChans)

Opens Sound Device channels for sound and music output.

### Input

numChans
  Number of channels to open

### Description

This function opens a specified number of channels for digital sound and music output. The channels opened can be used for playing streams, samples and modules.

If this function has not been called before MIDASplayModule is called, MIDASplayModule will open the channels it needs for module playback. However, if this function has been called, but the number of available channels is inadequate for the module, MIDASplayModule will return an error and refuse to play the module.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDAScloseChannels, MIDASplayModule

## 3.3.8 MIDASpoll

    BOOL MIDASpoll(void)

Polls the MIDAS sound and music player.

### Input

None.

### Description

This function can be used to poll MIDAS sound and music player manually. It plays music forward, mixes sound data, and sends it to output. When using manual polling, make sure you call MIDASpoll often enough to make sure there are no breaks in sound output -- at least two times during buffer length, preferably four times or more. Under multitasking operating systems such as Win32 and Linux, this may be difficult, so very short buffer sizes can't be used reliably.

Also note that currently this function is not available under MS-DOS. Under MS-DOS, playback is always done in background using the system timer (IRQ 0).

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32, Linux

### See also

MIDASstartBackgroundPlay, MIDASstopBackgroundPlay

## 3.3.9 MIDASremoveTimerCallbacks

    BOOL MIDASremoveTimerCallbacks(void)

Removes the user timer callbacks.

### Input

None.

### Description

This function removes the user timer callbacks set with MIDASsetTimerCallbacks. The callback functions will no longer be called. This function may not be called if MIDASsetTimerCallbacks has not been called before.

It is not necessary to call this function without exiting even if the callbacks have been used -- MIDASclose will remove the callbacks automatically. On the other hand, if the callback functions or rate are changed with MIDASsetTimerCallbacks, this function must be called to remove the previous ones first.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

MS-DOS

### See also

MIDASsetTimerCallbacks

## 3.3.10 MIDASresume

    BOOL MIDASresume(void)

Resumes MIDAS sound playback.

### Input

None.

### Description

This function re-allocates the system audio device to MIDAS, and resumes sound playback, after being suspended with MIDASsuspend. See MIDASsuspend documentation for more information about suspending MIDAS.

Note that this function may fail, if another application has captured the sound output device while MIDAS was suspended.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32

### See also

MIDASsuspend

## 3.3.11 MIDASsetAmplification

    BOOL MIDASsetAmplification(DWORD amplification)

Sets sound output amplification level.

### Input

amplification
  New output amplification level

### Description

This function changes the output amplification level. Amplification can be used to boost the volume of the music, if the sounds played are unusually quiet, or lower it if the output seems distorted.. The amplification level is given as a percentage -- 100 stands for no amplification, 200 for double volume, 400 for quadruple volue, 50 for half volume etc.

MIDAS has some build-in amplification, but the default amplification is designed for situations where most channels have data played at moderate volumes (eg. module playback). If a lot of the channels are empty, or sounds are played at low volumes, adding amplification with this function can help to get the total sound output at a reasonable level. The amplification set with this function acts on top of the default MIDAS amplification, so nothing will be overridden.

This function can be called at any point after MIDASstartup.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

## 3.3.12 MIDASsetTimerCallbacks

    BOOL MIDASsetTimerCallbacks(DWORD rate, BOOL displaySync,
        void (MIDAS_CALL *preVR)(), void (MIDAS_CALL *immVR)(),
        void (MIDAS_CALL *inVR)());

Sets the user timer callback functions and their rate.

### Input

rate
  Timer callback rate, in milliHertz (1000*Hz, 100Hz becomes 100000 etc)
displaySync
  TRUE if the callbacks should be synchronized to display refresh, FALSE if not.
preVR
  preVR callback function pointer or NULL
immVR
  immVR callback function pointer or NULL
inVR
  inVR callback function pointer or NULL

### Description

This function sets the user timer callback functions and their call rate. The functions will be called periodically by the MIDAS timer interrupt, one after another. Any of the callback function pointers may be set to NULL -- the callback is then ignored.

If displaySync is TRUE, the timer system attempts to synchronize the callbacks to the display refresh. In that case, preVR is called just before the Vertical Retrace starts, immVR immediately after it has started, and inVR later during retrace. preVR can then be used for changing the display start address, for example. If display synchronization is used, rate has to be set to the value returned by MIDASgetDisplayRefreshRate.

If displaySync is FALSE, or the timer system is unable to synchronize to display refresh (running under Win95, for example), the functions are simply called one after another: first preVR, then immVR and last inVR. Note that display synchronization is not always possible, and this may happen even if displaySync is set to 1.

In either case, both the preVR and immVR functions have to be kept as short as possible, to prevent timing problems. They should not do more than update a few counters, or set a couple of hardware registers. inVR can take somewhat longer time, and be used for, for example, setting the VGA palette. It should not take more than one quarter of the time between callbacks though.

The most common use for the timer callback functions is to use them for controlling the program speed. There one of the callbacks, usually preVR is simply used for incrementing a counter. This counter then can be used to determine when to display a new frame of graphics, for example, or how many frames of movement needs to be skipped to maintain correct speed.

Note that this function may cause a small break to music playback with some sound cards. Therefore it should not be called more often than necessary. Also, if the application changes display modes, any display-synchronized timer callbacks must be resetted, and a separate refresh rate must be read for each display mode used.

`MIDAS_CALL` is the calling convention used for the callback functions -- `__cdecl` for Watcom C, empty (default) for DJGPP. As the functions will be called from an interrupt, the module containing the callback functions must be compiled with the ``SS==DS'' setting disabled (command line argument ``-zu'' for Watcom C, default setting for DJGPP).

### Return value

TRUE if successful, FALSE if not.

### Operating systems

MS-DOS

### See also

MIDASremoveTimerCallbacks, MIDASgetDisplayRefreshRate

## 3.3.13 MIDASstartBackgroundPlay

    BOOL MIDASstartBackgroundPlay(DWORD pollRate)

Starts playing music and sound in the background.

### Input

pollRate
  Polling rate (number of polls per second), 0 for default

### Description

This function starts playing sound and music in the background. pollRate controls the target polling rate -- number of polls per second. Polling might not be done at actually the set rate, although usually it will be faster. Under Win32 and Linux, a new thread will be created for playing. Under MS-DOS this function is currently ignored, and background playback starts immediately when MIDAS is initialized.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All, but see MS-DOS note above.

### See also

MIDASstopBackgroundPlay, MIDASpoll

## 3.3.14 MIDASstopBackgroundPlay

    BOOL MIDASstopBackgroundPlay(void)

Stops playing sound and music in the background.

### Input

None.

### Description

This function stops music and sound background playback that has been started with MIDASstartBackgroundPlay. Under Win32 and Linux, this function also destroys the thread created for playback. Under MS-DOS this function is currently ignored, and background playback starts immediately when MIDAS is initialized.

If background playback has been started with MIDASstartBackgroundPlay, this function bf must be called before the program exits.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All, but see MS-DOS note above.

### See also

MIDASstartBackgroundPlay, MIDASpoll

## 3.3.15 MIDASsuspend

    BOOL MIDASsuspend(void)

Suspends MIDAS Sound System.

### Input

None.

### Description

This function suspends all MIDAS Sound System output, and releases the system audio device to other programs. Playback can be resumed with MIDASresume. Suspending and resuming MIDAS can be used to change some of the initial configuration options (set with MIDASsetOption) on the fly. In particular, the DirectSound mode and DirectSound window handle can be changed while MIDAS is suspended, and the new values take effect when MDIAS is restarted. Buffer size can also be changed, although this is not recommended. Output mode and mixing rate cannot be changed without completely uninitializing MIDAS.

While MIDAS is suspended, all MIDAS functions can be called normally -- the sound simply is not played. Also, stream, module and sample playback positions do not change while MIDAS is suspended.

Note that MIDASsuspend and MIDASresume are only available in Win32 systems at the moment.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32

### See also

MIDASresume

Next: 4 Module playback Up: 3 System control Previous: Data types