Mercurial > audlegacy-plugins
comparison src/Input/console/gme_notes.txt @ 0:13389e613d67 trunk
[svn] - initial import of audacious-plugins tree (lots to do)
author | nenolod |
---|---|
date | Mon, 18 Sep 2006 01:11:49 -0700 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:13389e613d67 |
---|---|
1 Game_Music_Emu 0.3.0 Notes | |
2 -------------------------- | |
3 Author : Shay Green <hotpop.com@blargg> | |
4 Website: http://www.slack.net/~ant/ | |
5 Forum : http://groups.google.com/group/blargg-sound-libs | |
6 | |
7 | |
8 Overview | |
9 -------- | |
10 This library is composed of several independent game music emulators | |
11 derived from the common Music_Emu interface. Each emulator can load a | |
12 game music file and play from any track. To play a game music file, do | |
13 the following: | |
14 | |
15 - Determine file's type | |
16 - Create appropriate emulator | |
17 - Set sample rate | |
18 - Load file into emulator | |
19 - Start desired track | |
20 - When samples are needed, call play() | |
21 - When done, delete emulator | |
22 | |
23 See Music_Emu.h for reference. | |
24 | |
25 | |
26 Information Fields | |
27 ------------------ | |
28 Game music files include text fields with information about the game and | |
29 track. These are stored in the file's header or in an embedded block. | |
30 Text fields in most game music formats do *not* have a nul terminator if | |
31 the string completely fills the field. The simplest way to handle this | |
32 is to copy the string out and manually add a nul terminator at the end. | |
33 | |
34 This library is currently focused only on actual emulation, so it | |
35 doesn't provide a common interface to the different schemes each game | |
36 music file format uses. Refer to the file's official specification for | |
37 further information. | |
38 | |
39 | |
40 Modular Construction | |
41 -------------------- | |
42 The library is made of many fairly independent modules. If you're using | |
43 only one music file emulator, you can eliminate many of the library | |
44 sources from your program. Refer to the files list in readme.txt to get | |
45 a general idea of what can be removed. Post to the forum if you'd like | |
46 me to put together a smaller version for a particular use, as this only | |
47 takes me a few minutes to do. | |
48 | |
49 If you want to use one of the individual sound chip emulators in your | |
50 console emulator, first check the libraries page on my website since I | |
51 have released several of them as standalone libraries with included | |
52 documentation and examples on their use. | |
53 | |
54 The "classic" sound chips use my Blip_Buffer library, which greatly | |
55 simplifies their implementation and efficiently handles band-limited | |
56 synthesis. It is also available as a standalone library with | |
57 documentation and many examples. | |
58 | |
59 | |
60 Sound Parameters | |
61 ---------------- | |
62 All emulators support adjustable output sampling rate, set with | |
63 Music_Emu::set_sample_rate(). A rate of 44100 should work well on most | |
64 systems. Since band-limited synthesis is used, a sampling rate above | |
65 48000 Hz is not necessary. | |
66 | |
67 Some emulators support adjustable treble and bass frequency equalization | |
68 (NSF, GBS, VGM) using Music_Emu::set_equalizer(). Parameters are | |
69 specified using Music_Emu::equalizer_t eq = { treble_dB, bass_freq }. | |
70 Treble_dB sets the treble level (in dB), where 0.0 dB gives normal | |
71 treble; -200.0 dB is quite muffled, and 5.0 dB emphasizes treble for an | |
72 extra crisp sound. Bass_freq sets the frequency where bass response | |
73 starts to diminish; 15 Hz is normal, 0 Hz gives maximum bass, and 15000 | |
74 Hz removes all bass. For example, the following makes the sound | |
75 extra-crisp but lacking bass: | |
76 | |
77 Music_Emu::equalizer_t eq = { 5.0, 1000 }; | |
78 music_emu->set_equalizer( eq ); | |
79 | |
80 Each emulator's equalization defaults to a profile that approximates its | |
81 particular console's sound quality; this default can be determined by | |
82 calling Music_Emu::equalizer() just after creating the emulator. Some | |
83 emulators include other profiles for different versions of the system. | |
84 The Music_Emu::tv_eq profile gives sound as if coming from a TV speaker. | |
85 For example, to use Famicom sound equalization with the NSF emulator, do | |
86 the following: | |
87 | |
88 nsf_emu->set_equalizer( Nsf_Emu::famicom_eq ); | |
89 | |
90 | |
91 VGM/GYM YM2413 & YM2612 FM Sound | |
92 -------------------------------- | |
93 The library plays Sega Genesis/Mega Drive music using a YM2612 FM sound | |
94 chip emulator based on Gens. Because this has some inaccuracies, other | |
95 YM2612 emulators can be used in its place by reimplementing the | |
96 interface in YM2612_Emu.h. Available on my website is a modified version | |
97 of MAME's YM2612 emulator, which sounds better in some ways and whose | |
98 author is still making improvements. | |
99 | |
100 VGM music files using the YM2413 FM sound chip are also supported, but a | |
101 YM2413 emulator isn't included. Similar to above, I have put one of the | |
102 available YM2413 emulators on my website that can be used directly. | |
103 | |
104 | |
105 Misc | |
106 ---- | |
107 Some emulators have constructor parameters which can be specified when | |
108 creating the object. For example, this creates a Vgm_Emu with | |
109 oversampling off and a tempo of 83%: | |
110 | |
111 Vgm_Emu* emu = new Vgm_Emu( false, 0.83 ); | |
112 | |
113 For a full example of using Game_Music_Emu see the source code for Game | |
114 Music Box, a full-featured game music player for Mac OS: | |
115 | |
116 http://www.slack.net/~ant/game-music-box/dev.html | |
117 | |
118 | |
119 Thanks | |
120 ------ | |
121 Big thanks to Chris Moeller (kode54) for help with library testing and | |
122 feedback, for maintaining the Foobar2000 plugin foo_gep based on it, and | |
123 for original work on openspc++ that was used when developing Spc_Emu. | |
124 Brad Martin's excellent OpenSPC SNES DSP emulator worked well from the | |
125 start. Also thanks to Richard Bannister, Mahendra Tallur, Shazz, and the | |
126 Audacious team for testing and using the library in their game music | |
127 players. | |
128 | |
129 | |
130 Solving Problems | |
131 ---------------- | |
132 If you're having problems, try the following: | |
133 | |
134 - Enable debugging support in your environment. This enables assertions | |
135 and other run-time checks. | |
136 | |
137 - Turn the compiler's optimizer is off. Sometimes an optimizer generates | |
138 bad code. | |
139 | |
140 - If multiple threads are being used, ensure that only one at a time is | |
141 accessing a given set of objects from the library. This library is not | |
142 in general thread-safe, though independent objects can be used in | |
143 separate threads. | |
144 | |
145 - If all else fails, see if the demos work. | |
146 | |
147 | |
148 Error handling | |
149 -------------- | |
150 Functions which can fail have a return type of blargg_err_t, which is a | |
151 pointer to an error string (const char*). If the function is successful | |
152 it returns blargg_success (NULL), otherwise it returns a pointer to an | |
153 error string. Errors which the caller can easily detect are only checked | |
154 with debug assertions; blargg_err_t returns values are only used for | |
155 genuine run-time errors that can't be easily predicted in advance (out | |
156 of memory, I/O errors, incompatible file data). | |
157 | |
158 To allow compatibility with older C++ compilers, no exceptions are | |
159 thrown by any of the modules and code is generally exception-safe. Any | |
160 exceptions thrown by the standard library or caller-supplied functions | |
161 are allowed to propagate normally. | |
162 | |
163 | |
164 Configuration | |
165 ------------- | |
166 The header "blargg_common.h" is used to establish a common environment, | |
167 and is #included at the beginning of all library headers and sources. It | |
168 attempts to automatically determine the features of the environment, but | |
169 might need help. Refer to "blargg_common.h" for descriptions of | |
170 features. | |
171 | |
172 If defined HAVE_CONFIG_H in the compiler command-line, the user-provided | |
173 "config.h" is included at the beginning of each library header file, | |
174 allowing configuration options for the library to be set. I have | |
175 attempted to design the library so that configuration can be done | |
176 *without* modifying any of the library sources and header files. This | |
177 makes it easy to upgrade to a new version without losing any | |
178 customizations to its configuration. | |
179 | |
180 Post to the forum if you have problems or suggestions. | |
181 |