mikmod.texi

tcpmp.src.0.72RC1 优秀的多媒体播放器TCPMP的源代码

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename mikmod.info
@settitle MikMod sound library
@c %**end of header
@ignore

  MikMod Sound Library Documentation

  $Id: mikmod.texi,v 1.2 2004/01/27 18:59:23 raph Exp $

@end ignore
@c comment this during modifications
@finalout
@c @iftex
@c @afourpaper
@c @end iftex

@syncodeindex tp vr
@set documentation-version 1.3
@set documentation-date February 2004
@set library-version 3.1.12
@set authorname Miodrag Vallat
@set authoraddress miod@@mikmod.org

@c ========================================================== Copyright (info)
@ifinfo
Copyright @copyright{} 1998, 1999, 2000, 2001, 2002 Miodrag Vallat and others --- see
file AUTHORS for complete list.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Library General Public License for more details.
 
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@end ifinfo

@c ========================================================== Title page
@titlepage
@title{MikMod Sound Library}
@subtitle Documentation edition @value{documentation-version}
@subtitle @value{documentation-date}
@author @value{authorname}
@author (@code{@value{authoraddress}})
@page
@vskip 0pt plus 1filll

@c ========================================================== Copyright (TeX)
Copyright @copyright{} 1998, 1999, 2000, 2001, 2002 Miodrag Vallat and others --- see
file AUTHORS for complete list.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Library General Public License for more details.
 
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@end titlepage

@c ========================================================== File information
@ifnottex
@dircategory Programming
@direntry
* MikMod: (mikmod).            MikMod Sound Library.
@end direntry

@c ========================================================== Top node
@node Top, Introduction, (dir), (dir)
@top MikMod Sound Library
@w{This manual documents the MikMod Sound Library, version @value{library-version}.}

@menu
* Introduction::          What is MikMod ?
* Tutorial::              Your first steps with MikMod.
* Using the Library::     A thematic presentation of the library.
* Library Reference::     Detailed description of the functions and variables.
* Index::
@end menu
@end ifnottex

@c ========================================================== Introduction
@node Introduction, Tutorial, Top, Top
@chapter Introduction

The MikMod sound library is an excellent way for a programmer to add music
and sound effects to an application. It is a powerful and flexible library,
with a simple and easy-to-learn API.

Besides, the library is very portable and runs under a lot of Unices, as well
as under OS/2, MacOS and Windows. Third party individuals also maintain ports
on other systems, including MS-DOS, and BeOS.

MikMod is able to play a wide range of module formats, as well as digital sound
files. It can take advantage of particular features of your system, such as
sound redirection over the network. And due to its modular nature, the library
can be extended to support more sound or module formats, as well as new
hardware or other sound output capabilities, as they appear.

@c ========================================================== Tutorial
@node Tutorial, Using the Library, Introduction, Top
@chapter Tutorial

This chapter will describe how to quickly incorporate MikMod's power into
your programs. It doesn't cover everything, but that's a start and I hope
it will help you understand the library philosophy.

If you have a real tutorial to put here, you're welcome ! Please send it to
me@enddots{}

@menu
* MikMod Concepts::         A few things you'll need to know.
* A Skeleton Program::      The shortest MikMod program.
* Playing Modules::         How to create a simple module player.
* Playing Sound Effects::   How to play simple sound effects.
* More Sound Effects::      How to play more complex sound effects.
@end menu

@c ========================================================== Concepts
@node MikMod Concepts, A Skeleton Program, Tutorial, Tutorial
@section MikMod Concepts

MikMod's sound output is composed of several sound @emph{voices} which are
mixed, either in software or in hardware, depending of your hardware
configuration. Simple sounds, like sound effects, use only one voice, whereas
sound modules, which are complex arrangements of sound effects, use several
voices.

MikMod's functions operate either globally, or at the voice level. Differences
in the handling of sound effects and modules are kept minimal, at least for
the programmer.

The sound playback is done by a @emph{sound driver}. MikMod provides several
sound drivers: different hardware drivers, and some software drivers to
redirect sound in a file, or over the network. You can even add your own
driver, register it to make it known by the library, and select it (this is
exactly what the module plugin of xmms does).

@c ========================================================== Skeleton
@node A Skeleton Program, Playing Modules, MikMod Concepts, Tutorial
@section A Skeleton Program
@iftex
@findex MikMod_Exit
@findex MikMod_Init
@findex MikMod_RegisterAllDrivers
@end iftex

To use MikMod in your program, there are a few steps required:

@itemize @bullet
@item Include @file{mikmod.h} in your program.
@item Register the MikMod drivers you need.
@item Initialize the library with MikMod_Init() before using any other MikMod
function.
@item Give up resources with MikMod_Exit() at the end of your program, or before
when MikMod is not needed anymore.
@item Link your application with the MikMod sound library.
@end itemize

Here's a program which meets all those conditions:

@example
/* MikMod Sound Library example program: a skeleton */

#include <mikmod.h>

main()
@{
	/* register all the drivers */
	MikMod_RegisterAllDrivers();

	/* initialize the library */
	MikMod_Init("");

	/* we could play some sound here... */

	/* give up */
	MikMod_Exit();
@}
@end example

