src/lib/gme/gme.pas

   1 unit GME;
   2
   3 {$IFDEF FPC}
   4 {$PACKRECORDS C}
   5 {$MODE OBJFPC}
   6 {$ENDIF}
   7
   8 interface
   9
  10 uses ctypes;
  11
  12 {$IF DEFINED(WINDOWS)}
  13   {$IFDEF LIBGME_WINDOZE_STATIC}
  14     {$ERROR libgme won't static-link on Windows until we switch to FPC 3.2.0}
  15     // {$LINKLIB libgme.a}
  16   {$ELSE}
  17     {$DEFINE GME_DYNAMIC}
  18     const gmelib = 'libgme.dll';
  19   {$ENDIF}
  20 {$ELSEIF DEFINED(UNIX)}
  21   {$DEFINE GME_DYNAMIC}
  22   {$LINKLIB libgme}
  23   const gmelib = 'libgme.so';
  24 {$ELSE}
  25   {$ERROR libgme not supported on this platform. Fix it!}
  26 {$ENDIF}
  27
  28 type
  29   // first parameter of most gme_ functions is a pointer to the Music_Emu
  30   pgme_music_emu = pointer;
  31   ppgme_music_emu = ^pgme_music_emu;
  32
  33   // track information
  34   gme_info_t = record
  35     // times in milliseconds, -1 if unknown
  36     length:       longint; // total length, if file specifies it
  37     intro_length: longint; // length of song up to looping section
  38     loop_length:  longint; // length of looping section
  39     play_length:  longint; // length if available, otherwise intro_length+loop_length*2 if available,
  40                            // otherwise a default of 150000 (2.5 minutes).
  41     i4,i5,i6,i7,i8,i9,i10,i11,i12,i13,i14,i15: longint; // reserved (jesus christ)
  42     // various metadata (empty string if not available)
  43     system:    pchar;
  44     game:      pchar;
  45     song:      pchar;
  46     author:    pchar;
  47     copyright: pchar;
  48     comment:   pchar;
  49     dump:      pchar;
  50     // reserved (holy fuck)
  51     s7,s8,s9,s10,s11,s12,s13,s14,s15: pchar;
  52   end;
  53   pgme_info_t = ^gme_info_t;
  54   ppgme_info_t = ^pgme_info_t;
  55
  56   // frequency equalizer parameters
  57   gme_equalizer_t = record
  58     treble: double;
  59     bass: double;
  60     d2,d3,d4,d5,d6,d7,d8,d9: double; // reserved (please stop)
  61   end;
  62   pgme_equalizer_t = ^gme_equalizer_t;
  63
  64   // music file type identifier; can also hold NULL
  65   gme_type_t = pointer;
  66   pgme_type_t = ^gme_type_t;
  67
  68   // all errors are just const char* msg, NULL === success
  69   gme_err_t = pchar;
  70
  71 const
  72   gme_info_only = -1;
  73
  74 var
  75   // emulator type constants for each supported file type
  76   gme_ay_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  77   gme_gbs_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  78   gme_gym_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  79   gme_hes_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  80   gme_kss_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  81   gme_nsf_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  82   gme_nsfe_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  83   gme_sap_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  84   gme_spc_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  85   gme_vgm_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  86   gme_vgz_type: gme_type_t; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  87
  88   // error returned if GME encounters an invalid file type
  89   gme_wrong_file_type: pchar; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  90
  91 { basic API }
  92
  93 // create emulator and load game music file/data into it. Sets *out to new emulator.
  94 function gme_open_file(const path: pchar; eout: ppgme_music_emu; sample_rate: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  95
  96 // same as gme_open_file(), but uses file data already in memory; makes copy of data;
  97 // the resulting Music_Emu object will be set to single channel mode
  98 function gme_open_data(const data: pointer; size: clong; eout: ppgme_music_emu; sample_rate: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
  99
 100 // number of tracks available
 101 function gme_track_count(const emu: pgme_music_emu): longint; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 102
 103 // start a track, where 0 is the first track
 104 function gme_start_track(emu: pgme_music_emu; track: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 105
 106 // generate 'count' 16-bit signed samples into 'out'; output is in stereo
 107 function gme_play(emu: pgme_music_emu; count: longint; buf: pword): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 108
 109 // finish using emulator and free memory
 110 procedure gme_delete(emu: pgme_music_emu); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 111
 112 { track positioning }
 113
 114 // Set time to start fading track out. Once fade ends track_ended() returns true.
 115 // Fade time can be changed while track is playing.
 116 procedure gme_set_fade(emu: pgme_music_emu; start_msec: longint); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 117
 118 // true if a track has reached its end
 119 function gme_track_ended(const emu: pgme_music_emu): longint; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 120
 121 // number of milliseconds (1000 = one second) played since beginning of track
 122 function gme_tell(const emu: pgme_music_emu): longint; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 123
 124 // number of samples generated since beginning of track
 125 function gme_tell_samples(const emu: pgme_music_emu): longint; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 126
 127 // seek to new time in track; seeking backwards or far forward can take a while
 128 function gme_seek(emu: pgme_music_emu; msec: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 129
 130 // equivalent to restarting track then skipping n samples
 131 function gme_seek_samples(emu: pgme_music_emu; n: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 132
 133 // If do_autoload_limit is nonzero, then automatically load track length
 134 // metadata (if present) and terminate playback once the track length has been
 135 // reached. Otherwise playback will continue for an arbitrary period of time
 136 // until a prolonged period of silence is detected.
 137 // By default, playback limits are loaded and applied.
 138 procedure gme_set_autoload_playback_limit(emu: pgme_music_emu; do_autoload_limit: longint); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 139
 140 { informational }
 141
 142 // most recent warning string, or NULL if none; clears current warning after returning
 143 function gme_warning(emu: pgme_music_emu): pchar; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 144
 145 // gets information for a particular track (length, name, author, etc.); must be freed after use
 146 function gme_track_info(const emu: pgme_music_emu; iout: ppgme_info_t; track: longint): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 147
 148 // frees track information
 149 procedure gme_free_info(info: pgme_info_t); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 150
 151 { advanced playback }
 152
 153 // Adjust stereo echo depth, where 0.0 = off and 1.0 = maximum.
 154 // Has no effect for GYM, SPC, and Sega Genesis VGM music
 155 procedure gme_set_stereo_depth(emu: pgme_music_emu; depth: double); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 156
 157 // enables/disables most accurate sound emulation options
 158 procedure gme_enable_accuracy(emu: pgme_music_emu; enable: longint); cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 159
 160 { music type ident }
 161
 162 // Type of this emulator
 163 function gme_type(const emu: pgme_music_emu): gme_type_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 164
 165 // Pointer to array of all music types, with NULL entry at end. Allows a player linked
 166 // to this library to support new music types without having to be updated.
 167 function gme_type_list(): pgme_type_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 168
 169 // Determine likely game music type based on first four bytes of file. Returns
 170 // string containing proper file suffix (i.e. "NSF", "SPC", etc.) or "" if
 171 // file header is not recognized.
 172 function gme_identify_header(const header: pointer): pchar; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 173
 174 // Get corresponding music type for file path or extension passed in.
 175 function gme_identify_extension(const path_or_extension: pchar): gme_type_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 176
 177 // Create new emulator and set sample rate. Returns NULL if out of memory.
 178 // If you only need track information, pass gme_info_only for sample_rate.
 179 function gme_new_emu(stype: gme_type_t; sample_rate: longint): pgme_music_emu; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 180
 181 // Load music file into emulator
 182 function gme_load_file(emu: pgme_music_emu; const path: pchar): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 183
 184 // Load music file from memory into emulator. Makes a copy of data passed.
 185 function gme_load_data(emu: pgme_music_emu; const data: pointer; len: clong): gme_err_t; cdecl; external {$IFDEF GME_DYNAMIC}gmelib{$ENDIF};
 186
 187
 188 implementation
 189
 190
 191 end.