GNU Info

(mikmod.info)Library Core Functions

---

Next: Module Player Functions Prev: Function Reference Up: Function Reference

---

Enter node , (file) or (file)node

Library Core Functions
----------------------

MikMod_Active
.............

   `BOOL MikMod_Active(void)'
Description
     This function returns whether sound output is enabled or not.

Result
0
     Sound output is disabled.

1
     Sound output is enabled.

Notes
     Calls to `MikMod_Update' will be ignored when sound output is
     disabled.

See also
     `MikMod_DisableOutput', `MikMod_EnableOutput'.

MikMod_DisableOutput
....................

   `void MikMod_DisableOutput(void)'
Description
     This function stops the sound mixing.

Notes
     Calls to `MikMod_Update' will be ignored when sound output is
     disabled.

See also
     `MikMod_Active', `MikMod_EnableOutput'.

MikMod_EnableOutput
...................

   `BOOL MikMod_EnableOutput(void)'
Description
     This function starts the sound mixing.

Result
0
     Sound mixing is ready.

nonzero
     An error occurred during the operation.

Notes
     Calls to `MikMod_Update' will be ignored when sound output is
     disabled.

See also
     `MikMod_Active', `MikMod_DisableOutput'.

MikMod_Exit
...........

   `void MikMod_Exit(void)'
Description
     This function deinitializes the sound hardware and frees all the
     memory and resources used by MikMod.

See also
     `MikMod_Init', `MikMod_Reset'.

MikMod_GetVersion
.................

   `long MikMod_GetVersion(void)'
Description
     This function returns the version number of the library.

Result
     The version number, encoded as follows: `(maj<<16)|(min<<8)|(rev)',
     where `maj' is the major version number, `min' is the minor version
     number, and `rev' is the revision number.

MikMod_InfoDriver
.................

   `CHAR* MikMod_InfoDriver(void)'
Description
     This function returns a formatted list of the registered drivers
     in a buffer.

Result
     A pointer to a text buffer, or `NULL' if no drivers are registered.

Notes
     The buffer is created with `malloc'; the caller must free it when
     it is no longer necessary.

See also
     `MikMod_RegisterDriver', `MikMod_RegisterAllDrivers'.

MikMod_InfoLoader
.................

   `CHAR* MikMod_InfoLoader(void)'
Description
     This function returns a formatted list of the registered module
     loaders in a buffer.

Result
     A pointer to a text buffer, or `NULL' if no loaders are registered.

Notes
     The buffer is created with `malloc'; the caller must free it when
     it is no longer necessary.

See also
     `MikMod_RegisterLoader', `MikMod_RegisterAllLoaders'.

MikMod_Init
...........

   `BOOL MikMod_Init(CHAR *parameters)'
Description
     This function performs the library initialization, including the
     sound driver choice and configuration, and all the necessary
     memory allocations.

Parameters
parameters
     Optional parameters given to the sound driver. These parameters
     are ignored if the value of `md_device' is zero (autodetection).

Result
0
     Initialization was successful.

nonzero
     An error occurred during initialization.

Notes
     When the initialization fails, the library uses the nosound sound
     driver to let other the other MikMod functions work without
     crashing the application.

See also
     `MikMod_Exit', `MikMod_InitThreads', `MikMod_Reset'.

MikMod_InitThreads
..................

   `BOOL MikMod_InitThreads(void)'
Description
     This function returns whether libmikmod is thread-safe.

Result
0
     The library is not thread-safe.

1
     The library is thread-safe.

Notes
     This function should be called before any call to `MikMod_Lock' or
     `MikMod_Unlock' is made.

See also
     `MikMod_Lock', `MikMod_Unlock'.

MikMod_Lock
...........

   `void MikMod_Lock(void)'
Description
     This function obtains exclusive access to libmikmod's variables.

Notes
     This function locks an internal mutex. If the mutex is already
     locked, it will block the calling thread until the mutex is
     unlocked.
     Every `MikMod_Unlock' call should be associated to a `MikMod_Lock'
     call. To be sure this is the case, we advise you to define and use
     the following macros:
     `#define MIKMOD_LOCK MikMod_Lock();{'
     `#define MIKMOD_UNLOCK }MikMod_Unlock();'
     The function `MikMod_InitThreads' must have been invoked before
     any call to `MikMod_Lock' in made.
See also
     `MikMod_InitThreads', `MikMod_Unlock'.

MikMod_RegisterAllDrivers
.........................

   `void MikMod_RegisterAllDrivers(void)'
Description
     This function registers all the available drivers.

See also
     `MikMod_InfoDriver', `MikMod_RegisterDriver'.

MikMod_RegisterAllLoaders
.........................

   `void MikMod_RegisterAllLoaders(void)'
Description
     This function registers all the available module loaders.

See also
     `MikMod_InfoLoader', `MikMod_RegisterLoader'.

MikMod_RegisterDriver
.....................

   `void MikMod_RegisterDriver(struct MDRIVER* newdriver)'
Description
     This function adds the specified driver to the internal list of
     usable drivers.

Parameters
newdriver
     A pointer to the `MDRIVER' structure identifying the driver.

Notes
     It is safe to register the same driver several times, although it
     will not be duplicated in the list.
     You should register all the drivers you need before calling
     `MikMod_Init'.  If you want to register all the available drivers,
     use `MikMod_RegisterAllDrivers' instead.

See also
     `MikMod_InfoDriver', `MikMod_RegisterAllDrivers'.