This program would be compiled with the following command line:
@code{cc -o example example.c `libmikmod-config --cflags` `libmikmod-config --libs`}

Although this programs produces no useful result, many things happen when you
run it. The call to @code{MikMod_RegisterAllDrivers} registers all the drivers
embedded in the MikMod library. Then, @code{MikMod_Init} chooses the more
adequate driver and initializes it. The program is now ready to produce sound.
When sound is not needed any more, @code{MikMod_Exit} is used to relinquish
memory and let other programs have access to the sound hardware.

@c ========================================================== Modules
@node Playing Modules, Playing Sound Effects, A Skeleton Program, Tutorial
@section Playing Modules
@iftex
@findex MikMod_Exit
@findex MikMod_Init
@findex MikMod_RegisterAllDrivers
@findex MikMod_RegisterAllLoaders
@findex MikMod_Update
@vindex MikMod_errno
@findex MikMod_strerror
@findex Player_Active
@findex Player_Free
@findex Player_Load
@findex Player_Start
@findex Player_Stop
@end iftex

Our program is not really useful if it doesn't produce sound. Let's suppose
you've got this good old module, ``Beyond music'', in the file
@file{beyond music.mod}. How about playing it ?

To do this, we'll use the following code:

@example
/* MikMod Sound Library example program: a simple module player */

#include <unistd.h>
#include <mikmod.h>

main()
@{
    MODULE *module;

    /* register all the drivers */
    MikMod_RegisterAllDrivers();

    /* register all the module loaders */
    MikMod_RegisterAllLoaders();

    /* initialize the library */
    md_mode |= DMODE_SOFT_MUSIC;
    if (MikMod_Init("")) @{
        fprintf(stderr, "Could not initialize sound, reason: %s\n",
                MikMod_strerror(MikMod_errno));
        return;
    @}

    /* load module */
    module = Player_Load("beyond music.mod", 64, 0);
    if (module) @{
        /* start module */
        Player_Start(module);

        while (Player_Active()) @{
            /* we're playing */
            usleep(10000);
            MikMod_Update();
        @}

        Player_Stop();
        Player_Free(module);
    @} else
        fprintf(stderr, "Could not load module, reason: %s\n",
                MikMod_strerror(MikMod_errno));

    /* give up */
    MikMod_Exit();
@}
@end example

What's new here ? First, we've not only registered MikMod's device driver,
but also the module loaders. MikMod comes with a large choice of module
loaders, each one for a different module type. Since @emph{every} loader is
called to determine the type of the module when we try to load them, you may
want to register only a few of them to save time. In our case, we don't matter,
so we happily register every module loader.

Then, there's an extra line before calling @code{MikMod_Init}. We change the
value of MikMod's variable @code{md_mode} to tell the library that we want the
module to be processed by the software. If you're the happy owner of a GUS-type
card, you could use the specific hardware driver for this card, but in this
case you should not set the @code{DMODE_SOFT_MUSIC} flag.

We'll ensure that @code{MikMod_Init} was successful. Note that, in case of
error, MikMod provides the variable @code{MikMod_errno}, an equivalent of
the C library @code{errno} for MikMod errors, and the function
@code{MikMod_strerror}, an equivalent to @code{strerror}.

Now onto serious business ! The module is loaded with the @code{Player_Load}
function, which takes the name of the module file, and the number of voices
afforded to the module. In this case, the module has only 4 channels, so 4
voices, but complex Impulse Tracker modules can have a lot of voices (as they
can have as many as 256 virtual channels with so-called ``new note actions'').
Since empty voices don't cost time to be processed, it is safe to use a big
value, such as 64 or 128. The third parameter is the ``curiosity'' of the
loader: if nonzero, the loader will search for hidden parts in the module.
However, only a few module formats can embed hidden or non played parts, so
we'll use 0 here.

Now that the module is ready to play, let's play it. We inform the player that
the current module is @code{module} with @code{Player_Start}. Playback starts,
but we have to update it on a regular basis. So there's a loop on the result
of the @code{Player_Active} function, which will tell us if the module has
finished. To update the sound, we simply call @code{MikMod_Update}.

After the module has finished, we tell the player its job is done with
@code{Player_Stop}, and we free the module with @code{Player_Free}.

@c ========================================================== Sound effects
@node Playing Sound Effects, More Sound Effects, Playing Modules, Tutorial
@section Playing Sound Effects
@iftex
@findex MikMod_DisableOutput
@findex MikMod_EnableOutput
@findex MikMod_Exit
@findex MikMod_Init
@findex MikMod_RegisterAllDrivers
@findex MikMod_SetNumVoices
@findex MikMod_Update
@findex Voice_Stopped
@findex Sample_Free
@findex Sample_Load
@findex Sample_Play
@end iftex

MikMod is not limited to playing modules, it can also play sound effects, that
is, module samples. It's a bit more complex than playing a module, because the
module player does a lot of things for us, but here we'll get more control over
what is actually played by the program. Let's look at an example:

@example
/* MikMod Sound Library example program: sound effects */

#include <unistd.h>
#include <mikmod.h>

main()
@{