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   2
  35 #define ASAP_VERSION         "2.1.2"
  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     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;
 111
 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;
 152
 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;
 194
 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);
 198
 199 /* Converts number of milliseconds to a string in the "mm:ss.xxx" format. */
 200 void ASAP_DurationToString(char *s, int duration);
 201
 202 /* Checks whether the extension of the passed filename is known to ASAP. */
 203 abool ASAP_IsOurFile(const char *filename);
 204
 205 /* Checks whether the filename extension is known to ASAP. */
 206 abool ASAP_IsOurExt(const char *ext);
 207
 208 /* Changes the filename extension, returns true on success. */
 209 abool ASAP_ChangeExt(char *filename, const char *ext);
 210
 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);
 219
 220 /* Extracts year from date. */
 221 abool ASAP_DateToYear(const char *date, char *year);
 222
 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);
 235
 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);
 241
 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);
 249
 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);
 258
 259 /* Returns current position in milliseconds.
 260    "ast" is ASAP state initialized by ASAP_PlaySong(). */
 261 int ASAP_GetPosition(const ASAP_State *ast);
 262
 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);
 267
 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);
 274
 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);
 286
 287 /* Checks whether information in the specified file can be edited. */
 288 abool ASAP_CanSetModuleInfo(const char *filename);
 289
 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[]);
 300
 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);
 311
 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[]);
 323
 324 #ifdef __cplusplus
 325 }
 326 #endif
 327
 328 #endif