Merge branch 'master' into divVerent/crypto2
[xonotic/xonotic.git] / misc / builddeps / dp.linux64 / include / libmodplug / modplug.h
1 /*
2  * This source code is public domain.
3  *
4  * Authors: Kenton Varda <temporal@gauge3d.org> (C interface wrapper)
5  */
6
7 #ifndef MODPLUG_H__INCLUDED
8 #define MODPLUG_H__INCLUDED
9
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13
14 struct _ModPlugFile;
15 typedef struct _ModPlugFile ModPlugFile;
16
17 struct _ModPlugNote {
18         unsigned char Note;
19         unsigned char Instrument;
20         unsigned char VolumeEffect;
21         unsigned char Effect;
22         unsigned char Volume;
23         unsigned char Parameter;
24 };
25 typedef struct _ModPlugNote ModPlugNote;
26
27 typedef void (*ModPlugMixerProc)(int*, unsigned long, unsigned long);
28
29 /* Load a mod file.  [data] should point to a block of memory containing the complete
30  * file, and [size] should be the size of that block.
31  * Return the loaded mod file on success, or NULL on failure. */
32 ModPlugFile* ModPlug_Load(const void* data, int size);
33 /* Unload a mod file. */
34 void ModPlug_Unload(ModPlugFile* file);
35
36 /* Read sample data into the buffer.  Returns the number of bytes read.  If the end
37  * of the mod has been reached, zero is returned. */
38 int  ModPlug_Read(ModPlugFile* file, void* buffer, int size);
39
40 /* Get the name of the mod.  The returned buffer is stored within the ModPlugFile
41  * structure and will remain valid until you unload the file. */
42 const char* ModPlug_GetName(ModPlugFile* file);
43
44 /* Get the length of the mod, in milliseconds.  Note that this result is not always
45  * accurate, especially in the case of mods with loops. */
46 int ModPlug_GetLength(ModPlugFile* file);
47
48 /* Seek to a particular position in the song.  Note that seeking and MODs don't mix very
49  * well.  Some mods will be missing instruments for a short time after a seek, as ModPlug
50  * does not scan the sequence backwards to find out which instruments were supposed to be
51  * playing at that time.  (Doing so would be difficult and not very reliable.)  Also,
52  * note that seeking is not very exact in some mods -- especially those for which
53  * ModPlug_GetLength() does not report the full length. */
54 void ModPlug_Seek(ModPlugFile* file, int millisecond);
55
56 enum _ModPlug_Flags
57 {
58         MODPLUG_ENABLE_OVERSAMPLING     = 1 << 0,  /* Enable oversampling (*highly* recommended) */
59         MODPLUG_ENABLE_NOISE_REDUCTION  = 1 << 1,  /* Enable noise reduction */
60         MODPLUG_ENABLE_REVERB           = 1 << 2,  /* Enable reverb */
61         MODPLUG_ENABLE_MEGABASS         = 1 << 3,  /* Enable megabass */
62         MODPLUG_ENABLE_SURROUND         = 1 << 4   /* Enable surround sound. */
63 };
64
65 enum _ModPlug_ResamplingMode
66 {
67         MODPLUG_RESAMPLE_NEAREST = 0,  /* No interpolation (very fast, extremely bad sound quality) */
68         MODPLUG_RESAMPLE_LINEAR  = 1,  /* Linear interpolation (fast, good quality) */
69         MODPLUG_RESAMPLE_SPLINE  = 2,  /* Cubic spline interpolation (high quality) */
70         MODPLUG_RESAMPLE_FIR     = 3   /* 8-tap fir filter (extremely high quality) */
71 };
72
73 typedef struct _ModPlug_Settings
74 {
75         int mFlags;  /* One or more of the MODPLUG_ENABLE_* flags above, bitwise-OR'ed */
76         
77         /* Note that ModPlug always decodes sound at 44100kHz, 32 bit, stereo and then
78          * down-mixes to the settings you choose. */
79         int mChannels;       /* Number of channels - 1 for mono or 2 for stereo */
80         int mBits;           /* Bits per sample - 8, 16, or 32 */
81         int mFrequency;      /* Sampling rate - 11025, 22050, or 44100 */
82         int mResamplingMode; /* One of MODPLUG_RESAMPLE_*, above */
83
84         int mStereoSeparation; /* Stereo separation, 1 - 256 */
85         int mMaxMixChannels; /* Maximum number of mixing channels (polyphony), 32 - 256 */
86         
87         int mReverbDepth;    /* Reverb level 0(quiet)-100(loud)      */
88         int mReverbDelay;    /* Reverb delay in ms, usually 40-200ms */
89         int mBassAmount;     /* XBass level 0(quiet)-100(loud)       */
90         int mBassRange;      /* XBass cutoff in Hz 10-100            */
91         int mSurroundDepth;  /* Surround level 0(quiet)-100(heavy)   */
92         int mSurroundDelay;  /* Surround delay in ms, usually 5-40ms */
93         int mLoopCount;      /* Number of times to loop.  Zero prevents looping.
94                                 -1 loops forever. */
95 } ModPlug_Settings;
96
97 /* Get and set the mod decoder settings.  All options, except for channels, bits-per-sample,
98  * sampling rate, and loop count, will take effect immediately.  Those options which don't
99  * take effect immediately will take effect the next time you load a mod. */
100 void ModPlug_GetSettings(ModPlug_Settings* settings);
101 void ModPlug_SetSettings(const ModPlug_Settings* settings);
102
103 /* New ModPlug API Functions */
104 /* NOTE: Master Volume (1-512) */
105 unsigned int ModPlug_GetMasterVolume(ModPlugFile* file) ;
106 void ModPlug_SetMasterVolume(ModPlugFile* file,unsigned int cvol) ;
107
108 int ModPlug_GetCurrentSpeed(ModPlugFile* file);
109 int ModPlug_GetCurrentTempo(ModPlugFile* file);
110 int ModPlug_GetCurrentOrder(ModPlugFile* file);
111 int ModPlug_GetCurrentPattern(ModPlugFile* file);
112 int ModPlug_GetCurrentRow(ModPlugFile* file);
113 int ModPlug_GetPlayingChannels(ModPlugFile* file);
114
115 void ModPlug_SeekOrder(ModPlugFile* file,int order);
116 int ModPlug_GetModuleType(ModPlugFile* file);
117 char* ModPlug_GetMessage(ModPlugFile* file);
118
119
120 #ifndef MODPLUG_NO_FILESAVE
121 /*
122  * EXPERIMENTAL Export Functions
123  */
124 /*Export to a Scream Tracker 3 S3M module. EXPERIMENTAL (only works on Little-Endian platforms)*/
125 char ModPlug_ExportS3M(ModPlugFile* file, const char* filepath);
126
127 /*Export to a Extended Module (XM). EXPERIMENTAL (only works on Little-Endian platforms)*/
128 char ModPlug_ExportXM(ModPlugFile* file, const char* filepath);
129
130 /*Export to a Amiga MOD file. EXPERIMENTAL.*/
131 char ModPlug_ExportMOD(ModPlugFile* file, const char* filepath);
132
133 /*Export to a Impulse Tracker IT file. Should work OK in Little-Endian & Big-Endian platforms :-) */
134 char ModPlug_ExportIT(ModPlugFile* file, const char* filepath);
135 #endif // MODPLUG_NO_FILESAVE
136
137 unsigned int ModPlug_NumInstruments(ModPlugFile* file);
138 unsigned int ModPlug_NumSamples(ModPlugFile* file);
139 unsigned int ModPlug_NumPatterns(ModPlugFile* file);
140 unsigned int ModPlug_NumChannels(ModPlugFile* file);
141 unsigned int ModPlug_SampleName(ModPlugFile* file, unsigned int qual, char* buff);
142 unsigned int ModPlug_InstrumentName(ModPlugFile* file, unsigned int qual, char* buff);
143
144 /*
145  * Retrieve pattern note-data
146  */
147 ModPlugNote* ModPlug_GetPattern(ModPlugFile* file, int pattern, unsigned int* numrows);
148
149 /*
150  * =================
151  * Mixer callback
152  * =================
153  *
154  * Use this callback if you want to 'modify' the mixed data of LibModPlug.
155  * 
156  * void proc(int* buffer,unsigned long channels,unsigned long nsamples) ;
157  *
158  * 'buffer': A buffer of mixed samples
159  * 'channels': N. of channels in the buffer
160  * 'nsamples': N. of samples in the buffeer (without taking care of n.channels)
161  *
162  * (Samples are signed 32-bit integers)
163  */
164 void ModPlug_InitMixerCallback(ModPlugFile* file,ModPlugMixerProc proc) ;
165 void ModPlug_UnloadMixerCallback(ModPlugFile* file) ;
166
167 #ifdef __cplusplus
168 } /* extern "C" */
169 #endif
170
171 #endif