mikmod.texi

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

Sound playback frequency, in hertz. High values
yield high sound quality, but need more computing power than lower values. The
default value is 44100 Hz, which is compact disc quality. Other common values
are 22100 Hz (radio quality), 11025 Hz (phone quality), and 8000 Hz (mu-law
quality).
@vindex md_mode
@item UWORD md_mode
This variable is a combination of several flags, to select which output mode
to select.
The following flags have a direct action to the sound output (i.e. changes take
effect immediately):
@table @samp
@item DMODE_INTERP
This flag, if set, enables the interpolated mixers. Interpolated mixing gives
better sound but takes a bit more time than standard mixing. If the library
is built with the high quality mixer, interpolated mixing is always enabled,
regardless of this flag.
@item DMODE_REVERSE
This flag, if set, exchanges the left and right stereo channels.
@item DMODE_SURROUND
This flag, if set, enables the surround mixers. Since surround mixing works
only for stereo sound, this flag has no effect if the sound playback is in
mono.
@end table

@*The following flags aren't taken in account until the sound driver is changed
or reset:
@table @samp
@item DMODE_16BIT
This flag, if set, selects 16 bit sound mode. This mode yields better sound
quality, but needs twice more mixing time.
@item DMODE_HQMIXER
This flag, if set, selects the high-quality software mixer. This mode yields
better sound quality, but needs more mixing time. Of course, this flag has no
effect if no @code{DMODE_SOFT_xx} flag is set.
@item DMODE_SOFT_MUSIC
This flag, if set, selects software mixing of the module.
@item DMODE_SOFT_SNDFX
This flag, if set, selects software mixing of the sound effects.
@item DMODE_STEREO
This flag, if set, selects stereo sound.
@end table

@*The default value of this variable is @samp{DMODE_STEREO | DMODE_SURROUND |
DMODE_16BITS | DMODE_SOFT_MUSIC | DMODE_SOFT_SNDFX}.
@end table

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

Only the useful fields are described here; if a structure field is not
described, you must assume that it's an internal field which must not be
modified.

@subsection Drivers
@tindex MDRIVER

The @code{MDRIVER} structure is not meant to be used by anything else than the
core of the library, but its first four fields contain useful information for
your programs:
@table @code
@item CHAR* Name
Name of the driver, usually never more than 20 characters.
@item CHAR* Description
Description of the driver, usually never more than 50 characters.
@item UBYTE HardVoiceLimit
Maximum number of hardware voices for this driver, 0 if the driver has no
hardware mixing support.
@item UBYTE SoftVoiceLimit
Maximum number of software voices for this driver, 0 if the driver has no
software mixing support.
@item CHAR* Alias
A short name for the driver, without spaces, usually never more than 10
characters.
@end table

@subsection Modules
@tindex MODULE

The @code{MODULE} structure gathers all the necessary information needed to
play a module file, regardless of its initial format.

@subsubsection General Module Information

The fields described in this section contain general information about the
module and should not be modified.

@table @code
@item CHAR* songname
Name of the module.
@item CHAR* modtype
Type of the module (which tracker format).
@item CHAR* comment
Either the module comments, or NULL if the module doesn't have comments.
@end table

@table @code
@item UWORD flags
Several module flags or'ed together.
@table @samp
@item UF_ARPMEM
If set, arpeggio effects have memory.
@item UF_BGSLIDES
If set, volume slide effects continue until a new note or a new effect is played.
@item UF_HIGHBPM
If set, the module is allowed to have its tempo value (bpm) over 255.
@item UF_INST
If set, the module has instruments and samples; otherwise, the
module has only samples.
@item UF_LINEAR
If set, slide periods are linear; otherwise, they are logarithmic.
@item UF_NNA
If set, module uses new note actions (NNA) and the @code{numvoices} field is
valid.
@item UF_NOWRAP
If set, pattern break on the last pattern does not continue to the first
pattern.
@item UF_S3MSLIDES
If set, module uses old-S3M style volume slides (slides processed every tick);
otherwise, it uses the standard style (slides processed every tick except the
first).
@item UF_XMPERIODS
If set, module uses XM-type periods; otherwise, it uses Amiga periods.
@item UF_FT2QUIRKS
If set, module player will reproduce some FastTracker 2 quirks during playback.
@item UF_PANNING
If set, module use panning commands.
@end table
@item UBYTE numchn
The number of channels in the module.
@item UBYTE numvoices
If the module uses NNA, and this variable is not zero, it contains the limit
of module voices; otherwise, the limit is set to the @code{maxchan} parameter
of the @code{Player_Loadxx} functions.
@item UWORD numpos
The number of sound positions in the module.
@item UWORD numpat
The number of patterns.
@item UWORD numins
The number of instruments.
@item UWORD numsmp
The number of samples.
@end table

@table @code
@item INSTRUMENT* instruments
Points to an array of instrument structures.
@item SAMPLE* samples
Points to an array of sample structures.
@end table

@table @code
@item UBYTE realchn
During playback, this variable contains the number of active channels (not
counting NNA channels).
@item UBYTE totalchn
During playback, this variable contains the total number of channels (including
NNA channels).
@item ULONG sngtime
Elapsed song time, in @math{2^@minus{}10} @dmn{seconds} units (not exactly a
millisecond). To convert this value to seconds, divide by 1024, not 1000 !
@end table

@subsubsection Playback Settings

The fields described here control the module playback and can be modified at
any time, unless otherwise specified.

