GNU Info

(mikmod.info)Samples and Voice Control

---

Next: Modules and Player Control Prev: Library Initialization Up: Using the Library

---

Enter node , (file) or (file)node

Samples and Voice Control
=========================

   Currently, MikMod only supports uncompressed mono WAV files as
samples. You can load a sample by calling `Sample_Load' with a
filename, or by calling `Sample_LoadFP' with an open `FILE*' pointer.
These functions return a pointer to a `SAMPLE' structure, or `NULL' in
case of error.

   The `SAMPLE' structure has a few interesting fields:
   - `speed' contains the default frequency of the sample.

   - `volume' contains the default volume of the sample, ranging from 0
     (silence) to 64.

   - `panning' contains the default panning position of the sample.

   Altering one of those fields will affect all voices currently
playing the sample. You can achieve the same result on a single voice
with the functions `Voice_SetFrequency', `Voice_SetVolume' and
`Voice_SetPanning'.  Since the same sample can be played with different
frequency, volume and panning parameters on each voice, you can get
voice specific information with `Voice_GetFrequency', `Voice_GetVolume'
and `Voice_GetPanning'.

   You can also make your sample loop by setting the fields `loopstart'
and `loopend' and or'ing `flags' with `SF_LOOP'. To compute your loop
values, the field `length' will be useful. However, you must know that
all the sample length are expressed in samples, i.e. 8 bits for an 8
bit sample, and 16 bit for a 16 bit sample... Test `flags' for the value
`SF_16BITS' to know this.

   Speaking of flags, if you're curious and want to know the original
format of the sample on disk (since libmikmod does some work on the
sample data internally), refer to the `inflags' field.

   If the common forward loop isn't enough, you can play with some
other flags: `SF_BIDI' will make your sample loop "ping pong" (back and
forth), and `SF_REVERSE' will make it play backwards.

   To play your sample, use the `Sample_Play' function. This function
will return a voice number which enable you to use the `Voice_xx'
functions.

   The sample will play until another sample takes over its voice (when
you play more samples than you reserved sound effect voices), unless it
has been flagged as `SFX_CRITICAL'. You can force it to stop with
`Voice_Stop', or you can force another sample to take over this voice
with `Voice_Play'; however `Voice_Play' doesn't let you flag the new
sample as critical.

   Non looping samples will free their voice channel as soon as they
are finished; you can know the current playback position of your sample
with `Voice_GetPosition'. If it is zero, either the sample has finished
playing or it is just beginning; use `Voice_Stopped' to know.

   When you don't need a sample anymore, don't forget to free its
memory with `Sample_Free'.