MikMod_RegisterErrorHandler
...........................

   `MikMod_handler_t MikMod_RegisterErrorHandler(MikMod_handler_t
newhandler)'
Description
     This function selects the function which should be called in case
     of error.

Parameters
newhandler
     The new error callback function.

Result
     The previous error callback function, or `NULL' if there was none.

Notes
     `MikMod_handler_t' is defined as `void(*function)(void)', this
     means your error function has the following prototype: `void
     MyErrorHandler(void)'
     The error callback function is called when errors are detected,
     but not always immediately (the library has to resume to a stable
     state before calling your callback).

MikMod_RegisterLoader
.....................

   `void MikMod_RegisterLoader(struct MLOADER* newloader)'
Description
     This function adds the specified module loader to the internal
     list of usable module loaders.

Parameters
newloader
     A pointer to the `MLOADER' structure identifying the loader.

Notes
     It is safe to register the same loader several times, although it
     will not be duplicated in the list.
     You should register all the loaders you need before calling
     `Player_Load' or `Player_LoadFP'. If you want to register all the
     available module loaders, use `MikMod_RegisterAllLoaders' instead.
     The 15 instrument module loader (`load_m15') should always be
     registered last.

See also
     `MikMod_InfoLoader', `MikMod_RegisterAllLoaders'.

MikMod_RegisterPlayer
.....................

   `MikMod_player_t MikMod_RegisterPlayer(MikMod_player_t newplayer)'
Description
     This function selects the function which should be used to process
     module playback.

Parameters
newplayer
     The new playback function

Result
     The previous playback function.

Notes
     `MikMod_player_t' is defined as `void(*function)(void)', this means
     your player function has the following prototype: `void
     MyPlayer(void)'
     The player function is called every module tick to process module
     playback.  The rate at which the player function is called is
     controlled by the sound driver, and is computed by the following
     equation:
     (bpm*50)/125 calls per second, which means every 125000/(bpm*50)
     milliseconds. The `bpm' value is the tempo of the module and can
     change from its initial value when requested by the module.
     When changing the playback function, you should make sure that you
     chain to the default MikMod playback function, otherwise you won't
     get module sound anymore....

Example
              MikMod_player_t oldroutine;
          
              void MyPlayer(void)
              {
                  oldroutine();
                  /* your stuff here */
                  ...
              }
          
              main()
              {
                  ...
                  /* Register our player */
                  oldroutine = MikMod_RegisterPlayer(MyPlayer);
                  ...
              }

MikMod_Reset
............

   `BOOL MikMod_Reset(CHAR *parameters)'
Description
     This function resets MikMod and reinitialize the sound hardware.

Parameters
parameters
     Optional parameters given to the sound driver. If you set the
     value of `md_device' to zero (autodetect), these parameters are
     ignored.

Result
0
     Reinitialization was successful.

nonzero
     An error occurred during reinitialization.

Notes
     Use this function when you have changed the global configuration
     variables: `md_device' and `md_mixfreq', or one of the `md_mode'
     flags which require sound reinitialization. Sound playback will
     continue as soon as the driver is ready.

See also
     `MikMod_Exit', `MikMod_Init'.

MikMod_SetNumVoices
...................

   `BOOL MikMod_SetNumVoices(int musicvoices, int samplevoices)'
Description
     This function sets the number of mixed voices which can be used
     for music and sound effects playback.

Parameters
musicvoices
     The number of voices to reserve for music playback.

samplevoices
     The number of voices to reserve for sound effects.

Result
0
     Initialization was successful.

nonzero
     An error occurred during initialization.

Notes
     A value of `-1' for any of the parameters will retain the current
     number of reserved voices.
     The maximum number of voices vary from driver to driver (hardware
     drivers often have a limit of 32 to 64 voices, whereas the
     software drivers handle 255 voices). If your settings exceed the
     driver's limit, they will be truncated.

See also
     `MikMod_Init', `MikMod_Reset'.

MikMod_Unlock
.............

   `void MikMod_Unlock(void)'
Description
     This function relinquishes exclusive access to libmikmod's
     variables.

Notes
     This function unlocks an internal mutex, so that other threads
     waiting for the lock can be resumed.
     Every `MikMod_Unlock' call should be associated to a `MikMod_Lock'
     call. To be sure this is the case, we advise you to define and use
     the following macros:
     `#define MIKMOD_LOCK MikMod_Lock();{'
     `#define MIKMOD_UNLOCK }MikMod_Unlock();'
     The function `MikMod_InitThreads' must have been invoked before
     any call to `MikMod_Unlock' in made.
See also
     `MikMod_InitThreads', `MikMod_Lock'.

MikMod_Update
.............

   `void MikMod_Update(void)'
Description
     This routine should be called on a regular basis to update the
     sound.

Notes
     The sound output buffer is filled each time this function is
     called; if you use a large buffer, you don't need to call this
     routine as frequently as with a smaller buffer, but you get a
     bigger shift between the sound being played and the reported state
     of the player, since the player is always a buffer ahead of the
     playback.
     If you play low quality sound (for example, mono 8 bit 11kHz
     sound), you only need to call this routine a few times per second.
     However, for high quality sound (stereo 16 bit 44kHz), this rate
     increases to a few hundred times per second, but never more, due
     to the minimal buffer size constraint imposed to the sound drivers.
     If you plan on modifying voice information with the `Voice_xx'
     functions, you should do this before calling `MikMod_Update'.

MikMod_strerror
...............

   `char* MikMod_strerror(int errno)'
Description
     This function associates a descriptive message to an error code.

Parameters
errno
     The MikMod error code.

Result
     A pointer to a string describing the error.