Mercurial > audlegacy-plugins
annotate src/console/gme_notes.txt @ 3047:4434b4c4a715
ported EsounD plugin
author | Andrew O. Shadoura <bugzilla@tut.by> |
---|---|
date | Fri, 17 Apr 2009 16:17:10 +0300 |
parents | 986f098da058 |
children |
rev | line source |
---|---|
341 | 1 Game_Music_Emu 0.5.2 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
2 -------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
3 Author : Shay Green <gblargg@gmail.com> |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
4 Website: http://www.slack.net/~ant/libs/ |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
5 Forum : http://groups.google.com/group/blargg-sound-libs |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
6 License: GNU Lesser General Public License (LGPL) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
7 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
8 Contents |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
9 -------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
10 * Overview |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
11 * C and C++ interfaces |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
12 * Function reference |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
13 * Error handling |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
14 * Emulator types |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
15 * M3U playlist support |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
16 * Information fields |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
17 * Track length |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
18 * Loading file data |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
19 * Sound parameters |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
20 * VGM/GYM YM2413 & YM2612 FM sound |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
21 * Modular construction |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
22 * Obscure features |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
23 * Solving problems |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
24 * Deprecated features |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
25 * Thanks |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
26 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
27 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
28 Overview |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
29 -------- |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
30 This library contains several game music file emulators with a common |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
31 interface. Each can load a game music file and play from any track. To |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
32 play a track from a game music file, do the following: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
33 |
341 | 34 ** TODO: things are simpler now |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
35 * Determine file's type (i.e. gme_nsf_emu, gme_spc_emu, etc.) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
36 * Create appropriate emulator and set sample rate with gme_new_emu() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
37 * Load file into emulator with gme_load() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
38 * Start a track with gme_start_track() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
39 * Generate samples as needed with gme_play() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
40 * Play samples through speaker using your operating system |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
41 * Delete emulator when done with gme_delete() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
42 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
43 Your code must arrange for the generated samples to be played through |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
44 the computer's speaker using whatever method your operating system |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
45 requires. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
46 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
47 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
48 C and C++ interfaces |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
49 -------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
50 While the library is written in C++, a fairly complete C interface is |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
51 provided in gme.h. This C interface will be referred to throughout this |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
52 documentation unless a feature is only available in the full C++ |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
53 interface. All C interface functions and other names have the gme_ |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
54 prefix, so you can recognize a C++-only feature by the lack of gme_ in |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
55 the names used (contact me if you'd like a feature added to the C |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
56 interface). If you're building a shared library, I highly recommend |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
57 sticking to the C interface only, because it will be much more stable |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
58 between releases of the library than the C++ interface. Finally, the C |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
59 and C++ interfaces can be freely mixed without problems. Compare |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
60 demo/basics.c with demo/cpp_basics.cpp to see how the C and C++ |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
61 interfaces translate between each other. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
62 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
63 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
64 Function reference |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
65 ------------------ |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
66 Read the following header files for a complete reference to functions |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
67 and features. The second group of header files can only be used in C++. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
68 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
69 blargg_config.h Library configuration |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
70 gme.h C interface |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
71 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
72 Gme_File.h File loading and track information |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
73 Music_Emu.h Track playback and adjustments |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
74 Data_Reader.h Custom data readers |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
75 Effects_Buffer.h Sound buffer with adjustable stereo echo and panning |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
76 M3u_Playlist.h M3U playlist support |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
77 Gbs_Emu.h GBS equalizer settings |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
78 Nsf_Emu.h NSF equalizer settings |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
79 Spc_Emu.h SPC surround disable |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
80 Vgm_Emu.h VGM oversampling disable and custom buffer query |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
81 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
82 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
83 Error handling |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
84 -------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
85 Functions which can fail have a return type of gme_err_t, which is a |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
86 pointer to an error string (const char*). If a function is successful it |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
87 returns NULL. Errors that you can easily avoid are checked with debug |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
88 assertions; gme_err_t return values are only used for genuine run-time |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
89 errors that can't be easily predicted in advance (out of memory, I/O |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
90 errors, incompatible file data). Your code should check all error |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
91 values. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
92 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
93 To improve usability for C programmers, C++ programmers unfamiliar with |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
94 exceptions, and compatibility with older C++ compilers, the library does |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
95 *not* throw any C++ exceptions and uses malloc() instead of the standard |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
96 operator new. This means that you *must* check for NULL when creating a |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
97 library object with the new operator. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
98 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
99 When loading a music file in the wrong emulator or trying to load a |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
100 non-music file, gme_wrong_file_type is returned. You can check for this |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
101 error in C++ like this: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
102 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
103 gme_err_t err = gme_load_file( music_emu, path, 0 ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
104 if ( err == gme_wrong_file_type ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
105 ... |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
106 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
107 To check for minor problems, call gme_warning() to get a string |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
108 describing the last warning. Your player should allow the user some way |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
109 of knowing when this is the case, since these minor errors could affect |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
110 playback. Without this information the user can't solve problems as |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
111 well. When playing a track, gme_warning() returns minor playback-related |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
112 problems (major playback problems end the track immediately and set the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
113 warning string). |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
114 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
115 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
116 Emulator types |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
117 -------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
118 The library includes several game music emulators that each support a |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
119 different file type. Each is identified by a gme_type_t constant defined |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
120 in gme.h, for example gme_nsf_emu is for the NSF emulator. Ultimately |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
121 you will use one of these to select which emulator to use for a file. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
122 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
123 There are two basic ways to identify a game music file's type: look at |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
124 its file extension, or read the header data. The library includes |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
125 functions to help with both methods. The first is preferable because it |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
126 is fast and the most common way to identify files. Sometimes the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
127 extension is lost or wrong, so the header must be read. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
128 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
129 Use gme_identify_extension() to find the correct game music type based |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
130 on a filename. It takes an array of gme_type_t elements, allowing you to |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
131 customize what game music types you accept. If you want to accept all |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
132 types supported by the library, use gme_type_list(), otherwise pass an |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
133 array of the types you support. For example, to support just NSF and |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
134 GBS, and avoid having to compile/link the other emulator files, do this |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
135 (be sure to end your array with 0): |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
136 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
137 static gme_type_t types [] = { gme_nsf_type, gme_gbs_type, 0 }; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
138 file_type = gme_identify_extension( path, types ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
139 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
140 To identify a file based on its extension and header contents, use |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
141 gme_identify_file(). If you read the header data yourself, use |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
142 gme_identify_header(). |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
143 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
144 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
145 M3U playlist support |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
146 -------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
147 The library supports playlists in the .m3u format with gme_load_m3u() to |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
148 give track names and times to multi-song formats: AY, GBS, HES, KSS, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
149 NSF, NSFE, and SAP. Some aspects of the file format itself is not |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
150 well-defined so some .m3u files won't work properly (particularly those |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
151 provided with KSS files). Only .m3u files referencing a single file are |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
152 supported; your code must handle .m3u files covering more than one game |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
153 music file, though it can use the built-in .m3u parsing provided by the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
154 library. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
155 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
156 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
157 Information fields |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
158 ------------------ |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
159 Support is provided for the various text fields and length information |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
160 in a file with gme_track_info(). If you just need track information for |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
161 a file (for example, building a playlist), use gme_new_info() in place |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
162 of gme_new_emu(), load the file normally, then you can access the track |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
163 count and info, but nothing else. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
164 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
165 M3U VGM GYM SPC SAP NSFE NSF AY GBS HES KSS |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
166 ------------------------------------------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
167 Track Count | * * * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
168 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
169 System | * * * * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
170 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
171 Game | * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
172 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
173 Song | * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
174 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
175 Author | * * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
176 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
177 Copyright | * * * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
178 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
179 Comment | * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
180 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
181 Dumper | * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
182 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
183 Length | * * * * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
184 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
185 Intro Length| * * * |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
186 | |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
187 Loop Length | * * * |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
188 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
189 As listed above, the HES and KSS file formats don't include a track |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
190 count, and tracks are often scattered over the 0-255 range, so an m3u |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
191 playlist for these is a must. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
192 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
193 Unavailable text fields are set to an empty string and times to -1. Your |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
194 code should be prepared for any combination of available and unavailable |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
195 fields, as a particular music file might not use all of the supported |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
196 fields listed above. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
197 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
198 Currently text fields are truncated to 255 characters. Obscure fields of |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
199 some formats are not currently decoded; contact me if you want one |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
200 added. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
201 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
202 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
203 Track length |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
204 ------------ |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
205 The library leaves it up to you as to when to stop playing a track. You |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
206 can ask for available length information and then tell the library what |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
207 time it should start fading the track with gme_set_fade(). By default it |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
208 also continually checks for 6 or more seconds of silence to mark the end |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
209 of a track. Here is a reasonable algorithm you can use to decide how |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
210 long to play a track: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
211 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
212 * If the track length is > 0, use it |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
213 * If the loop length > 0, play for intro + loop * 2 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
214 * Otherwise, default to 2.5 minutes (150000 msec) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
215 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
216 If you want to play a track longer than normal, be sure the loop length |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
217 isn't zero. See Music_Player.cpp around line 145 for example code. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
218 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
219 By default, the library skips silence at the beginning of a track. It |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
220 also continually checks for the end of a non-looping track by watching |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
221 for 6 seconds of unbroken silence. When doing this is scans *ahead* by |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
222 several seconds so it can report the end of the track after only one |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
223 second of silence has actually played. This feature can be disabled with |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
224 gme_ignore_silence(). |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
225 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
226 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
227 Loading file data |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
228 ----------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
229 The library allows file data to be loaded in many different ways. All |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
230 load functions return an error which you should check (not shown here |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
231 for clarity). The most basic is always available, simple calling |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
232 load_file() with the path of a file: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
233 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
234 gme_load_file( music_emu, file_path ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
235 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
236 * From a block of memory: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
237 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
238 gme_load_data( music_emu, pointer, size ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
239 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
240 * Have library call your function to read data: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
241 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
242 gme_err_t my_read( void* my_data, void* out, long count ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
243 { |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
244 // code that reads 'count' bytes into 'out' buffer |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
245 // and return 0 if no error |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
246 } |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
247 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
248 gme_load_custom( music_emu, my_read, file_size, my_data ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
249 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
250 * If you must load the file data into memory yourself, you can have the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
251 library use your data directly *without* making a copy. If you do this, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
252 you must not free the data until you're done playing the file. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
253 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
254 music_emu->load_mem( pointer, size ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
255 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
256 * If you've already read the first bytes of a file (perhaps to determine |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
257 the file type) and want to avoid seeking back to the beginning for |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
258 performance reasons, use Remaining_Reader: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
259 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
260 Std_File_Reader in; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
261 in.open( file_path ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
262 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
263 char header [4]; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
264 in.read( &header, sizeof header ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
265 ... |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
266 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
267 Remaining_Reader rem( &header, sizeof header, &in ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
268 music_emu->load( rem ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
269 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
270 If you merely need access to a file's header after loading, use the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
271 emulator-specific header() functions, after casting the Music_Emu |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
272 pointer to the specific emulator's type. This example examines the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
273 chip_flags field of the header if it's an NSF file: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
274 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
275 if ( music_emu->type() == gme_nsf_type ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
276 { |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
277 Nsf_Emu* nsf_emu = (Nsf_Emu*) music_emu; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
278 if ( nsf_emu->header().chip_flags & 0x01 ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
279 ... |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
280 } |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
281 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
282 Contact me if you want more information about loading files. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
283 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
284 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
285 Sound parameters |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
286 ---------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
287 All emulators support an arbitrary output sampling rate. A rate of 44100 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
288 Hz should work well on most systems. Since band-limited synthesis is |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
289 used, a sampling rate above 48000 Hz is not necessary and will actually |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
290 reduce sound quality and performance. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
291 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
292 All emulators also support adjustable gain, mainly for the purpose of |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
293 getting consistent volume between different music formats and avoiding |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
294 excessive modulation. The gain can only be set *before* setting the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
295 emulator's sampling rate, so it's not useful as a general volume |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
296 control. The default gains of emulators are set so that they give |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
297 generally similar volumes, though some soundtracks are significantly |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
298 louder or quieter than normal. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
299 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
300 Some emulators support adjustable treble and bass frequency equalization |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
301 (AY, GBS, HES, KSS, NSF, NSFE, SAP, VGM) using set_equalizer(). |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
302 Parameters are specified using gme_equalizer_t eq = { treble_dB, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
303 bass_freq }. Treble_dB sets the treble level (in dB), where 0.0 dB gives |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
304 normal treble; -200.0 dB is quite muffled, and 5.0 dB emphasizes treble |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
305 for an extra crisp sound. Bass_freq sets the frequency where bass |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
306 response starts to diminish; 15 Hz is normal, 0 Hz gives maximum bass, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
307 and 15000 Hz removes all bass. For example, the following makes the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
308 sound extra-crisp but lacking bass: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
309 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
310 gme_equalizer_t eq = { 5.0, 1000 }; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
311 gme_set_equalizer( music_emu, &eq ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
312 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
313 Each emulator's equalization defaults to approximate the particular |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
314 console's sound quality; this default can be determined by calling |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
315 equalizer() just after creating the emulator. The Music_Emu::tv_eq |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
316 profile gives sound as if coming from a TV speaker, and some emulators |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
317 include other profiles for different versions of the system. For |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
318 example, to use Famicom sound equalization with the NSF emulator, do the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
319 following: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
320 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
321 music_emu->set_equalizer( Nsf_Emu::famicom_eq ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
322 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
323 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
324 VGM/GYM YM2413 & YM2612 FM sound |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
325 -------------------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
326 The library plays Sega Genesis/Mega Drive music using a YM2612 FM sound |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
327 chip emulator based on the Gens project. Because this has some |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
328 inaccuracies, other YM2612 emulators can be used in its place by |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
329 re-implementing the interface in YM2612_Emu.h. Available on my website |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
330 is a modified version of MAME's YM2612 emulator, which sounds better in |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
331 some ways and whose author is still making improvements. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
332 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
333 VGM music files using the YM2413 FM sound chip are also supported, but a |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
334 YM2413 emulator isn't included with the library due to technical |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
335 reasons. I have put one of the available YM2413 emulators on my website |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
336 that can be used directly. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
337 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
338 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
339 Modular construction |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
340 -------------------- |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
341 The library is made of many fairly independent modules. If you're using |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
342 only one music file emulator, you can eliminate many of the library |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
343 sources from your program. Refer to the files list in readme.txt to get |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
344 a general idea of what can be removed. Post to the forum if you'd like |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
345 me to put together a smaller version for a particular use, as this only |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
346 takes me a few minutes to do. |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
347 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
348 If you want to use one of the individual sound chip emulators (or CPU |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
349 cores) in your own console emulator, first check the libraries page on |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
350 my website since I have released several of them as stand alone |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
351 libraries with included documentation and examples on their use. If you |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
352 don't find it as a standalone library, contact me and I'll consider |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
353 separating it. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
354 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
355 The "classic" sound chips use my Blip_Buffer library, which greatly |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
356 simplifies their implementation and efficiently handles band-limited |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
357 synthesis. It is also available as a stand alone library with |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
358 documentation and many examples. |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
359 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
360 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
361 Obscure features |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
362 ---------------- |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
363 The library's flexibility allows many possibilities. Contact me if you |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
364 want help implementing ideas or removing limitations. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
365 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
366 * Uses no global/static variables, allowing multiple instances of any |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
367 emulator. This is useful in a music player if you want to allow |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
368 simultaneous recording or scanning of other tracks while one is already |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
369 playing. This will also be useful if your platform disallows global |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
370 data. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
371 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
372 * Emulators that support a custom sound buffer can have *every* voice |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
373 routed to a different Blip_Buffer, allowing custom processing on each |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
374 voice. For example you could record a Game Boy track as a 4-channel |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
375 sound file. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
376 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
377 * Defining BLIP_BUFFER_FAST uses lower quality, less-multiply-intensive |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
378 synthesis on "classic" emulators, which might help on some really old |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
379 processors. This significantly lowers sound quality and prevents treble |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
380 equalization. Try this if your platform's processor isn't fast enough |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
381 for normal quality. Even on my ten-year-old 400 MHz Mac, this reduces |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
382 processor usage at most by about 0.6% (from 4% to 3.4%), hardly worth |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
383 the quality loss. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
384 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
385 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
386 Solving problems |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
387 ---------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
388 If you're having problems, try the following: |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
389 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
390 * If you're getting garbled sound, try this simple siren generator in |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
391 place of your call to play(). This will quickly tell whether the problem |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
392 is in the library or in your code. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
393 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
394 static void play_siren( long count, short* out ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
395 { |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
396 static double a, a2; |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
397 while ( count-- ) |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
398 *out++ = 0x2000 * sin( a += .1 + .05*sin( a2+=.00005 ) ); |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
399 } |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
400 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
401 * Enable debugging support in your environment. This enables assertions |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
402 and other run-time checks. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
403 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
404 * Turn the compiler's optimizer is off. Sometimes an optimizer generates |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
405 bad code. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
406 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
407 * If multiple threads are being used, ensure that only one at a time is |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
408 accessing a given set of objects from the library. This library is not |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
409 in general thread-safe, though independent objects can be used in |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
410 separate threads. |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
411 |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
412 * If all else fails, see if the demos work. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
413 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
414 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
415 Deprecated features |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
416 ------------------- |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
417 The following functions and other features have been deprecated and will |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
418 be removed in a future release of the library. Alternatives to the |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
419 deprecated features are listed to the right. |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
420 |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
421 Music_Emu::error_count() warning() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
422 load( header, reader ) see "Loading file data" above |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
423 Spc_Emu::trailer() track_info() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
424 Spc_Emu::trailer_size() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
425 Gym_Emu::track_length() track_info() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
426 Vgm_Emu::gd3_data() track_info() |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
427 Nsfe_Emu::disable_playlist() clear_playlist() |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
428 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
429 |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
430 Thanks |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
431 ------ |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
432 Big thanks to Chris Moeller (kode54) for help with library testing and |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
433 feedback, for maintaining the Foobar2000 plugin foo_gep based on it, and |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
434 for original work on openspc++ that was used when developing Spc_Emu. |
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
435 Brad Martin's excellent OpenSPC SNES DSP emulator worked well from the |
316
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
436 start. Also thanks to Richard Bannister, Mahendra Tallur, Shazz, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
437 nenolod, theHobbit, Johan Samuelsson, and nes6502 for testing, using, |
fb513e10174e
[svn] - merge libconsole-blargg into mainline libconsole:
nenolod
parents:
12
diff
changeset
|
438 and giving feedback for the library in their respective game music |
0
13389e613d67
[svn] - initial import of audacious-plugins tree (lots to do)
nenolod
parents:
diff
changeset
|
439 players. |