GNU Info

(mikmod.info)Library Initialization

---

Next: Samples and Voice Control Prev: Error Handling Up: Using the Library

---

Enter node , (file) or (file)node

Library Initialization and Core Functions
=========================================

   To initialize the library, you must register some sound drivers
first. You can either register all the drivers embedded in the library
for your platform with `MikMod_RegisterAllDrivers', or register only
some of them with `MikMod_RegisterDriver'. If you choose to register
the drivers manually, you must be careful in their order, since
`MikMod_Init' will try them in the order you registered them. The
`MikMod_RegisterAllDrivers' function registers the network drivers
first (for playing sound over the network), then the hardware drivers,
then the disk writers, and in last resort, the nosound driver.
Registering the nosound driver first would not be a very good idea....

   You can get some printable information regarding the registered
drivers with `MikMod_InfoDriver'; don't forget to call `free' on the
returned string when you don't need it anymore.

   After you've registered your drivers, you can initialize the sound
playback with `MikMod_Init', passing specific information to the driver
if necessary. If you set the variable `md_device' to zero, which is its
default value, the driver will be autodetected, that is, the first
driver in the list that is available on the system will be used;
otherwise only the driver whose order in the list of the registered
drivers is equal to `md_device' will be tried.  If your playback
settings, in the variables `md_mixfreq' and `md_mode', are not
supported by the device, `MikMod_Init' will fail.

   You can then choose the number of voices you need with
`MikMod_SetNumVoices', and activate the playback with
`MikMod_EnableOutput'.

   Don't forget to call `MikMod_Update' as often as possible to process
the sound mixing. If necessary, fork a dedicated process to do this, or
if the library is thread-safe on your system, use a dedicated thread.

   If you want to change playback settings, most of them can't be
changed on the fly. You'll need to stop the playback and reinitialize
the driver. Use `MikMod_Active' to check if there is still sound
playing; in this case, call `MikMod_DisableOutput' to end playback.
Then, change your settings and call `MikMod_Reset'. You're now ready to
select your number of voices and restart playback.

   When your program ends, don't forget to stop playback and call
`MikMod_Exit' to leave the sound hardware in a coherent state.

   On systems that have pthreads, libmikmod is thread-safe(1). You can
check this in your programs with the `MikMod_InitThreads' function. If
this function returns 1, the library is thread-safe.

   The main benefit of thread-safety is that `MikMod_Update' can be
called from a separate thread, which often makes application design
easier. However, several libmikmod global variables are accessible from
all your threads, so when more than one thread need to access libmikmod
variables, you'll have to protect these access with the `MikMod_Lock'
and `MikMod_Unlock' functions. If libmikmod is not thread-safe, these
functions are no-ops.

   ---------- Footnotes ----------

   (1) Unless you explicitely choose to create a non thread-safe
version of libmikmod at compile-time.