FS#12113: Optimize IRAM configuration for Atari SAP format. Performance gains range...
[kugel-rb.git] / apps / codecs / libasap / asap.h
blob1cbf8d0100150421348f91818cf291f9f8608c9e
1 /*
2 * asap.h - public interface of ASAP
4 * Copyright (C) 2005-2010 Piotr Fusik
6 * This file is part of ASAP (Another Slight Atari Player),
7 * see http://asap.sourceforge.net
9 * ASAP is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU General Public License as published
11 * by the Free Software Foundation; either version 2 of the License,
12 * or (at your option) any later version.
14 * ASAP is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty
16 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
17 * See the GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with ASAP; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24 #ifndef _ASAP_H_
25 #define _ASAP_H_
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
31 /* ASAP version. */
32 #define ASAP_VERSION_MAJOR 2
33 #define ASAP_VERSION_MINOR 1
34 #define ASAP_VERSION_MICRO 2
35 #define ASAP_VERSION "2.1.2"
37 /* Short credits of the ASAP engine. */
38 #define ASAP_YEARS "2005-2010"
39 #define ASAP_CREDITS \
40 "Another Slight Atari Player (C) 2005-2010 Piotr Fusik\n" \
41 "CMC, MPT, TMC, TM2 players (C) 1994-2005 Marcin Lewandowski\n" \
42 "RMT player (C) 2002-2005 Radek Sterba\n" \
43 "DLT player (C) 2009 Marek Konopka\n" \
44 "CMS player (C) 1999 David Spilka\n"
46 /* Short GPL notice.
47 Display after the credits. */
48 #define ASAP_COPYRIGHT \
49 "This program is free software; you can redistribute it and/or modify\n" \
50 "it under the terms of the GNU General Public License as published\n" \
51 "by the Free Software Foundation; either version 2 of the License,\n" \
52 "or (at your option) any later version."
54 /* Maximum length of AUTHOR, NAME and DATE tags including the terminator. */
55 #define ASAP_INFO_CHARS 128
57 /* Maximum length of a "mm:ss.xxx" string including the terminator. */
58 #define ASAP_DURATION_CHARS 10
60 /* Maximum length of a supported input file.
61 You can assume that files longer than this are not supported by ASAP. */
62 #define ASAP_MODULE_MAX 65000
64 /* Maximum number of songs in a file. */
65 #define ASAP_SONGS_MAX 32
67 /* Output sample rate. */
68 #define ASAP_SAMPLE_RATE 44100
70 /* WAV file header length. */
71 #define ASAP_WAV_HEADER_BYTES 44
73 /* Output formats. */
74 typedef enum {
75 ASAP_FORMAT_U8 = 8, /* unsigned char */
76 ASAP_FORMAT_S16_LE = 16, /* signed short, little-endian */
77 ASAP_FORMAT_S16_BE = -16 /* signed short, big-endian */
78 } ASAP_SampleFormat;
80 /* Useful type definitions. */
81 #ifndef FALSE
82 #define FALSE 0
83 #endif
84 #ifndef TRUE
85 #define TRUE 1
86 #endif
87 typedef int abool;
88 typedef unsigned char byte;
90 /* Information about a music file. */
91 typedef struct {
92 char author[ASAP_INFO_CHARS]; /* author's name */
93 char name[ASAP_INFO_CHARS]; /* title */
94 char date[ASAP_INFO_CHARS]; /* creation date */
95 int channels; /* 1 for mono or 2 for stereo */
96 int songs; /* number of subsongs */
97 int default_song; /* 0-based index of the "main" subsong */
98 int durations[ASAP_SONGS_MAX]; /* lengths of songs, in milliseconds, -1 = indeterminate */
99 abool loops[ASAP_SONGS_MAX]; /* whether songs repeat or not */
100 /* the following technical information should not be used outside ASAP. */
101 abool ntsc;
102 int type;
103 int fastplay;
104 int music;
105 int init;
106 int player;
107 int covox_addr;
108 int header_len;
109 byte song_pos[ASAP_SONGS_MAX];
110 } ASAP_ModuleInfo;
112 /* POKEY state.
113 Not for use outside the ASAP engine. */
114 typedef struct {
115 int audctl;
116 abool init;
117 int poly_index;
118 int div_cycles;
119 int mute1;
120 int mute2;
121 int mute3;
122 int mute4;
123 int audf1;
124 int audf2;
125 int audf3;
126 int audf4;
127 int audc1;
128 int audc2;
129 int audc3;
130 int audc4;
131 int tick_cycle1;
132 int tick_cycle2;
133 int tick_cycle3;
134 int tick_cycle4;
135 int period_cycles1;
136 int period_cycles2;
137 int period_cycles3;
138 int period_cycles4;
139 int reload_cycles1;
140 int reload_cycles3;
141 int out1;
142 int out2;
143 int out3;
144 int out4;
145 int delta1;
146 int delta2;
147 int delta3;
148 int delta4;
149 int skctl;
150 int delta_buffer[888];
151 } PokeyState;
153 /* Player state.
154 Only module_info is meant to be read outside the ASAP engine. */
155 typedef struct {
156 int cycle;
157 int cpu_pc;
158 int cpu_a;
159 int cpu_x;
160 int cpu_y;
161 int cpu_s;
162 int cpu_nz;
163 int cpu_c;
164 int cpu_vdi;
165 int scanline_number;
166 int nearest_event_cycle;
167 int next_scanline_cycle;
168 int timer1_cycle;
169 int timer2_cycle;
170 int timer4_cycle;
171 int irqst;
172 int extra_pokey_mask;
173 int consol;
174 byte covox[4];
175 PokeyState base_pokey;
176 PokeyState extra_pokey;
177 int sample_offset;
178 int sample_index;
179 int samples;
180 int iir_acc_left;
181 int iir_acc_right;
182 ASAP_ModuleInfo *module_info;
183 int tmc_per_frame;
184 int tmc_per_frame_counter;
185 int current_song;
186 int current_duration;
187 int blocks_played;
188 int silence_cycles;
189 int silence_cycles_counter;
190 byte poly9_lookup[511];
191 byte poly17_lookup[16385];
192 byte *memory;
193 } ASAP_State;
195 /* Parses the string in the "mm:ss.xxx" format
196 and returns the number of milliseconds or -1 if an error occurs. */
197 int ASAP_ParseDuration(const char *s);
199 /* Converts number of milliseconds to a string in the "mm:ss.xxx" format. */
200 void ASAP_DurationToString(char *s, int duration);
202 /* Checks whether the extension of the passed filename is known to ASAP. */
203 abool ASAP_IsOurFile(const char *filename);
205 /* Checks whether the filename extension is known to ASAP. */
206 abool ASAP_IsOurExt(const char *ext);
208 /* Changes the filename extension, returns true on success. */
209 abool ASAP_ChangeExt(char *filename, const char *ext);
211 /* Gets information about a module.
212 "module_info" is the structure where the information is returned.
213 "filename" determines file format.
214 "module" is the music data (contents of the file).
215 "module_len" is the number of data bytes.
216 ASAP_GetModuleInfo() returns true on success. */
217 abool ASAP_GetModuleInfo(ASAP_ModuleInfo *module_info, const char *filename,
218 const byte module[], int module_len);
220 /* Extracts year from date. */
221 abool ASAP_DateToYear(const char *date, char *year);
223 /* Loads music data.
224 "ast" is the destination structure.
225 "filename" determines file format.
226 "module" is the music data (contents of the file).
227 "module_len" is the number of data bytes.
228 ASAP does not make copies of the passed pointers. You can overwrite
229 or free "filename" and "module" once this function returns.
230 ASAP_Load() returns true on success.
231 If false is returned, the structure is invalid and you cannot
232 call the following functions. */
233 abool ASAP_Load(ASAP_State *ast, const char *filename,
234 const byte module[], int module_len);
236 /* Enables silence detection.
237 Makes ASAP finish playing after the specified period of silence.
238 "ast" is ASAP state initialized by ASAP_Load().
239 "seconds" is the minimum length of silence that ends playback. */
240 void ASAP_DetectSilence(ASAP_State *ast, int seconds);
242 /* Prepares ASAP to play the specified song of the loaded module.
243 "ast" is ASAP state initialized by ASAP_Load().
244 "song" is a zero-based index which must be less than the "songs" field
245 of the ASAP_ModuleInfo structure.
246 "duration" is playback time in milliseconds - use durations[song]
247 unless you want to override it. -1 means indefinitely. */
248 void ASAP_PlaySong(ASAP_State *ast, int song, int duration);
250 /* Mutes the selected POKEY channels.
251 This is only useful for people who want to grab samples of individual
252 instruments.
253 "ast" is ASAP state after calling ASAP_PlaySong().
254 "mask" is a bit mask which selects POKEY channels to be muted.
255 Bits 0-3 control the base POKEY channels,
256 bits 4-7 control the extra POKEY channels. */
257 void ASAP_MutePokeyChannels(ASAP_State *ast, int mask);
259 /* Returns current position in milliseconds.
260 "ast" is ASAP state initialized by ASAP_PlaySong(). */
261 int ASAP_GetPosition(const ASAP_State *ast);
263 /* Rewinds the current song.
264 "ast" is ASAP state initialized by ASAP_PlaySong().
265 "position" is the requested absolute position in milliseconds. */
266 void ASAP_Seek(ASAP_State *ast, int position);
268 /* Fills the specified buffer with WAV file header.
269 "ast" is ASAP state initialized by ASAP_PlaySong() with a positive "duration".
270 "buffer" is buffer of ASAP_WAV_HEADER_BYTES bytes.
271 "format" is the format of samples. */
272 void ASAP_GetWavHeader(const ASAP_State *ast, byte buffer[],
273 ASAP_SampleFormat format);
275 /* Fills the specified buffer with generated samples.
276 "ast" is ASAP state initialized by ASAP_PlaySong().
277 "buffer" is the destination buffer.
278 "buffer_len" is the length of this buffer in bytes.
279 "format" is the format of samples.
280 ASAP_Generate() returns number of bytes actually written
281 (less than buffer_len if reached the end of the song).
282 Normally you use a buffer of a few kilobytes or less,
283 and call ASAP_Generate() in a loop or via a callback. */
284 int ASAP_Generate(ASAP_State *ast, void *buffer, int buffer_len,
285 ASAP_SampleFormat format);
287 /* Checks whether information in the specified file can be edited. */
288 abool ASAP_CanSetModuleInfo(const char *filename);
290 /* Updates the specified module with author, name, date, stereo
291 and song durations as specified in "module_info".
292 "module_info" contains the new module information.
293 "module" is the source file contents.
294 "module_len" is the source file length.
295 "out_module" is the destination buffer of size ASAP_MODULE_MAX.
296 ASAP_SetModuleInfo() returns the resulting file length (number of bytes
297 written to "out_module") or -1 if illegal characters were found. */
298 int ASAP_SetModuleInfo(const ASAP_ModuleInfo *module_info, const byte module[],
299 int module_len, byte out_module[]);
301 /* Checks whether the specified module can be converted to another format.
302 "filename" determines the source format.
303 "module_info" contains the information about the source module,
304 with possibly modified public fields.
305 "module" is the source file contents.
306 "module_len" is the source file length.
307 ASAP_CanConvert() returns the extension of the target format
308 or NULL if there's no possible conversion. */
309 const char *ASAP_CanConvert(const char *filename, const ASAP_ModuleInfo *module_info,
310 const byte module[], int module_len);
312 /* Converts the specified module to the format returned by ASAP_CanConvert().
313 "filename" determines the source format.
314 "module_info" contains the information about the source module,
315 with possibly modified public fields.
316 "module" is the source file contents.
317 "module_len" is the source file length.
318 "out_module" is the destination buffer of size ASAP_MODULE_MAX.
319 ASAP_Convert() returns the resulting file length (number of bytes
320 written to "out_module") or -1 on error. */
321 int ASAP_Convert(const char *filename, const ASAP_ModuleInfo *module_info,
322 const byte module[], int module_len, byte out_module[]);
324 #ifdef __cplusplus
326 #endif
328 #endif