GNU Info
(mikmod.info)Structure Reference
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.
Drivers
-------
The `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:
`CHAR* Name'
Name of the driver, usually never more than 20 characters.
`CHAR* Description'
Description of the driver, usually never more than 50 characters.
`UBYTE HardVoiceLimit'
Maximum number of hardware voices for this driver, 0 if the driver
has no hardware mixing support.
`UBYTE SoftVoiceLimit'
Maximum number of software voices for this driver, 0 if the driver
has no software mixing support.
`CHAR* Alias'
A short name for the driver, without spaces, usually never more
than 10 characters.
Modules
-------
The `MODULE' structure gathers all the necessary information needed
to play a module file, regardless of its initial format.
General Module Information
..........................
The fields described in this section contain general information
about the module and should not be modified.
`CHAR* songname'
Name of the module.
`CHAR* modtype'
Type of the module (which tracker format).
`CHAR* comment'
Either the module comments, or NULL if the module doesn't have
comments.
`UWORD flags'
Several module flags or'ed together.
`UF_ARPMEM'
If set, arpeggio effects have memory.
`UF_BGSLIDES'
If set, volume slide effects continue until a new note or a
new effect is played.
`UF_HIGHBPM'
If set, the module is allowed to have its tempo value (bpm)
over 255.
`UF_INST'
If set, the module has instruments and samples; otherwise, the
module has only samples.
`UF_LINEAR'
If set, slide periods are linear; otherwise, they are
logarithmic.
`UF_NNA'
If set, module uses new note actions (NNA) and the
`numvoices' field is valid.
`UF_NOWRAP'
If set, pattern break on the last pattern does not continue
to the first pattern.
`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).
`UF_XMPERIODS'
If set, module uses XM-type periods; otherwise, it uses Amiga
periods.
`UF_FT2QUIRKS'
If set, module player will reproduce some FastTracker 2
quirks during playback.
`UF_PANNING'
If set, module use panning commands.
`UBYTE numchn'
The number of channels in the module.
`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
`maxchan' parameter of the `Player_Loadxx' functions.
`UWORD numpos'
The number of sound positions in the module.
`UWORD numpat'
The number of patterns.
`UWORD numins'
The number of instruments.
`UWORD numsmp'
The number of samples.
`INSTRUMENT* instruments'
Points to an array of instrument structures.
`SAMPLE* samples'
Points to an array of sample structures.
`UBYTE realchn'
During playback, this variable contains the number of active
channels (not counting NNA channels).
`UBYTE totalchn'
During playback, this variable contains the total number of
channels (including NNA channels).
`ULONG sngtime'
Elapsed song time, in 2^-10 seconds units (not exactly a
millisecond). To convert this value to seconds, divide by 1024,
not 1000 !
Playback Settings
.................
The fields described here control the module playback and can be
modified at any time, unless otherwise specified.
`UBYTE initspeed'
The initial speed of the module (Protracker compatible). Valid
range is 1-32.
`UBYTE inittempo'
The initial tempo of the module (Protracker compatible). Valid
range is 32-255.
`UBYTE initvolume'
The initial overall volume of the module. Valid range is 0-128.
`UWORD panning[]'
The current channel panning positions. Only the first `numchn'
values are defined.
`UBYTE chanvol[]'
The current channel volumes. Only the first `numchn' values are
defined.
`UWORD bpm'
The current tempo of the module. Use `Player_SetTempo' to change
its value.
`UBYTE sngspd'
The current speed of the module. Use `Player_SetSpeed' to change
its value.
`UBYTE volume'
The current overall volume of the module, in range 0-128. Use
`Player_SetVolume' to change its value.
`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.
`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.
`BOOL wrap'
If nonzero, module wraps to its restart position when it is
finished, to play continuously. Default value is zero (play only
once).
`UBYTE reppos'
The restart position of the module, when it wraps.
`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).
`BOOL fadeout'
If nonzero, volume fades out during when last position of the
module is being played. Default value us zero (no fadeout).
`UWORD patpos'
Current position (row) in the pattern being played. Must not be
changed.
`SWORD sngpos'
Current song position. Do not change this variable directly, use
`Player_NextPosition', `Player_PrevPosition' or
`Player_SetPosition' instead.
`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.
Module Instruments
------------------
Although the `INSTRUMENT' structure is intended for internal use, you
might need to know its name:
`CHAR* insname'
The instrument text, theoretically its name, but often a message
line.
Samples
-------
The `SAMPLE' structure is used for sound effects and module samples
as well. You can play with the following fields:
`SWORD panning'
Panning value of the sample. Valid values range from PAN_LEFT (0)
to PAN_RIGHT (255), or PAN_SURROUND.
`ULONG speed'
Playing frequency of the sample, it hertz.
`UBYTE volume'
Sample volume. Valid range is 0-64.
`UWORD flags'
Several format flags or'ed together describing the format of the
sample in memory.
Format flags:
`SF_16BITS'
If set, sample data is 16 bit wide; otherwise, it is 8 bit
wide.
`SF_BIG_ENDIAN'
If set, sample data is in big-endian (Motorola) format;
otherwise, it is in little-endian (Intel) format.
`SF_DELTA'
If set, sample is stored as delta values (differences between
two consecutive samples); otherwise, sample is stored as
sample values.
`SF_ITPACKED'
If set, sample data is packed with Impulse Tracker's
compression method; otherwise, sample is not packed.
`SF_SIGNED'
If set, sample data is made of signed values; otherwise, it
is made of unsigned values.
`SF_STEREO'
If set, sample data is stereo (two channels); otherwise, it
is mono.
Playback flags:
`SF_BIDI'
If set, sample loops "ping pong" (back and forth).
`SF_LOOP'
If set, sample loops forward.
`SF_REVERSE'
If set, sample plays backwards.
`UWORD inflags'
Same as "flags", but describing the format of the sample on disk.
`ULONG length'
Length of the sample, in _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.
`ULONG loopstart'
Loop starting position, relative to the start of the sample, in
samples.
`ULONG loopend'
Loop ending position, relative to the start of the sample, in
samples.
MREADER
-------
The `MREADER' contains the following function pointers:
`BOOL (*Seek)(struct MREADER*, long offset, int whence)'
This function should have the same behaviour as `fseek', with
offset 0 meaning the start of the object (module, sample) being
loaded.
`long (*Tell)(struct MREADER*)'
This function should have the same behaviour as `ftell', with
offset 0 meaning the start of the object being loaded.
`BOOL (*Read)(struct MREADER*, void *dest, size_t length)'
This function should copy `length' bytes of data into `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.
`int (*Get)(struct MREADER*)'
This function should have the same behaviour as `fgetc'.
`BOOL (*Eof)(struct MREADER*)'
This function should have the same behaviour as `feof'.
For an example of how to build an `MREADER' object, please refer to
the `MFILEREADER' object in file `mmio/mmio.c' in the library sources.
MWRITER
-------
The `MREADER' contains the following function pointers:
`BOOL (*Seek)(struct MWRITER*, long offset, int whence);'
This function should have the same behaviour as `fseek', with
offset 0 meaning the start of the object being written.
`long (*Tell)(struct MWRITER*);'
This function should have the same behaviour as `ftell', with
offset 0 meaning the start of the object being written.
`BOOL (*Write)(struct MWRITER*, void *dest, size_t length);'
This function should copy `length' bytes of data from `dest', and
return zero if an error occured, and any nonzero value otherwise.
`BOOL (*Put)(struct MWRITER*, int data);'
This function should have the same behaviour as `fputc'.
For an example of how to build an `MWRITER' object, please refer to
the `MFILEWRITER' object in file `mmio/mmio.c' in the library sources.
automatically generated by info2www version 1.2.2.9