mikmod.texi

这是著名的TCPMP播放器在WINDWOWS,和WINCE下编译通过的源程序.笔者对其中的LIBMAD库做了针对ARM MPU的优化. 并增加了词幕功能.

@findex MikMod_SetNumVoices
@findex MikMod_Unlock
@findex MikMod_Update
@vindex md_device
@vindex md_mixfreq
@vindex md_mode
@end iftex

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
@code{MikMod_RegisterAllDrivers}, or register only some of them with
@code{MikMod_RegisterDriver}. If you choose to register the drivers manually,
you must be careful in their order, since @code{MikMod_Init} will try them in
the order you registered them. The @code{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@enddots{}

You can get some printable information regarding the registered drivers with
@code{MikMod_InfoDriver}; don't forget to call @code{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 @code{MikMod_Init}, passing specific information to the driver if
necessary. If you set the variable @code{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
@code{md_device} will be tried.  If your playback settings, in the variables
@code{md_mixfreq} and @code{md_mode}, are not supported by the device,
@code{MikMod_Init} will fail.

You can then choose the number of voices you need with
@code{MikMod_SetNumVoices}, and activate the playback with
@code{MikMod_EnableOutput}.

Don't forget to call @code{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
@code{MikMod_Active} to check if there is still sound playing; in this case,
call @code{MikMod_DisableOutput} to end playback. Then, change your settings
and call @code{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
@code{MikMod_Exit} to leave the sound hardware in a coherent state.

On systems that have pthreads, libmikmod is thread-safe@footnote{Unless you
explicitely choose to create a non thread-safe version of libmikmod at
compile-time.}. You can check this in your programs with the
@code{MikMod_InitThreads} function. If this function returns 1, the library is
thread-safe.

The main benefit of thread-safety is that @code{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 @code{MikMod_Lock} and @code{MikMod_Unlock}
functions. If libmikmod is not thread-safe, these functions are no-ops.

@c ========================================================== Samples
@node Samples and Voice Control, Modules and Player Control, Library Initialization, Using the Library
@section Samples and Voice Control
@iftex
@findex Voice_GetFrequency
@findex Voice_GetPanning
@findex Voice_GetPosition
@findex Voice_GetVolume
@findex Voice_Play
@findex Voice_Stop
@findex Voice_Stopped
@findex Voice_SetFrequency
@findex Voice_SetPanning
@findex Voice_SetVolume
@findex Sample_Free
@findex Sample_Load
@findex Sample_LoadFP
@findex Sample_Play
@end iftex

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

The @code{SAMPLE} structure has a few interesting fields:
@itemize @minus
@item @code{speed} contains the default frequency of the sample.
@item @code{volume} contains the default volume of the sample, ranging from 0 (silence)
to 64.
@item @code{panning} contains the default panning position of the sample.
@end itemize

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
@code{Voice_SetFrequency}, @code{Voice_SetVolume} and @code{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
@code{Voice_GetFrequency}, @code{Voice_GetVolume} and @code{Voice_GetPanning}.

You can also make your sample loop by setting the fields @code{loopstart} and
@code{loopend} and or'ing @code{flags} with @code{SF_LOOP}. To compute your loop
values, the field @code{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@dots{} Test @code{flags} for the value
@code{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 @code{inflags} field.

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

To play your sample, use the @code{Sample_Play} function. This function
will return a voice number which enable you to use the @code{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 @code{SFX_CRITICAL}. You can force it to stop with @code{Voice_Stop}, or you
can force another sample to take over this voice with @code{Voice_Play};
however @code{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
@code{Voice_GetPosition}. If it is zero, either the sample has finished playing
or it is just beginning; use @code{Voice_Stopped} to know.

When you don't need a sample anymore, don't forget to free its memory with
@code{Sample_Free}.

@c ========================================================== Module player
@node Modules and Player Control, Loading Data from Memory, Samples and Voice Control, Using the Library
@section Modules and Player Control
@iftex
@findex MikMod_InfoLoader
@findex MikMod_RegisterAllLoaders
@findex MikMod_RegisterLoader
@findex MikMod_RegisterPlayer
@findex Player_Active
@findex Player_Free
@findex Player_GetChannelVoice
@findex Player_GetModule
@findex Player_Load
@findex Player_LoadFP
@findex Player_LoadTitle
@findex Player_LoadTitleFP
@findex Player_Mute
@findex Player_Muted
@findex Player_NextPosition
@findex Player_Paused
@findex Player_PrevPosition
@findex Player_SetPosition
@findex Player_SetSpeed
@findex Player_SetTempo
@findex Player_SetVolume
@findex Player_Start
@findex Player_Stop
@findex Player_ToggleMute
@findex Player_TogglePause
@findex Player_UnMute
@end iftex

As for the sound drivers, you have to register the module loaders you want to
use for MikMod to be able to load modules. You can either register all the
module loaders with @code{MikMod_RegisterAllLoaders}, or only a few of them with
@code{MikMod_RegisterLoader}. Be careful if you choose this solution, as the
15 instrument MOD loader has to be registered last, since loaders are called in
the order they were register to identify modules, and the detection of this
format is not fully reliable, so other modules might be mistaken as 15
instrument MOD files. 

You can get some printable information regarding the registered loaders with
@code{MikMod_InfoLoader}; don't forget to call @code{free} on the returned
string when you don't need it anymore.

Note that, contrary to the sound drivers, you can register module loaders at
any time, it doesn't matter.

For playlists, you might be interested in knowing the module title first, and
@code{Player_LoadTitle} will give you this information. Don't forget to
@code{free} the returned text when you don't need it anymore.

You can load a module either with @code{Player_Load} and the name of the
module, or with @code{Player_LoadFP} and an open @code{FILE*} pointer. These
functions also expect a maximal number of voices, and a curiosity flag. Unless
you have excellent reasons not to do so, choose a big limit, such as 64 or even
128 for complex Impulse Tracker modules. Both functions return a pointer to an
@code{MODULE} structure, or @code{NULL} if an error occurs.

You'll find some useful information in this structure:
@itemize @minus
@item @code{numchn} contains the number of module ``real'' channels.
@item @code{numvoices} contains the number of voices reserved by the player for
the real channels and the virtual channels (NNA).
@item @code{numpas} and @code{numpat} contain the number of song positions and
song patterns.
@item @code{numins} and @code{numsmp} contain the number of instruments and
samples.
@item @code{songname} contains the song title.
@item @code{modtype} contains the name of the tracker used to create the song.
@item @code{comment} contains the song comment, if it has one.
@item @code{sngtime} contains the time elapsed in the module, in
@math{2^@minus{}10} @dmn{seconds} (not exactly a millisecond).
@item @code{sngspd} and @code{bpm} contain the song speed and tempo.
@item @code{realchn} contains the actual number of active channels.
@item @code{totalchn} contains the actual number of active virtual channels,
i.e. the sum of @code{realchn} and the number of NNA virtual channels.
@end itemize

Now that the module is loaded, you need to tell the module player that you want
to play this particular module with @code{Player_Start} (the player can only
play one module, but you can have several modules in memory). The playback
begins. Should you forget which module is playing, @code{Player_GetModule} will
return it to you.

You can change the current song position with the functions
@code{Player_NextPosition}, @code{Player_PrevPosition} and
@code{Player_SetPosition}, the speed with @code{Player_SetSpeed} and
@code{Player_SetTempo}, and the volume (ranging from 0 to 128) with
@code{Player_SetVolume}.

Playback can be paused or resumed with @code{Player_TogglePause}. Be sure to
check with @code{Player_Paused} that it isn't already in the state you want !

Fine player control is achieved by the functions @code{Player_Mute},
@code{Player_UnMute} and @code{Player_ToggleMute} which can silence or resume
a set of module channels. The function @code{Player_Muted} will return the
state of a given channel. And if you want even more control, you can get the
voice corresponding to a module channel with @code{Player_GetChannelVoice} and
act directly on the voice.

Modules play only once, but can loop indefinitely if they are designed to do so.
You can change this behavior with the @code{wrap} and @code{loop} of the
@code{MODULE} structure; the first one, if set, will make the module restart
when it's finished, and the second one, if set, will prevent the module from
jumping backwards.

You can test if the module is still playing with @code{Player_Active}, and you
can stop it at any time with @code{Player_Stop}. When the module isn't needed
anymore, get rid of it with @code{Player_Free}.


@c ========================================================== Mreaders
@node Loading Data from Memory, ,Modules and Player Control, Using the Library
@section Loading Data from Memory
@iftex
@tindex MREADER
@tindex MWRITER
@findex Player_LoadGeneric
@findex Sample_LoadGeneric
@end iftex

If you need to load modules or sound effects from other places than plain
files, you can use the @code{MREADER} and @code{MWRITER} objects to achieve
this.

The @code{MREADER} and @code{MWRITER} structures contain a list of function
pointers, which emulate the behaviour of a regular @code{FILE *} object. In
fact, all functions which take filenames or @code{FILE *} as arguments are only
wrappers to a real function which takes an @code{MREADER} or an @code{MWRITER}
argument.

So, if you need to load a module from memory, or for a multi-file archive, for
example, all you need is to build an adequate @code{MREADER} object, and use
@code{Player_LoadGeneric} instead of @code{Player_Load} or
@code{Player_LoadFP}. For samples, use @code{Sample_LoadGeneric} instead of
@code{Sample_Load} or @code{Sample_LoadFP}.

@c ========================================================== Reference
@node Library Reference, Index, Using the Library, Top
@chapter Library Reference

This chapter describes in more detail all the functions and variables provided
by the library. @xref{Type Definitions}, for the basic type reference.

@menu
* Variable Reference::
* Structure Reference::
* Error Reference::
* Function Reference::
* Loader Reference::
* Driver Reference::
@end menu

@c ========================================================== Variable reference
@node Variable Reference, Structure Reference, Library Reference, Library Reference
@section Variable Reference

@subsection Error Variables
The following variables are set by the library to return error information.

@table @code
@vindex MikMod_errno
@item int MikMod_errno
When an error occurs, this variable contains the error code.
@xref{Error Reference}, for more information.
@vindex MikMod_critical
@item BOOL MikMod_critical
When an error occurs, this variable informs of the severity of the error. Its
value has sense only if the value of @code{MikMod_errno} is different from zero.
If the value of @code{MikMod_critical} is zero, the error wasn't fatal and the
library is in a stable state. However, if it is nonzero, then the library can't
be used and has reseted itself to the uninitialized state. This often means
that the mixing parameters you choose were not supported by the driver, or that
it doesn't has enough voices for your needs if you called
@code{MikMod_SetNumVoices}.
@end table

@subsection Sound Settings
The following variables control the sound output parameters and their changes
take effect immediately.

@table @code
@vindex md_musicvolume
@item UBYTE md_musicvolume
Volume of the module. Allowed values range from
0 to 128. The default value is 128.
@vindex md_pansep
@item UBYTE md_pansep
Stereo channels separation. Allowed values range
from 0 (no separation, thus mono sound) to 128 (full channel separation). The
default value is 128.
@vindex md_reverb
@item UBYTE md_reverb
Amount of sound reverberation. Allowed values range
from 0 (no reverberation) to 15 (a rough estimate for chaos@dots{}). The