Next: About this document Up: 4 MIDAS DLL API Previous: 4.1 Constants

# 4.2 Functions

This section describes all function available in the MIDAS DLL API. Not all of these functions are available in all operating systems, so the description for each function also lists the systems in which the function is available.

## 4.2.1 MIDASstartup

    BOOL MIDASstartup(void)

Prepares MIDAS Sound System for initialization and use.

### Input

None.

### Description

This function sets all MIDAS configuration variables to default values and prepares MIDAS for use. It must be called before any other MIDAS function, including MIDASinit and MIDASsetOption is called. After this function has been called, MIDASclose can be safely called at any point and any number of times, regardless of whether MIDAS has been initialized or not. After calling this function, you can use MIDASsetOption to change MIDAS configuration before initializing MIDAS with MIDASinit.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASinit, MIDASclose

## 4.2.2 MIDASinit

    BOOL MIDASinit(void)

Initializes MIDAS Sound System.

### Input

None.

### Description

This function initializes all MIDAS Sound System components, and sets up the DLL API. Apart from configuration functions, this function must be called before any other MIDAS functions are used.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASclose

## 4.2.3 MIDASclose

    BOOL MIDASclose(void)

Uninitializes MIDAS Sound System.

### Input

None.

### Description

This function uninitializes all MIDAS Sound System components, deallocates all resources allocated, and shuts down all MIDAS processing. This function must always be called before exiting under MS-DOS and is also strongly recommended under other operating systems. After this function has been called, no MIDAS function may be called unless MIDAS is initialized again.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 4.2.4 MIDASdetectSD

    BOOL MIDASdetectSD(void)

Attempts to detect the Sound Device to use.

### Input

None.

### Description

This function attempts to detect the Sound Device that should be used. It is called internally by MIDASinit, and should not normally be called by user programs. Note that the function returns TRUE even if it fails to detect a Sound Device.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 4.2.5 MIDASsetOption

    BOOL MIDASsetOption(int option, int value)

Sets a MIDAS option.

### Input

int option
  Option number (see enum MIDASoptions above)
int value
  New value for option

### Description

This function sets a value to a MIDAS option. The different number codes for different options are described above.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 4.2.6 MIDASopenChannels

    BOOL MIDASopenChannels(int numChans)

Opens Sound Device channels for sound and music output.

### Input

int 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. When MIDASplayModule is used to play modules, it will use the last possible channels for the module, so that the first `(numChans - module->numChans)` channels are available for effects and streams.

If this function has not been called before MIDASplayModule, MIDASplayModule will open the channels it needs for module playback. However, if this function has been called, but the number of channels opened 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

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

## 4.2.8 MIDASloadModule

    MIDASmodule MIDASloadModule(char *fileName)

Loads a module file into memory.

### Input

char *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.2.9 MIDASplayModule

    BOOL MIDASplayModule(MIDASmodule module, int numEffectChannels)

Starts playing a module.

### Input

MIDASmodule module
  Module to be played
int 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

## 4.2.10 MIDASstopModule

    BOOL MIDASstopModule(MIDASmodule module)

Stops playing a module.

### Input

MIDASmodule module
  Module that is being played

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

## 4.2.11 MIDASfreeModule

    BOOL MIDASfreeModule(MIDASmodule module)

Deallocates a module.

### Input

MIDASmodule 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.2.12 MIDASstartPlayThread

    BOOL MIDASstartPlayThread(DWORD pollPeriod)

Starts polling MIDAS in a thread.

### Input

DWORD pollPeriod
  Polling period (delay between polling in ms) or 0 for default

### Description

This function starts polling MIDAS Sound System in a separate thread. It creates a new thread that will run in the background, polling MIDAS periodically, with a delay of pollPeriod milliseconds between two successive polls.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32, Linux

### See also

MIDASstopPlayThread

## 4.2.13 MIDASstopPlayThread

    BOOL MIDASstopPlayThread(void)

Stops polling MIDAS in a thread.

### Input

None.

### Description

This function stops polling MIDAS in a thread, and destroys the polling thread. The thread must have been previously created with MIDASstartPlayThread.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32, Linux

### See also

MIDASstartPlayThread

## 4.2.14 MIDASloadRawSample

    MIDASsample MIDASloadRawSample(char *filename, int sampleType,
        int loopSample)

Loads a raw sound effect sample.

### Input

char *filename
  Sample file name
int sampleType
  Sample type, see enum MIDASsampleTypes
int loopSample
  1 if the sample should be looped, 0 if not

### Description

