apps/codecs/libasap/asap.h

   1 /*
   2  * asap.h - public interface of ASAP
   3  *
   4  * Copyright (C) 2005-2010  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   2
  33 #define ASAP_VERSION_MINOR   1
  34 #define ASAP_VERSION_MICRO   0
  35 #define ASAP_VERSION         "2.1.0"
  36
  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"
  45
  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."
  53
  54 /* Maximum length of AUTHOR, NAME and DATE tags including the terminator. */
  55 #define ASAP_INFO_CHARS         128
  56
  57 /* Maximum length of a "mm:ss.xxx" string including the terminator. */
  58 #define ASAP_DURATION_CHARS     10
  59
  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
  63
  64 /* Maximum number of songs in a file. */
  65 #define ASAP_SONGS_MAX          32
  66
  67 /* Output sample rate. */
  68 #define ASAP_SAMPLE_RATE        44100
  69
  70 /* WAV file header length. */
  71 #define ASAP_WAV_HEADER_BYTES   44
  72
  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;
  79
  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;
  89
  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     int type;
 102     int fastplay;
 103     int music;
 104     int init;
 105     int player;
 106     int covox_addr;
 107     int header_len;
 108     byte song_pos[ASAP_SONGS_MAX];
 109 } ASAP_ModuleInfo;
 110
 111 /* POKEY state.
 112    Not for use outside the ASAP engine. */
 113 typedef struct {
 114     int audctl;
 115     abool init;
 116     int poly_index;
 117     int div_cycles;
 118     int mute1;
 119     int mute2;
 120     int mute3;
 121     int mute4;
 122     int audf1;
 123     int audf2;
 124     int audf3;
 125     int audf4;
 126     int audc1;
 127     int audc2;
 128     int audc3;
 129     int audc4;
 130     int tick_cycle1;
 131     int tick_cycle2;
 132     int tick_cycle3;
 133     int tick_cycle4;
 134     int period_cycles1;
 135     int period_cycles2;
 136     int period_cycles3;
 137     int period_cycles4;
 138     int reload_cycles1;
 139     int reload_cycles3;
 140     int out1;
 141     int out2;
 142     int out3;
 143     int out4;
 144     int delta1;
 145     int delta2;
 146     int delta3;
 147     int delta4;
 148     int skctl;
 149     int delta_buffer[888];
 150 } PokeyState;
 151
 152 /* Player state.
 153    Only module_info is meant to be read outside the ASAP engine. */
 154 typedef struct {
 155     int cycle;
 156     int cpu_pc;
 157     int cpu_a;
 158     int cpu_x;
 159     int cpu_y;
 160     int cpu_s;
 161     int cpu_nz;
 162     int cpu_c;
 163     int cpu_vdi;
 164     int scanline_number;
 165     int nearest_event_cycle;
 166     int next_scanline_cycle;
 167     int timer1_cycle;
 168     int timer2_cycle;
 169     int timer4_cycle;
 170     int irqst;
 171     int extra_pokey_mask;
 172     int consol;
 173     byte covox[4];
 174     PokeyState base_pokey;
 175     PokeyState extra_pokey;
 176     int sample_offset;
 177     int sample_index;
 178     int samples;
 179     int iir_acc_left;
 180     int iir_acc_right;
 181     ASAP_ModuleInfo module_info;
 182     int tmc_per_frame;
 183     int tmc_per_frame_counter;
 184     int current_song;
 185     int current_duration;
 186     int blocks_played;
 187     int silence_cycles;
 188     int silence_cycles_counter;
 189     byte poly9_lookup[511];
 190     byte poly17_lookup[16385];
 191     byte memory[65536];
 192 } ASAP_State;
 193
 194 /* Parses the string in the "mm:ss.xxx" format
 195    and returns the number of milliseconds or -1 if an error occurs. */
 196 int ASAP_ParseDuration(const char *s);
 197
 198 /* Converts number of milliseconds to a string in the "mm:ss.xxx" format. */
 199 void ASAP_DurationToString(char *s, int duration);
 200
 201 /* Checks whether the extension of the passed filename is known to ASAP. */
 202 abool ASAP_IsOurFile(const char *filename);
 203
 204 /* Checks whether the filename extension is known to ASAP. */
 205 abool ASAP_IsOurExt(const char *ext);
 206
 207 /* Changes the filename extension, returns true on success. */
 208 abool ASAP_ChangeExt(char *filename, const char *ext);
 209
 210 /* Gets information about a module.
 211    "module_info" is the structure where the information is returned.
 212    "filename" determines file format.
 213    "module" is the music data (contents of the file).
 214    "module_len" is the number of data bytes.
 215    ASAP_GetModuleInfo() returns true on success. */
 216 abool ASAP_GetModuleInfo(ASAP_ModuleInfo *module_info, const char *filename,
 217                          const byte module[], int module_len);
 218
 219 /* Loads music data.
 220    "ast" is the destination structure.
 221    "filename" determines file format.
 222    "module" is the music data (contents of the file).
 223    "module_len" is the number of data bytes.
 224    ASAP does not make copies of the passed pointers. You can overwrite
 225    or free "filename" and "module" once this function returns.
 226    ASAP_Load() returns true on success.
 227    If false is returned, the structure is invalid and you cannot
 228    call the following functions. */
 229 abool ASAP_Load(ASAP_State *ast, const char *filename,
 230                 const byte module[], int module_len);
 231
 232 /* Enables silence detection.
 233    Makes ASAP finish playing after the specified period of silence.
 234    "ast" is ASAP state initialized by ASAP_Load().
 235    "seconds" is the minimum length of silence that ends playback. */
 236 void ASAP_DetectSilence(ASAP_State *ast, int seconds);
 237
 238 /* Prepares ASAP to play the specified song of the loaded module.
 239    "ast" is ASAP state initialized by ASAP_Load().
 240    "song" is a zero-based index which must be less than the "songs" field
 241    of the ASAP_ModuleInfo structure.
 242    "duration" is playback time in milliseconds - use durations[song]
 243    unless you want to override it. -1 means indefinitely. */
 244 void ASAP_PlaySong(ASAP_State *ast, int song, int duration);
 245
 246 /* Mutes the selected POKEY channels.
 247    This is only useful for people who want to grab samples of individual
 248    instruments.
 249    "ast" is ASAP state after calling ASAP_PlaySong().
 250    "mask" is a bit mask which selects POKEY channels to be muted.
 251    Bits 0-3 control the base POKEY channels,
 252    bits 4-7 control the extra POKEY channels. */
 253 void ASAP_MutePokeyChannels(ASAP_State *ast, int mask);
 254
 255 /* Returns current position in milliseconds.
 256    "ast" is ASAP state initialized by ASAP_PlaySong(). */
 257 int ASAP_GetPosition(const ASAP_State *ast);
 258
 259 /* Rewinds the current song.
 260    "ast" is ASAP state initialized by ASAP_PlaySong().
 261    "position" is the requested absolute position in milliseconds. */
 262 void ASAP_Seek(ASAP_State *ast, int position);
 263
 264 /* Fills the specified buffer with WAV file header.
 265    "ast" is ASAP state initialized by ASAP_PlaySong() with a positive "duration".
 266    "buffer" is buffer of ASAP_WAV_HEADER_BYTES bytes.
 267    "format" is the format of samples. */
 268 void ASAP_GetWavHeader(const ASAP_State *ast, byte buffer[],
 269                        ASAP_SampleFormat format);
 270
 271 /* Fills the specified buffer with generated samples.
 272    "ast" is ASAP state initialized by ASAP_PlaySong().
 273    "buffer" is the destination buffer.
 274    "buffer_len" is the length of this buffer in bytes.
 275    "format" is the format of samples.
 276    ASAP_Generate() returns number of bytes actually written
 277    (less than buffer_len if reached the end of the song).
 278    Normally you use a buffer of a few kilobytes or less,
 279    and call ASAP_Generate() in a loop or via a callback. */
 280 int ASAP_Generate(ASAP_State *ast, void *buffer, int buffer_len,
 281                   ASAP_SampleFormat format);
 282
 283 /* Checks whether information in the specified file can be edited. */
 284 abool ASAP_CanSetModuleInfo(const char *filename);
 285
 286 /* Updates the specified module with author, name, date, stereo
 287    and song durations as specified in "module_info".
 288    "module_info" contains the new module information.
 289    "module" is the source file contents.
 290    "module_len" is the source file length.
 291    "out_module" is the destination buffer of size ASAP_MODULE_MAX.
 292    ASAP_SetModuleInfo() returns the resulting file length (number of bytes
 293    written to "out_module") or -1 if illegal characters were found. */
 294 int ASAP_SetModuleInfo(const ASAP_ModuleInfo *module_info, const byte module[],
 295                        int module_len, byte out_module[]);
 296
 297 /* Checks whether the specified module can be converted to another format.
 298    "filename" determines the source format.
 299    "module_info" contains the information about the source module,
 300    with possibly modified public fields.
 301    "module" is the source file contents.
 302    "module_len" is the source file length.
 303    ASAP_CanConvert() returns the extension of the target format
 304    or NULL if there's no possible conversion. */
 305 const char *ASAP_CanConvert(const char *filename, const ASAP_ModuleInfo *module_info,
 306                             const byte module[], int module_len);
 307
 308 /* Converts the specified module to the format returned by ASAP_CanConvert().
 309    "filename" determines the source format.
 310    "module_info" contains the information about the source module,
 311    with possibly modified public fields.
 312    "module" is the source file contents.
 313    "module_len" is the source file length.
 314    "out_module" is the destination buffer of size ASAP_MODULE_MAX.
 315    ASAP_Convert() returns the resulting file length (number of bytes
 316    written to "out_module") or -1 on error. */
 317 int ASAP_Convert(const char *filename, const ASAP_ModuleInfo *module_info,
 318                  const byte module[], int module_len, byte out_module[]);
 319
 320 #ifdef __cplusplus
 321 }
 322 #endif
 323
 324 #endif