annotate src/console/gme_notes.txt @ 1263:458d46e65a86

wav-sndfile: in is_our_file, ensure that filename is not NULL before passing it to sf_open
author Giacomo Lozito <james@develia.org>
date Fri, 13 Jul 2007 20:55:42 +0200
parents 986f098da058
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
341
986f098da058 [svn] - merge in blargg's changes
nenolod
parents: 316
diff changeset
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
986f098da058 [svn] - merge in blargg's changes
nenolod
parents: 316
diff changeset
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.