mikmod.texi

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

For an example of how to build an @code{MWRITER} object, please refer to the
@code{MFILEWRITER} object in file @code{mmio/mmio.c} in the library sources.

@c ========================================================== Error reference
@node Error Reference, Function Reference, Structure Reference, Library Reference
@section Error Reference

The following errors are currently defined:

@subsection General Errors
@table @samp
@item MMERR_DYNAMIC_LINKING
This error occurs when a specific driver was requested, but the support shared
library couldn't be loaded. Currently, the only drivers which can yield this
error are the ALSA, EsounD and Ultra drivers.
@item MMERR_OPENING_FILE
This error occurs when a file can not be opened, either for read access from a
@code{xx_Loadxx} function, or for write access from the disk writer drivers.
@item MMERR_OUT_OF_MEMORY
This error occurs when there is not enough virtual memory available to complete
the operation, or there is enough memory but the calling process would exceed
its memory limit. MikMod does not do any resource tuning, your program has to
use the @code{setrlimit} function to do this if it needs to load very huge
samples.
@end table

@subsection Sample Errors
@table @samp
@item MMERR_SAMPLE_TOO_BIG
This error occurs when the memory allocation of the sample data yields the
error @code{MMERR_OUT_OF_MEMORY}.
@item MMERR_OUT_OF_HANDLES
This error occurs when your program reaches the limit of loaded samples,
currently defined as 384, which should be sufficient for most cases.
@item MMERR_UNKNOWN_WAVE_TYPE
This error occurs when you're trying to load a sample which format is not
recognized.
@end table

@subsection Module Errors
@table @samp
@item MMERR_ITPACK_INVALID_DATA
This error occurs when a compressed module sample is corrupt.
@item MMERR_LOADING_HEADER
This error occurs when you're trying to load a module which has a corrupted
header, or is truncated.
@item MMERR_LOADING_PATTERN
This error occurs when you're trying to load a module which has corrupted
pattern data, or is truncated.
@item MMERR_LOADING_SAMPLEINFO
This error occurs when you're trying to load a module which has corrupted
sample information, or is truncated.
@item MMERR_LOADING_TRACK
This error occurs when you're trying to load a module which has corrupted
track data, or is truncated.
@item MMERR_MED_SYNTHSAMPLES
This error occurs when you're trying to load a MED module which has synthsounds
samples, which are currently not supported.@footnote{You can force libmikmod to
load the module (without the synthsounds, of course) by setting the
@code{curious} parameter to @code{1} when invoking @code{Player_Loadxx}.}
@item MMERR_NOT_A_MODULE
This error occurs when you're trying to load a module which format is not
recognized.
@item MMERR_NOT_A_STREAM
This error occurs when you're trying to load a sample with a sample which format
is not recognized.
@end table

