Mercurial > audlegacy-plugins
comparison src/console/gme.h @ 316:fb513e10174e trunk
[svn] - merge libconsole-blargg into mainline libconsole:
+ obsoletes plugins-ugly:sapplug
author | nenolod |
---|---|
date | Thu, 30 Nov 2006 19:54:33 -0800 |
parents | |
children | 986f098da058 |
comparison
equal
deleted
inserted
replaced
315:2294f3a6f136 | 316:fb513e10174e |
---|---|
1 /* Game music emulator library C interface (also usable from C++) */ | |
2 | |
3 /* Game_Music_Emu 0.5.1 */ | |
4 #ifndef GME_H | |
5 #define GME_H | |
6 | |
7 #ifdef __cplusplus | |
8 extern "C" { | |
9 #endif | |
10 | |
11 /* Error string returned by library functions, or NULL if no error (success) */ | |
12 typedef const char* gme_err_t; | |
13 | |
14 /* First parameter of most gme_ functions is a pointer to the Music_Emu */ | |
15 typedef struct Music_Emu Music_Emu; | |
16 | |
17 | |
18 /******** Game music types ********/ | |
19 | |
20 /* Emulator type constants for each supported file type */ | |
21 extern struct gme_type_t_ const gme_ay_type [], gme_gbs_type [], gme_gym_type [], | |
22 gme_hes_type [], gme_kss_type [], gme_nsf_type [], gme_nsfe_type [], | |
23 gme_sap_type [], gme_spc_type [], gme_vgm_type [], gme_vgz_type []; | |
24 typedef struct gme_type_t_ const* gme_type_t; | |
25 | |
26 /* Determine likely game music type based on first four bytes of file. Returns | |
27 string containing proper file suffix (i.e. "NSF", "SPC", etc.) or "" if | |
28 file header is not recognized. */ | |
29 const char* gme_identify_header( void const* header ); | |
30 | |
31 /* Pointer to array of music types, with NULL entry at end. Allows a player linked | |
32 to this library to support new music types without having to be updated. */ | |
33 gme_type_t const* gme_type_list(); | |
34 | |
35 /* Get corresponding music type for file extension passed in. Types points to | |
36 an array of gme_type_t elements with a NULL terminator at the end. */ | |
37 gme_type_t gme_identify_extension( const char* extension, gme_type_t const* types ); | |
38 | |
39 /* Determine file type based on file's extension or header (if extension isn't recognized) */ | |
40 gme_err_t gme_identify_file( const char* path, gme_type_t const* types, gme_type_t* type_out ); | |
41 | |
42 /* gme_type_t is a pointer to this structure. For example, gme_nsf_type->system is | |
43 "Nintendo NES" and gme_nsf_type->new_emu() is equilvant to new Nsf_Emu (in C++). */ | |
44 struct gme_type_t_ | |
45 { | |
46 const char* system; /* name of system this music file type is generally for */ | |
47 int track_count; /* non-zero for formats with a fixed number of tracks */ | |
48 Music_Emu* (*new_emu)(); /* Create new emulator for this type (useful in C++ only) */ | |
49 Music_Emu* (*new_info)(); /* Create new info reader for this type */ | |
50 | |
51 /* internal */ | |
52 const char* extension_; | |
53 int flags_; | |
54 }; | |
55 | |
56 | |
57 /******** Emulator creation/cleanup ********/ | |
58 | |
59 /* Create new emulator and set sample rate. Returns NULL if out of memory. */ | |
60 Music_Emu* gme_new_emu( gme_type_t, long sample_rate ); | |
61 | |
62 /* Create new music file info reader. Same as gme_new_emu() except it does not | |
63 support playback functions. It *does* support an m3u playlist. */ | |
64 Music_Emu* gme_new_info( gme_type_t ); | |
65 | |
66 /* Error returned if file is wrong type */ | |
67 extern const char gme_wrong_file_type []; | |
68 | |
69 /* Type of this emulator */ | |
70 gme_type_t gme_type( Music_Emu const* ); | |
71 | |
72 /* Finish using emulator and free memory */ | |
73 void gme_delete( Music_Emu* ); | |
74 | |
75 | |
76 /******** File loading ********/ | |
77 | |
78 /* Load music file */ | |
79 gme_err_t gme_load_file( Music_Emu*, const char* path ); | |
80 | |
81 /* Load music file from memory. Makes a copy of data passed. */ | |
82 gme_err_t gme_load_data( Music_Emu*, const void* data, long size ); | |
83 | |
84 /* Load music file using custom data reader function that will be called to | |
85 read file data. Most emulators load the entire file in one call. */ | |
86 typedef gme_err_t (*gme_reader_t)( void* your_data, void* out, long count ); | |
87 gme_err_t gme_load_custom( Music_Emu*, gme_reader_t, long file_size, void* your_data ); | |
88 | |
89 /* Load m3u playlist file (must be done after loading file) */ | |
90 gme_err_t gme_load_m3u( Music_Emu*, const char* path ); | |
91 | |
92 /* Load m3u playlist file from memory (must be done after loading file) */ | |
93 gme_err_t gme_load_m3u_data( Music_Emu*, const void* data, long size ); | |
94 | |
95 /* Clears any loaded m3u playlist and any internal playlist that the music format | |
96 supports (NSFE for example). */ | |
97 void gme_clear_playlist( Music_Emu* ); | |
98 | |
99 /* Most recent warning string, or NULL if none. Clears current warning after returning. */ | |
100 const char* gme_warning( Music_Emu* ); | |
101 | |
102 | |
103 /******** Track information ********/ | |
104 | |
105 /* Number of tracks in file/playlist */ | |
106 int gme_track_count( Music_Emu const* ); | |
107 | |
108 /* Get information for a particular track (length, name, author, etc.) */ | |
109 typedef struct track_info_t track_info_t; | |
110 gme_err_t gme_track_info( Music_Emu const*, track_info_t* out, int track ); | |
111 | |
112 enum { gme_max_field = 255 }; | |
113 struct track_info_t | |
114 { | |
115 long track_count; | |
116 | |
117 /* times in milliseconds; -1 if unknown */ | |
118 long length; | |
119 long intro_length; | |
120 long loop_length; | |
121 | |
122 /* empty string if not available */ | |
123 char system [256]; | |
124 char game [256]; | |
125 char song [256]; | |
126 char author [256]; | |
127 char copyright [256]; | |
128 char comment [256]; | |
129 char dumper [256]; | |
130 }; | |
131 | |
132 | |
133 /******** Basic playback ********/ | |
134 | |
135 /* Start a track, where 0 is the first track. Also clears warning string. */ | |
136 gme_err_t gme_start_track( Music_Emu*, int index ); | |
137 | |
138 /* Set start time and length of track fade out. Once fade ends track_ended() returns | |
139 true. Fade time can be changed while track is playing. */ | |
140 void gme_set_fade( Music_Emu*, long start_msec ); | |
141 | |
142 /* Generate 'count' samples info 'buf'. Output is in stereo. Any emulation | |
143 errors set warning string, and major errors also end track. */ | |
144 gme_err_t gme_play( Music_Emu*, long sample_count, short* out ); | |
145 | |
146 /* True if a track has reached its end */ | |
147 int gme_track_ended( Music_Emu const* ); | |
148 | |
149 /* Number of milliseconds (1000 msec = 1 second) played since beginning of track */ | |
150 long gme_tell( Music_Emu const* ); | |
151 | |
152 /* Seek to new time in track. Seeking backwards or far forward can take a while. */ | |
153 gme_err_t gme_seek( Music_Emu*, long msec ); | |
154 | |
155 | |
156 /******** Advanced playback ********/ | |
157 | |
158 /* Adjust stereo echo depth, where 0.0 = off and 1.0 = maximum. Has no effect for | |
159 GYM, SPC, and Sega Genesis VGM music */ | |
160 void gme_set_stereo_depth( Music_Emu*, double depth ); | |
161 | |
162 /* Disable automatic end-of-track detection and skipping of silence at beginning | |
163 if ignore is true */ | |
164 void gme_ignore_silence( Music_Emu*, int ignore ); | |
165 | |
166 /* Adjust song tempo, where 1.0 = normal, 0.5 = half speed, 2.0 = double speed. | |
167 Track length as returned by track_info() assumes a tempo of 1.0. */ | |
168 void gme_set_tempo( Music_Emu*, double tempo ); | |
169 | |
170 /* Number of voices used by currently loaded file */ | |
171 int gme_voice_count( Music_Emu const* ); | |
172 | |
173 /* Names of voices */ | |
174 const char** gme_voice_names( Music_Emu const* ); | |
175 | |
176 /* Mute/unmute voice i, where voice 0 is first voice */ | |
177 void gme_mute_voice( Music_Emu*, int index, int mute ); | |
178 | |
179 /* Set muting state of all voices at once using a bit mask, where -1 mutes all | |
180 voices, 0 unmutes them all, 0x01 mutes just the first voice, etc. */ | |
181 void gme_mute_voices( Music_Emu*, int muting_mask ); | |
182 | |
183 /* Frequency equalizer parameters (see gme.txt) */ | |
184 typedef struct gme_equalizer_t | |
185 { | |
186 double treble; /* -50.0 = muffled, 0 = flat, +5.0 = extra-crisp */ | |
187 long bass; /* 1 = full bass, 90 = average, 16000 = almost no bass */ | |
188 } gme_equalizer_t; | |
189 | |
190 /* Get current frequency equalizater parameters */ | |
191 gme_equalizer_t gme_equalizer( Music_Emu const* ); | |
192 | |
193 /* Change frequency equalizer parameters */ | |
194 void gme_set_equalizer( Music_Emu*, gme_equalizer_t const* eq ); | |
195 | |
196 | |
197 #ifdef __cplusplus | |
198 } | |
199 #endif | |
200 | |
201 #endif |