1 /* Game music emulator library C interface (also usable from C++) */ 2 3 /* Game_Music_Emu 0.6.0 */ 4 #ifndef GME_H 5 #define GME_H 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 #define GME_VERSION 0x000600 /* 1 byte major, 1 byte minor, 1 byte patch-level */ 12 13 /* Error string returned by library functions, or NULL if no error (success) */ 14 typedef const char* gme_err_t; 15 16 /* First parameter of most gme_ functions is a pointer to the Music_Emu */ 17 typedef struct Music_Emu Music_Emu; 18 19 20 /******** Basic operations ********/ 21 22 /* Create emulator and load game music file/data into it. Sets *out to new emulator. */ 23 gme_err_t gme_open_file( const char path [], Music_Emu** out, int sample_rate ); 24 25 /* Number of tracks available */ 26 int gme_track_count( Music_Emu const* ); 27 28 /* Start a track, where 0 is the first track */ 29 gme_err_t gme_start_track( Music_Emu*, int index ); 30 31 /* Generate 'count' 16-bit signed samples info 'out'. Output is in stereo. */ 32 gme_err_t gme_play( Music_Emu*, int count, short out [] ); 33 34 /* Finish using emulator and free memory */ 35 void gme_delete( Music_Emu* ); 36 37 38 /******** Track position/length ********/ 39 40 /* Set time to start fading track out. Once fade ends track_ended() returns true. 41 Fade time can be changed while track is playing. */ 42 void gme_set_fade( Music_Emu*, int start_msec ); 43 44 /* True if a track has reached its end */ 45 int gme_track_ended( Music_Emu const* ); 46 47 /* Number of milliseconds (1000 = one second) played since beginning of track */ 48 int gme_tell( Music_Emu const* ); 49 50 /* Seek to new time in track. Seeking backwards or far forward can take a while. */ 51 gme_err_t gme_seek( Music_Emu*, int msec ); 52 53 54 /******** Informational ********/ 55 56 /* If you only need track information from a music file, pass gme_info_only for 57 sample_rate to open/load. */ 58 enum { gme_info_only = -1 }; 59 60 /* Most recent warning string, or NULL if none. Clears current warning after returning. 61 Warning is also cleared when loading a file and starting a track. */ 62 const char* gme_warning( Music_Emu* ); 63 64 /* Load m3u playlist file (must be done after loading music) */ 65 gme_err_t gme_load_m3u( Music_Emu*, const char path [] ); 66 67 /* Clear any loaded m3u playlist and any internal playlist that the music format 68 supports (NSFE for example). */ 69 void gme_clear_playlist( Music_Emu* ); 70 71 /* Gets information for a particular track (length, name, author, etc.). 72 Must be freed after use. */ 73 typedef struct gme_info_t gme_info_t; 74 gme_err_t gme_track_info( Music_Emu const*, gme_info_t** out, int track ); 75 76 /* Frees track information */ 77 void gme_free_info( gme_info_t* ); 78 79 struct gme_info_t 80 { 81 /* times in milliseconds; -1 if unknown */ 82 int length; /* total length, if file specifies it */ 83 int intro_length; /* length of song up to looping section */ 84 int loop_length; /* length of looping section */ 85 86 /* Length if available, otherwise intro_length+loop_length*2 if available, 87 otherwise a default of 150000 (2.5 minutes). */ 88 int play_length; 89 90 int i4,i5,i6,i7,i8,i9,i10,i11,i12,i13,i14,i15; /* reserved */ 91 92 /* empty string ("") if not available */ 93 const char* system; 94 const char* game; 95 const char* song; 96 const char* author; 97 const char* copyright; 98 const char* comment; 99 const char* dumper; 100 101 const char *s7,*s8,*s9,*s10,*s11,*s12,*s13,*s14,*s15; /* reserved */ 102 }; 103 104 105 /******** Advanced playback ********/ 106 107 /* Adjust stereo echo depth, where 0.0 = off and 1.0 = maximum. Has no effect for 108 GYM, SPC, and Sega Genesis VGM music */ 109 void gme_set_stereo_depth( Music_Emu*, double depth ); 110 111 /* Disable automatic end-of-track detection and skipping of silence at beginning 112 if ignore is true */ 113 void gme_ignore_silence( Music_Emu*, int ignore ); 114 115 /* Adjust song tempo, where 1.0 = normal, 0.5 = half speed, 2.0 = double speed. 116 Track length as returned by track_info() assumes a tempo of 1.0. */ 117 void gme_set_tempo( Music_Emu*, double tempo ); 118 119 /* Number of voices used by currently loaded file */ 120 int gme_voice_count( Music_Emu const* ); 121 122 /* Name of voice i, from 0 to gme_voice_count() - 1 */ 123 const char* gme_voice_name( Music_Emu const*, int i ); 124 125 /* Mute/unmute voice i, where voice 0 is first voice */ 126 void gme_mute_voice( Music_Emu*, int index, int mute ); 127 128 /* Set muting state of all voices at once using a bit mask, where -1 mutes all 129 voices, 0 unmutes them all, 0x01 mutes just the first voice, etc. */ 130 void gme_mute_voices( Music_Emu*, int muting_mask ); 131 132 /* Frequency equalizer parameters (see gme.txt) */ 133 /* Implementers: If modified, also adjust Music_Emu::make_equalizer as needed */ 134 typedef struct gme_equalizer_t 135 { 136 double treble; /* -50.0 = muffled, 0 = flat, +5.0 = extra-crisp */ 137 double bass; /* 1 = full bass, 90 = average, 16000 = almost no bass */ 138 139 double d2,d3,d4,d5,d6,d7,d8,d9; /* reserved */ 140 } gme_equalizer_t; 141 142 /* Get current frequency equalizater parameters */ 143 void gme_equalizer( Music_Emu const*, gme_equalizer_t* out ); 144 145 /* Change frequency equalizer parameters */ 146 void gme_set_equalizer( Music_Emu*, gme_equalizer_t const* eq ); 147 148 /* Enables/disables most accurate sound emulation options */ 149 void gme_enable_accuracy( Music_Emu*, int enabled ); 150 151 152 /******** Game music types ********/ 153 154 /* Music file type identifier. Can also hold NULL. */ 155 typedef const struct gme_type_t_* gme_type_t; 156 157 /* Emulator type constants for each supported file type */ 158 extern const gme_type_t 159 gme_ay_type, 160 gme_gbs_type, 161 gme_gym_type, 162 gme_hes_type, 163 gme_kss_type, 164 gme_nsf_type, 165 gme_nsfe_type, 166 gme_sap_type, 167 gme_spc_type, 168 gme_vgm_type, 169 gme_vgz_type; 170 171 /* Type of this emulator */ 172 gme_type_t gme_type( Music_Emu const* ); 173 174 /* Pointer to array of all music types, with NULL entry at end. Allows a player linked 175 to this library to support new music types without having to be updated. */ 176 gme_type_t const* gme_type_list(); 177 178 /* Name of game system for this music file type */ 179 const char* gme_type_system( gme_type_t ); 180 181 /* True if this music file type supports multiple tracks */ 182 int gme_type_multitrack( gme_type_t ); 183 184 185 /******** Advanced file loading ********/ 186 187 /* Error returned if file type is not supported */ 188 extern const char* const gme_wrong_file_type; 189 190 /* Same as gme_open_file(), but uses file data already in memory. Makes copy of data. */ 191 gme_err_t gme_open_data( void const* data, long size, Music_Emu** out, int sample_rate ); 192 193 /* Determine likely game music type based on first four bytes of file. Returns 194 string containing proper file suffix (i.e. "NSF", "SPC", etc.) or "" if 195 file header is not recognized. */ 196 const char* gme_identify_header( void const* header ); 197 198 /* Get corresponding music type for file path or extension passed in. */ 199 gme_type_t gme_identify_extension( const char path_or_extension [] ); 200 201 /* Determine file type based on file's extension or header (if extension isn't recognized). 202 Sets *type_out to type, or 0 if unrecognized or error. */ 203 gme_err_t gme_identify_file( const char path [], gme_type_t* type_out ); 204 205 /* Create new emulator and set sample rate. Returns NULL if out of memory. If you only need 206 track information, pass gme_info_only for sample_rate. */ 207 Music_Emu* gme_new_emu( gme_type_t, int sample_rate ); 208 209 /* Load music file into emulator */ 210 gme_err_t gme_load_file( Music_Emu*, const char path [] ); 211 212 /* Load music file from memory into emulator. Makes a copy of data passed. */ 213 gme_err_t gme_load_data( Music_Emu*, void const* data, long size ); 214 215 /* Load music file using custom data reader function that will be called to 216 read file data. Most emulators load the entire file in one read call. */ 217 typedef gme_err_t (*gme_reader_t)( void* your_data, void* out, int count ); 218 gme_err_t gme_load_custom( Music_Emu*, gme_reader_t, long file_size, void* your_data ); 219 220 /* Load m3u playlist file from memory (must be done after loading music) */ 221 gme_err_t gme_load_m3u_data( Music_Emu*, void const* data, long size ); 222 223 224 /******** User data ********/ 225 226 /* Set/get pointer to data you want to associate with this emulator. 227 You can use this for whatever you want. */ 228 void gme_set_user_data( Music_Emu*, void* new_user_data ); 229 void* gme_user_data( Music_Emu const* ); 230 231 /* Register cleanup function to be called when deleting emulator, or NULL to 232 clear it. Passes user_data to cleanup function. */ 233 typedef void (*gme_user_cleanup_t)( void* user_data ); 234 void gme_set_user_cleanup( Music_Emu*, gme_user_cleanup_t func ); 235 236 237 #ifdef __cplusplus 238 } 239 #endif 240 241 #endif 242