@subsection Driver Errors
@ifnottex
@subsubsection Generic Driver Errors
@end ifnottex
@iftex
Generic driver errors
@end iftex
@table @samp
@item MMERR_16BIT_ONLY
This error occurs when the sound device doesn't support non-16 bit linear
sound output, which are the requested settings.
@item MMERR_8BIT_ONLY
This error occurs when the sound device doesn't support non-8 bit linear
sound output, which are the requested settings.
@item MMERR_DETECTING_DEVICE
This error occurs when the driver's sound device has not been detected.
@item MMERR_INITIALIZING_MIXER
This error occurs when MikMod's internal software mixer could not be initialized
properly.
@item MMERR_INVALID_DEVICE
This error occurs when the driver number (in @code{md_device}) is out of range.
@item MMERR_NON_BLOCK
This error occurs when the driver is unable to set the audio device in non
blocking mode.
@item MMERR_OPENING_AUDIO
This error occurs when the driver can not open sound device.
@item MMERR_STEREO_ONLY
This error occurs when the sound device doesn't support mono sound output, which
is the requested setting.
@item MMERR_ULAW
This error occurs when the sound device only supports uLaw output (which
implies mono, 8 bit, and 8000 Hz sampling rate), which isn't the requested
setting.
@end table
@ifnottex
@subsubsection AudioFile Driver Specific Error
@end ifnottex
@iftex
AudioFile driver specific error
@end iftex
@table @samp
@item MMERR_AF_AUDIO_PORT
This error occurs when the AudioFile driver can not find a suitable AudioFile
port.
@end table
@ifnottex
@subsubsection AIX Driver Specific Errors
@end ifnottex
@iftex
AIX driver specific errors
@end iftex
@table @samp
@item MMERR_AIX_CONFIG_CONTROL
This error occurs when the ``Control'' step of the device configuration has
failed.
@item MMERR_AIX_CONFIG_INIT
This error occurs when the ``Init'' step of the device configuration has failed.
@item MMERR_AIX_CONFIG_START
This error occurs when the ``Start'' step of the device configuration has failed.
@end table
@ifnottex
@subsubsection Ultra Driver Specific Errors
@end ifnottex
@iftex
Ultra driver specific errors
@end iftex
@table @samp
@item MMERR_GUS_RESET
This error occurs when the sound device couldn't be reset.
@item MMERR_GUS_SETTINGS
This error occurs because the sound device only works in 16 bit linear stereo
sound at 44100 Hz, which is not the requested settings.
@item MMERR_GUS_TIMER
This error occurs when the ultra driver could not setup the playback timer.
@end table
@ifnottex
@subsubsection HP-UX Driver Specific Errors
@end ifnottex
@iftex
HP-UX driver specific errors
@end iftex
@table @samp
@item MMERR_HP_AUDIO_DESC
This error occurs when the HP driver can not get the audio hardware description.
@item MMERR_HP_AUDIO_OUTPUT
This error occurs when the HP driver can not select the audio output.
@item MMERR_HP_BUFFERSIZE
This error occurs when the HP driver can not set the transmission buffer size.
@item MMERR_HP_CHANNELS
This error occurs when the HP driver can not set the requested number of
channels.
@item MMERR_HP_SETSAMPLESIZE
This error occurs when the HP driver can not set the requested sample size.
@item MMERR_HP_SETSPEED
This error occurs when the HP driver can not set the requested sample rate.
@end table
@ifnottex
@subsubsection Open Sound System Driver Specific Errors
@end ifnottex
@iftex
Open Sound System driver specific errors
@end iftex
@table @samp
@item MMERR_OSS_SETFRAGMENT
This error occurs when the OSS driver can not set audio fragment size.
@item MMERR_OSS_SETSAMPLESIZE
This error occurs when the OSS driver can not set the requested sample size.
@item MMERR_OSS_SETSPEED
This error occurs when the OSS driver can not set the requested sample rate.
@item MMERR_OSS_SETSTEREO
This error occurs when the OSS driver can not set the requested number of
channels.
@end table
@ifnottex
@subsubsection SGI Driver Specific Errors
@end ifnottex
@iftex
SGI driver specific errors
@end iftex
@table @samp
@item MMERR_SGI_MONO
This error occurs when the hardware only supports stereo sound.
@item MMERR_SGI_SPEED
This error occurs when the hardware does not support the requested sample rate.
@item MMERR_SGI_STEREO
This error occurs when the hardware only supports mono sound.
@item MMERR_SGI_16BIT
This error occurs when the hardware only supports 16 bit sound.
@item MMERR_SGI_8BIT
This error occurs when the hardware only supports 8 bit sound.
@end table
@ifnottex
@subsubsection Sun Driver Specific Error
@end ifnottex
@iftex
Sun driver specific error
@end iftex
@table @samp
@item MMERR_SUN_INIT
This error occurs when the sound device initialization failed.
@end table
@ifnottex
@subsubsection OS/2 Driver Specific Errors
@end ifnottex
@iftex
OS/2 driver specific errors
@end iftex
@table @samp
@item MMERR_OS2_MIXSETUP
This error occurs when the DART driver can not set the mixing parameters.
@item MMERR_OS2_SEMAPHORE
This error occurs when the MMPM/2 driver can not create the semaphores needed
for playback.
@item MMERR_OS2_THREAD
This error occurs when the MMPM/2 driver can not create the thread needed for
playback.
@item MMERR_OS2_TIMER
This error occurs when the MMPM/2 driver can not create the timer needed for
playback.
@end table
@ifnottex
@subsubsection DirectX Driver Specific Errors
@end ifnottex
@iftex
DirectX Driver Specific Errors
@end iftex
@table @samp
@item MMERR_DS_BUFFER
This error occurs when the DirectX driver can not allocate the playback buffers.
@item MMERR_DS_EVENT
This error occurs when the DirectX driver can not register the playback event.
@item MMERR_DS_FORMAT
This error occurs when the DirectX driver can not set the playback format.
@item MMERR_DS_NOTIFY
This error occurs when the DirectX driver can not register the playback
callback.
@item MMERR_DS_PRIORITY
This error occurs when the DirectX driver can not set the playback priority.
@item MMERR_DS_THREAD
This error occurs when the DirectX driver can not create the playback thread.
@item MMERR_DS_UPDATE
This error occurs when the DirectX driver can not initialize the playback
thread.
@end table
@ifnottex
@subsubsection Windows Multimedia API Driver Specific Errors
@end ifnottex
@iftex
Windows Multimedia API Driver Specific Errors
@end iftex
@table @samp
@item MMERR_WINMM_ALLOCATED
This error occurs when the playback resource is already allocated by another
application.
@item MMERR_WINMM_DEVICEID
This error occurs when the Multimedia API Driver is given an invalid audio
device identificator.
@item MMERR_WINMM_FORMAT
This error occurs when the playback output format is not supported by the audio
device.
@item MMERR_WINMM_HANDLE
This error occurs when the Multimedia API Driver is given an invalid handle.
@item MMERR_WINMM_UNKNOWN
This error should not occur ! If you get this error, please contact the
libmikmod development mailing list.
@end table
@ifnottex
@subsubsection MacOS Driver Specific Errors
@end ifnottex
@iftex
MacOS Driver Specific Errors
@end iftex
@table @samp
@item MMERR_MAC_SPEED
This error occurs when the playback speed is not supported by the audio device.
@item MMERR_MAC_START
This error occurs when the MacOS driver can not start playback.
@end table