@table @code
@item UBYTE initspeed
The initial speed of the module (Protracker compatible). Valid range is 1-32.
@item UBYTE inittempo
The initial tempo of the module (Protracker compatible). Valid range is
32-255.
@item UBYTE initvolume
The initial overall volume of the module. Valid range is 0-128.
@item UWORD panning[]
The current channel panning positions. Only the first @code{numchn} values are
defined.
@item UBYTE chanvol[]
The current channel volumes. Only the first @code{numchn} values are defined.
@item UWORD bpm
The current tempo of the module. Use @code{Player_SetTempo} to change its value.
@item UBYTE sngspd
The current speed of the module. Use @code{Player_SetSpeed} to change its value.
@item UBYTE volume
The current overall volume of the module, in range 0-128. Use
@code{Player_SetVolume} to change its value.
@end table

@table @code
@item BOOL extspd
If zero, Protracker extended speed effect (in-module tempo modification) is
not processed. The default value is 1, which causes this effect to be processed.
However, some old modules might not play correctly if this effect is not
neutralized.
@item BOOL panflag
If zero, panning effects are not processed. The default value is 1, which cause
all panning effects to be processed. However, some old modules might not play
correctly if panning is not neutralized.
@item BOOL wrap
If nonzero, module wraps to its restart position when it is finished, to
play continuously. Default value is zero (play only once).
@item UBYTE reppos
The restart position of the module, when it wraps.
@item BOOL loop
If nonzero, all in-module loops are processed; otherwise, backward loops which
decrease the current position are not processed (i.e. only forward loops, and
backward loops in the same pattern, are processed). This ensures that the module
never loops endlessly. The default value is 1 (all loops are processed).
@item BOOL fadeout
If nonzero, volume fades out during when last position of the module is being
played. Default value us zero (no fadeout).
@end table

@table @code
@item UWORD patpos
Current position (row) in the pattern being played. Must not be changed.
@item SWORD sngpos
Current song position. Do not change this variable directly, use
@code{Player_NextPosition}, @code{Player_PrevPosition} or
@code{Player_SetPosition} instead.
@end table

@table @code
@item SWORD relspd
Relative playback speed. The value of this variable is added to the module
tempo to define the actual playback speed. The default value is 0, which make
modules play at their intended speed.
@end table

@subsection Module Instruments
@tindex INSTRUMENT

Although the @code{INSTRUMENT} structure is intended for internal use, you
might need to know its name:

@table @code
@item CHAR* insname
The instrument text, theoretically its name, but often a message line.
@end table

@subsection Samples
@tindex SAMPLE

The @code{SAMPLE} structure is used for sound effects and module samples as
well. You can play with the following fields:

@table @code
@item SWORD panning
Panning value of the sample. Valid values range from PAN_LEFT (0) to
PAN_RIGHT (255), or PAN_SURROUND.
@item ULONG speed
Playing frequency of the sample, it hertz.
@item UBYTE volume
Sample volume. Valid range is 0-64.
@item UWORD flags
Several format flags or'ed together describing the format of the sample in
memory.

Format flags:
@table @samp
@item SF_16BITS
If set, sample data is 16 bit wide; otherwise, it is 8 bit wide.
@item SF_BIG_ENDIAN
If set, sample data is in big--endian (Motorola) format; otherwise, it is in
little--endian (Intel) format.
@item SF_DELTA
If set, sample is stored as delta values (differences between two consecutive
samples); otherwise, sample is stored as sample values.
@item SF_ITPACKED
If set, sample data is packed with Impulse Tracker's compression method;
otherwise, sample is not packed.
@item SF_SIGNED
If set, sample data is made of signed values; otherwise, it is made of
unsigned values.
@item SF_STEREO
If set, sample data is stereo (two channels); otherwise, it is mono.
@end table

@*Playback flags:
@table @samp
@item SF_BIDI
If set, sample loops ``ping pong'' (back and forth).
@item SF_LOOP
If set, sample loops forward.
@item SF_REVERSE
If set, sample plays backwards.
@end table
@item UWORD inflags
Same as ``flags'', but describing the format of the sample on disk.
@item ULONG length
Length of the sample, in @emph{samples}. The length of a sample is 8 bits
(1 byte) for a 8 bit sample, and 16 bits (2 bytes) for a 16 bit sample.
@item ULONG loopstart
Loop starting position, relative to the start of the sample, in samples.
@item ULONG loopend
Loop ending position, relative to the start of the sample, in samples.
@end table

@subsection MREADER
@tindex MREADER

The @code{MREADER} contains the following function pointers:

@table @code
@item BOOL (*Seek)(struct MREADER*, long offset, int whence)
This function should have the same behaviour as @code{fseek}, with offset 0
meaning the start of the object (module, sample) being loaded.
@item long (*Tell)(struct MREADER*)
This function should have the same behaviour as @code{ftell}, with offset 0
meaning the start of the object being loaded.
@item BOOL (*Read)(struct MREADER*, void *dest, size_t length)
This function should copy @code{length} bytes of data into @code{dest}, and
return zero if an error occured, and any nonzero value otherwise. Note that an
end-of-file condition will not be considered as an error in this case.
@item int (*Get)(struct MREADER*)
This function should have the same behaviour as @code{fgetc}.
@item BOOL (*Eof)(struct MREADER*)
This function should have the same behaviour as @code{feof}.
@end table

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

@subsection MWRITER
@tindex MWRITER

The @code{MREADER} contains the following function pointers:

@table @code
@item BOOL (*Seek)(struct MWRITER*, long offset, int whence);
This function should have the same behaviour as @code{fseek}, with offset 0
meaning the start of the object being written.
@item long (*Tell)(struct MWRITER*);
This function should have the same behaviour as @code{ftell}, with offset 0
meaning the start of the object being written.
@item BOOL (*Write)(struct MWRITER*, void *dest, size_t length);
This function should copy @code{length} bytes of data from @code{dest}, and
return zero if an error occured, and any nonzero value otherwise.
@item BOOL (*Put)(struct MWRITER*, int data);
This function should have the same behaviour as @code{fputc}.
@end table