This function loads a sound effect sample into memory and adds it to the Sound Device. The sample file must contain just the raw sample data, and all of it will be loaded into memory. If loopSample is 1, the whole sample will be looped. After the sample has been loaded, it can be played using MIDASplaySample, and it should be deallocated with MIDASfreeSample after it is no longer used.

### Return value

Sample handle if successful, NULL if failed.

### Operating systems

All

### See also

MIDASplaySample, MIDASfreeSample

## 4.2.15 MIDASfreeSample

    BOOL MIDASfreeSample(MIDASsample sample)

Deallocates a sound effect sample.

### Input

MIDASsample sample
  Sample to be deallocated

### Description

This function deallocates a sound effect sample that has been previously loaded with MIDASloadRawSample. It removes the sample from the Sound Device and deallocates the memory used. This function may not be called if the sample is still being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASloadRawSample

## 4.2.16 MIDASsetAutoEffectChannels

    BOOL MIDASsetAutoEffectChannels(unsigned firstChannel,
        unsigned numChannels)

Sets the range of channels that can be used as automatic effect channels.

### Input

unsigned firstChannel
  First channel that can be used
unsigned numChannels
  Number of channels that can be used

### Description

This function is used to set the range of channels that can be used as automatic effect channels by MIDASplaySample. When MIDASplaySample is passed MIDAS_CHANNEL_AUTO as the channel number, it will use one of these automatic channels to play the sound.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 4.2.17 MIDASplaySample

    MIDASsamplePlayHandle MIDASplaySample(MIDASsample sample,
        unsigned channel, int priority, unsigned rate,
        unsigned volume, int panning)

Plays a sound effect sample.

### Input

MIDASsample sample
  The sample that will be played

unsigned channel
  The channel number that is used to play the sample. Use MIDAS_CHANNEL_AUTO to let MIDASplaySample select the channel automatically.

int priority
  Sample playing priority. The higher the value the more important the sample is considered.

unsigned rate
  Initial sample rate for the sample

unsigned volume
  Initial volume for the sample

unsigned panning
  Initial panning position for the sample

### Description

This function is used to play a sound effect sample on a given channel. The sample will receive as initial parameters the values passed as arguments, and playing the sample will be started. If channel is MIDAS_CHANNEL_AUTO, the channel will be selected automatically. The sample playing priority is used to choose the channel the sample will be played on in this case.

This function returns a sample playing handle, that can later be used to stop the sample or change its parameters. This makes it possible to refer to samples without knowing the exact channel they are played on.

### Return value

Sample playing handle if successful, NULL if failed.

### Operating systems

All

### See also

MIDASstopSample, MIDASsetSampleRate, MIDASsetSampleVolume, MIDASsetSamplePanning, MIDASsetSamplePriority

## 4.2.18 MIDASstopSample

    BOOL MIDASstopSample(MIDASsamplePlayHandle sample)

Stops playing a sample.

### Input

MIDASsamplePlayHandle sample
  Sample to be stopped

### Description

This function stops playing a sound effect sample started with MIDASplaySample. Playing the sound will stop, and the channel is freed for other samples to use.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 4.2.19 MIDASsetSampleRate

    BOOL MIDASsetSampleRate(MIDASsamplePlayHandle sample,
        unsigned rate)

Changes the sample rate for a sound effect sample.

### Input

MIDASsamplePlayHandle sample
  Sample to be changed
unsigned rate
  New sample rate for the sample

### Description

This function changes the sample rate for a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 4.2.20 MIDASsetSampleVolume

    BOOL MIDASsetSampleVolume(MIDASsamplePlayHandle sample,
        unsigned volume)

Changes the volume for a sound effect sample.

### Input

MIDASsamplePlayHandle sample
  Sample to be changed
unsigned rate
  New volume for the sample

### Description

This function changes the volume for a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 4.2.21 MIDASsetSamplePanning

    BOOL MIDASsetSamplePanning(MIDASsamplePlayHandle sample,
        int panning)

Changes the panning position of a sound effect sample.

### Input

MIDASsamplePlayHandle sample
  Sample to be changed
int panning
  New panning position for the sample

### Description

This function changes the panning position of a sound effect sample that is being played. See description of enum MIDASpanning for information about the panning position values.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 4.2.22 MIDASsetSamplePriority

    BOOL MIDASsetSamplePriority(MIDASsamplePlayHandle sample,
        int priority)

Changes the playing priority of a sound effect sample.

### Input

MIDASsamplePlayHandle sample
  Sample to be changed
int priority
  New playing priority for the sample

### Description

This function changes the playing priority a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

Next: About this document Up: 4 MIDAS DLL API Previous: 4.1 Constants