@c ========================================================== Function reference
@node Function Reference, Library Core Functions, Error Reference, Library Reference
@section Function Reference
@menu
* Library Core Functions::      MikMod_xx functions.
* Module Player Functions::     Player_xx functions.
* Sample Functions::            Sample_xx functions.
* Voice Functions::             Voice_xx functions.
@end menu

@c ========================================================== MikMod_xx
@node Library Core Functions, Module Player Functions, Function Reference, Function Reference
@subsection Library Core Functions

@ifnottex
@subsubsection MikMod_Active
@end ifnottex
@findex MikMod_Active
@code{BOOL MikMod_Active(void)}
@table @i
@item Description
This function returns whether sound output is enabled or not.
@item Result
@itemx 0
Sound output is disabled.
@item 1
Sound output is enabled.
@item Notes
Calls to @code{MikMod_Update} will be ignored when sound output is disabled.
@item See also
@code{MikMod_DisableOutput}, @code{MikMod_EnableOutput}.
@end table

@ifnottex
@subsubsection MikMod_DisableOutput
@end ifnottex
@findex MikMod_DisableOutput
@code{void MikMod_DisableOutput(void)}
@table @i
@item Description
This function stops the sound mixing.
@item Notes
Calls to @code{MikMod_Update} will be ignored when sound output is disabled.
@item See also
@code{MikMod_Active}, @code{MikMod_EnableOutput}.
@end table

@ifnottex
@subsubsection MikMod_EnableOutput
@end ifnottex
@findex MikMod_EnableOutput
@code{BOOL MikMod_EnableOutput(void)}
@table @i
@item Description
This function starts the sound mixing.
@item