apps/codecs/libasap/asap.h

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