1 \input texinfo @c -*-texinfo-*-
3 @setfilename libadplug.info
5 @settitle AdPlug Core Library @value{VERSION} Manual
14 This manual documents the AdPlug core library, version
17 Copyright @copyright{} 2002 - 2010 Simon Peter <dn.tlp@@gmx.net>
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.1 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
24 and with the Back-Cover Texts as in (a) below. A copy of the license is
25 included in the section entitled ``GNU Free Documentation License.''
27 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
28 this GNU Manual, like GNU software. Copies published by the Free
29 Software Foundation raise funds for GNU development.''
33 @dircategory Software Libraries
35 * AdPlug Core Library: (libadplug). AdPlug Core Library @value{VERSION}
39 @title AdPlug Core Library Manual
40 @subtitle Version @value{VERSION}
41 @subtitle Last updated on @value{UPDATED}
45 @vskip 0pt plus 1filll
53 @top AdPlug core library
59 * Introduction:: What is AdPlug?
60 * Basic Usage:: Using AdPlug in your programs the easy way.
61 * Advanced Usage:: Using AdPlug in your programs the hard way.
62 * Hacking:: How to hack around in AdPlug.
63 * Player development:: How to write new replayers for AdPlug.
64 * Protracker based players:: How to write Protracker based players.
65 * Copying This Manual:: Your rights and freedoms.
74 AdPlug is a free, multi-platform, hardware independent AdLib sound
75 player library, mainly written in C++. AdPlug plays sound data,
76 originally created for the AdLib and Sound Blaster (OPL2/OPL3) audio
77 boards, on top of an OPL emulator or by using the real hardware. No
78 OPL chip is required for playback.
85 @node Supported Formats
86 @section Supported Formats
88 AdPlug implements unique file replayers for each supported format in
89 order to achieve the best possible replay quality. Below is a list of
90 all currently supported file formats along with information about
91 possible replay issues. Players marked as "preliminary" aren't
92 considered final by the author(s) and may contain many replay issues,
93 but are included for testing purposes anyway.
96 @item @file{A2M}: AdLib Tracker 2 by subz3ro
98 @item File format versions 1, 4, 5 and 8 are supported
99 @item Unimplemented commands (versions 1-4): @code{FF1 - FF9, FAx - FEx}
100 @item Unimplemented commands (versions 5-8): @code{Gxy, Hxy, Kxy - &xy}
101 @item In version 5-8 files, some parts of the flags byte are ignored
102 @item Only SixPack compressed and uncompressed files are supported
104 @item @file{ADL}: Westwood ADL File Format
105 @item @file{AMD}: AMUSIC Adlib Tracker by Elyssis
106 @item @file{BAM}: Bob's Adlib Music Format by Bob
107 @item @file{CFF}: BoomTracker 4.0 by CUD
108 @item @file{CMF}: Creative Music File Format by Creative Technology
109 @item @file{D00}: EdLib by Vibrants
111 @item Bugs: Hard restart SR sometimes sounds wrong
113 @item @file{DFM}: Digital-FM by R.Verhaag
114 @item @file{DMO}: Twin TrackPlayer by TwinTeam
115 @item @file{DRO}: DOSBox Raw OPL Format
116 @item @file{DTM}: DeFy Adlib Tracker by DeFy
117 @item @file{HSC}: HSC Adlib Composer by Hannes Seifert, HSC-Tracker by Electronic Rats
118 @item @file{HSP}: HSC Packed by Number Six / Aegis Corp.
119 @item @file{IMF}: Apogee IMF File Format by Apogee
120 @item @file{KSM}: Ken Silverman's Adlib Music Format by Ken Silverman
122 @item Needs file @file{insts.dat} in the same directory as loaded file
124 @item @file{LAA}: LucasArts AdLib Audio File Format by LucasArts
126 @item Bugs: Some volumes are a bit off
128 @item @file{LDS}: LOUDNESS Music Format by Andras Molnar
129 @item @file{M}: Ultima 6 Music Format by Origin
130 @item @file{MAD}: Mlat Adlib Tracker
131 @item @file{MID}: MIDI Audio File Format
132 @item @file{MKJ}: MKJamz by M \ K Productions @strong{(preliminary)}
133 @item @file{MSC}: AdLib MSCplay
134 @item @file{MTK}: MPU-401 Trakker by SuBZeR0
135 @item @file{RAD}: Reality ADlib Tracker by Reality
136 @item @file{RAW}: RdosPlay RAW file format by RDOS
137 @item @file{RIX}: Softstar RIX OPL Music Format
138 @item @file{ROL}: AdLib Visual Composer by AdLib Inc.
140 @item Needs file @file{standard.bnk} in the same directory as loaded file
142 @item @file{S3M}: Scream Tracker 3 by Future Crew
144 @item Bugs: Extra Fine Slides (@code{EEx, FEx}) & Fine Vibrato
145 (@code{Uxy}) are inaccurate
147 @item @file{SA2}: Surprise! Adlib Tracker 2 by Surprise! Productions
148 @item @file{SAT}: Surprise! Adlib Tracker by Surprise! Productions
149 @item @file{SCI}: Sierra's AdLib Audio File Format by Sierra On-Line Inc.
151 @item Needs file @file{@var{???}patch.003} in the same directory as
152 loaded file, where @var{???} are the first 3 characters of the loaded
154 @item Bugs: Some instruments are messed up
156 @item @file{SNG}: SNGPlay by BUGSY of OBSESSION
157 @item @file{SNG}: Faust Music Creator by FAUST
158 @item @file{SNG}: Adlib Tracker 1.0 by TJ
160 @item Needs file @file{@var{songname}.ins} in the same directory as
161 loaded file, where @var{songname} is the song's filename without
162 @file{.sng} extension.
164 @item @file{XAD}: eXotic ADlib Format by Riven the Mage
165 @item @file{XMS}: XMS-Tracker by MaDoKaN/E.S.G
166 @item @file{XSM}: eXtra Simple Music by Davey W Taylor
169 Whenever a player requires more files to be present in a given
170 directory, be especially careful under UNIX systems, because all file
171 names are case-sensitive.
176 All of AdPlug's header files are installed under the directory
177 @file{adplug} inside your specified include path. Whenever a specific
178 header file in this manual is referred to, the filename with the path
179 @file{adplug/} prepended is meant.
181 AdPlug can be divided into 2 sections and 3 layers of
182 functionality. These are the @dfn{Playback} and @dfn{Sound
183 generation} sections and the @dfn{Frontend}, @dfn{Mid-End} and
184 @dfn{Backend} layers.
186 The Frontend layer is simply your application itself, using AdPlug. It
187 is above of it all and does not belong to any particular
188 section. Anything that provides the user-interface to AdPlug or an
189 interface to another application is in the Frontend layer.
193 * Sound generation section::
196 @node Playback section
197 @subsection Playback section
199 The Playback section is divided into the Mid-End and the Backend
200 layers. As a whole, it is responsible for making the sound files play
203 The Mid-End layer provides the glue between the Frontend and the
204 Backend layers. It provides methods and classes for these layers to
205 communicate. The headers @file{adplug.h}, @file{fprovide.h},
206 @file{players.h} and @file{database.h} belong to the Mid-End
207 layer. From your application's point of view, you only have to include
208 the file @file{adplug.h} in your source files, which automatically
209 includes all the other Mid-End headers.
211 The Backend layer is responsible for reading and decoding the sound
212 files into OPL command data. It then passes this data to the sound
213 generation section, which generates the final audio data. The header
214 @file{player.h} and all player header files belong to the Backend
217 @node Sound generation section
218 @subsection Sound generation section
220 The Sound generation section is responsible for generating the OPL's
221 sound, according to the input of the Playback section. This sound is
222 either routed back to the application for it to do something with it
223 or routed directly to a specific audio hardware.
225 The following headers provide the interface to the sound generation
226 section: @file{emuopl.h}, @file{temuopl.h}, @file{kemuopl.h},
227 @file{realopl.h}, @file{silentopl.h}, @file{analopl.h} and
228 @file{diskopl.h}. All classes inside these headers are derived from
229 the abstract base class @class{Copl}, declared inside the file
230 @file{opl.h}, which provides the common interface for the Backend
231 layer of the Playback section. This interface is not meant for the
232 Frontend layer (i.e. your application). Your application, however, has
233 to call special methods of these classes in order to route the data
234 back, if there is any.
236 @file{emuopl.h} provides the class @class{CEmuopl}, which implements a
237 virtual OPL emulator, which automatically selects the best available
238 OPL chip emulation and type for each replayer.
240 @file{temuopl.h} provides the class @class{CTEmuopl}, which is a
241 wrapper class around Tatsuyuki Satoh's fmopl OPL2 emulator, which
242 generates wave audio data to be routed back to the application.
244 @file{kemuopl.h} provides the class @class{CKemuopl}, which is a
245 wrapper class around Ken Silverman's adlibemu OPL2 emulator, which
246 generates wave audio data to be routed back to the application.
248 @file{realopl.h} provides the class @class{CRealopl}, which outputs to
249 a real hardware OPL2 or OPL3 chip. No data is routed back to the
250 application. This class is currently only working on x86 hardware.
252 @file{silentopl.h} provides the class @class{CSilentopl}, which is a
253 dummy OPL2/3, which generates nothing. All data sent to it is
254 forgotten immediately. No data is routed back to the application.
256 @file{analopl.h} provides the class @class{CAnalopl}, which is the same
257 as @class{CRealopl}, but also provides a 9-channel loudness
258 pseudo-analyzer interface for the application. The loudness data is
259 the only data routed back to the application.
261 @file{diskopl.h} provides the class @class{CDiskopl}, which is an OPL3
262 emulator that does not output any sound to the soundcard, but instead
263 writes all received OPL commands to a file in the RdosPlay RAW
269 AdPlug provides convenience methods and classes inside its Mid-End
270 layer that make generic usage in your applications pretty easy. This
271 is most probably all that you need. For very advanced usage of
272 particular features of AdPlug, please refer to @ref{Advanced Usage}.
274 For basic usage, you need to include the header @file{adplug.h} inside
275 your application's source code. In addition, you need one of the
276 headers from the sound generation section, if you want sound output.
278 @file{adplug.h} provides the class @class{CAdPlug}, which in turn
279 provides the load and playback facilities for the song
280 files. @code{CAdPlug} is a static class, you do not need to
281 instantiate an object of it.
287 * Chip support selection::
288 * Getting Playback Information::
295 To load a supported file for playback, you use the method
296 @code{CAdPlug::factory(const std::string &@var{filename}, Copl *@var{opl},
297 ...)}. The method takes more arguments, but we don't need them for
298 basic usage. They are explained in @ref{Advanced Usage}.
300 The first argument, @var{filename}, is a string object, containing the
301 filename of the sound file to be loaded with AdPlug. The second
302 argument, @var{opl}, is a pointer to an already initialized object
303 from the sound generation section of the library.
305 The method returns a pointer to an initialized player object from the
306 Backend layer, or the NULL pointer if the file couldn't be loaded for
309 I guess @var{filename} does not need any more explanation, so i will
310 just explain how to get an instance of a @code{Copl} derived class:
312 If you want to use the OPL emulator class @code{CEmuopl}, you have to
313 include the header @file{emuopl.h} inside your application's source
314 code. @code{CEmuopl}'s constructor looks like this:
315 @code{CEmuopl::CEmuopl(int @var{rate}, bool @var{bit16}, bool
316 @var{usestereo})}. The @var{rate} argument specifies the playback
317 frequency rate in Hz. The @var{bit16} argument specifies whether to
318 create 8 bit or 16 bit wave audio data. If it is set, 16 bit data is
319 created. The @var{usestereo} argument specifies whether to create
320 stereo or mono audio data. If it is set, stereo data is created.
322 If you want to use real hardware OPL2 output, you have to include the
323 header @file{realopl.h} inside your application and use the class
324 @code{CRealopl}. Its constructor just takes one optional argument,
325 specifying the hardware OPL2's base port, which is @samp{0x388} by
326 default. As an option, you can include @file{analopl.h} instead, using
327 the class @code{CAnalopl}, and also use the analyzer interface
328 instead. This is explained in @ref{Audio output}.
330 For no audio generation at all, include the header @file{silentopl.h}
331 inside your application and use the class @code{CSilentopl}. Its
332 constructor does not take any arguments.
337 On successful operation, @code{CAdPlug}'s @code{factory()} method
338 returns a pointer to an initialized player object from the Backend
339 layer. You use this object to do the main song playback. The important
340 methods for song playback are:
343 @item void seek(unsigned long ms)
344 Use this to seek inside the song. The only argument specifies the
345 number of milliseconds to seek from the beginning of the song.
348 The most important method of them all. You have to call this method in
349 a loop. As long as it returns @samp{true}, the song has not ended
350 yet. At some point, it will start to always return @samp{false}. When
351 it does this, the song has ended. The song will play on (and is maybe
352 already automatically rewound by the player itself), but you should
353 use the @code{rewind()} method to rewind it or stop playing.
355 @item void rewind(int subsong = -1)
356 This method rewinds the song to the beginning of the subsong,
357 specified by the only argument. If no argument or @samp{-1} is given,
358 the currently selected subsong will be rewound. If the player does not
359 support subsongs, just don't provide an argument.
361 @item float getrefresh()
362 Returns a float containing the player object's idea of with what
363 frequency its @code{update()} method should be called, in Hz. This can
364 change at any time, so you have to poll it before every call to
367 @item unsigned int getsubsongs()
368 Returns the number of subsongs of the currently loaded song. If the
369 player doesn't support subsongs, @samp{1} is returned, representing
370 the only ``subsong''.
374 @section Audio output
376 To actually generate some sound, you probably additionally have to
377 make some calls to the OPL object. While the two hardware OPL2 output
378 and the silent OPL2 classes do not need any additional calls, the
379 @code{CEmuopl} class provides methods for your application's readback
380 of the generated wave audio data.
382 To get a buffer of wave audio data from the emulator, you have to call
383 the @code{void CEmuopl::update(short *@var{buf}, int @var{samples})}
384 method. The @var{buf} argument is a pointer to a previously allocated
385 memory block of the size specified by the @var{samples} argument, in
386 samples. The method will fill the specified amount of samples into the
387 buffer. Multibyte samples have the machine's byte ordering.
389 For easier and more uniform handling of the different OPL classes, the
390 @code{Copl} base class also provides the @code{update()} method. For
391 subclasses that do not support read back of the audio data (and for
392 which this is not necessary), the method is empty and does nothing.
394 The volume analyzing hardware OPL class @code{CAnalopl} also has some
395 data readback methods:
398 @item int getcarriervol(unsigned int v)
399 Returns the carrier's current volume of the OPL2 channel given as the
401 @item int getmodulatorvol(unsigned int v)
402 Returns the modulator's current volume of the OPL2 channel given as
404 @item bool getkeyon(unsigned int v)
405 Returns whether a key-on event just happened on the OPL2 channel given
406 as the only argument.
409 @node Chip support selection
410 @section Chip support selection
412 With some OPL classes, like @code{CEmuopl} and @code{CRealopl}, it is
413 also possible to select the chip type to support. The hardware OPL
414 class will of course only be able to support those chip types that are
415 available in the system. The emulated OPL class will be able to
416 support all chip types that it can emulate, provided the corresponding
417 emulators are compiled in.
419 Three different OPL chip configurations can be identified, which can
420 all be support by AdPlug.
423 @item Single OPL2: This is the classic configuration found on the
424 standard AdLib boards. One OPL2 chip is supported.
425 @item Dual OPL2: This configuration was first implemented on the Sound
426 Blaster Pro II boards. Two independant OPL2 chips are on this card.
427 @item OPL3: This is the configuration found on all newer sound
428 cards. An OPL3 chip is supported, which is capable of emulating the
429 other two configurations.
432 In accordance to this, AdPlug's @code{Copl} base class defines the
433 enumeration type @code{ChipType}, containing the items
434 @code{TYPE_OPL2}, @code{TYPE_OPL3} and @code{TYPE_DUAL_OPL2}.
436 OPL classes supporting multiple OPL interfaces have the
437 @code{settype(@var{type})} method, which can be used to set the chip
438 interface to support, using the @code{ChipType} enumeration type.
440 The chip type needs not to be set, as all supporting classes
441 automatically set the best available chip type, they can support, but
442 you may like to provide your user with this selection to suite his
443 listenting preferences.
445 You may retrieve the currently supported chip type of a class by using
446 the method @code{Copl::gettype()}, which returns a variable of type
447 @code{ChipType}. This method is defined in the @code{Copl} base class
448 and thus supported by all of the OPL classes.
450 @node Getting Playback Information
451 @section Getting Playback Information
453 During playback, it is possible to gain some replay statistics with
454 some players. The following methods are for getting playback
458 @item std::string gettype()
459 Returns a descriptive string containing the current file's format
460 type. This is for user information only and cannot be interpreted by
463 @item std::string gettitle()
464 Returns a string holding the current song's title. An empty string is
465 returned if the song's format does not support title information.
467 @item std::string getauthor()
468 Returns a string containing the current song's author name. An empty
469 string is returned if the song's format doesn't support author
472 @item std::string getdesc()
473 Returns a string with the current song's description. An empty string
474 is returned if the song's format doesn't support a description.
476 @item unsigned int getpatterns()
477 Returns the number of patterns in the current song. @samp{0} is
478 returned if the format isn't pattern-based.
480 @item unsigned int getpattern()
481 Returns the number of the currently playing pattern. @samp{0} is
482 returned if the format isn't pattern-based.
484 @item unsigned int getorders()
485 Returns the length of the order list of the current song. @samp{0} is
486 returned if the format doesn't have an order list.
488 @item unsigned int getorder()
489 Returns the number of the currently playing order list entry. @samp{0}
490 is returned if the format doesn't have an order list.
492 @item unsigned int getrow()
493 Returns the number of the currently playing row inside the current
494 pattern. @samp{0} is returned if the format isn't pattern-based.
496 @item unsigned int getspeed()
497 Returns the current speed setting of the song. @samp{0} is returned if
498 the format doesn't support Protracker-based speed settings.
500 @item unsinged int getinstruments()
501 Returns the number of defined instruments in the song. This does not
502 necessarily mean that any of the defined instruments has an instrument
503 name attached to it. @samp{0} is returned if the format doesn't define
506 @item std::string getinstrument(unsigned int n)
507 Returns a string with the name of the instrument, specified by the
508 only argument. If the specified instrument doesn't have a name, an
509 empty string is returned instead.
512 These methods may be called at any time on an initialized player
513 object (i.e. a file has already been loaded). If a player or song does
514 not support any of the above methods, or their values are not
515 meaningful for a format, reasonable bogus values are returned
518 Some informational methods may not be called while the song itself is
519 playing because they change the internal replay state and will
520 destroy the running playback. These are:
523 @item unsigned long songlength(int subsong = -1)
524 This method returns the total length in milliseconds of the subsong
525 given as the only argument. If it is omitted or @samp{-1}, the
526 currently selected subsong's length will be returned.
532 This is an example of a minimal playback utility that reads the
533 filename to be played from the commandline, uses the emulator to
534 generate the sound and writes the raw wave audio data back to disk:
539 #include <adplug/adplug.h>
540 #include <adplug/emuopl.h>
542 #define RATE 44100 // Output frequency in Hz
543 #define BIT16 true // true when 16bit samples should be used
544 #define STEREO false // true when stereo samples should be used
545 #define BUFSIZE 512 // Sound buffer size in samples
547 bool play(const char *filename, const char *output)
549 * Main playback function. Returns true on successful playback.
550 * false is returned otherwise.
553 CEmuopl opl(RATE, BIT16, STEREO);
554 CPlayer *p = CAdPlug::factory(filename, &opl);
557 unsigned long towrite, write;
559 if(!p) return false; // File couldn't be loaded
561 f = fopen(output, "wb");
563 for(towrite = RATE / p->getrefresh(); towrite; towrite -= write) {
564 write = (towrite > BUFSIZE ? BUFSIZE : towrite);
565 opl.update(buf, write);
566 fwrite(buf, write, 2, f);
573 int main(int argc, char **argv)
576 cout << "usage: " << argv[0] << " <filename> <output>" << endl;
580 if(play(argv[1], argv[2]))
588 @chapter Advanced Usage
590 This chapter explains very advanced usage of AdPlug. You do not
591 normally need to read this if you just want to write a usual frontend
592 application for AdPlug.
597 * Using the Database::
602 @section Player Lists
604 There is another argument to the @code{CAdPlug::factory(const
605 std::string &fn, Copl *opl, const CPlayers &@var{pl} = players, ...)}
606 method. The argument @var{pl} is a reference to an object holding a
609 A player list object is an instance of the @class{CPlayers} class (not
610 to be confused with the @class{CPlayer} class). The object can be
611 constant and even static (so it is possible to pass a temporary
612 object, created on the fly).
614 The @code{CPlayers} class itself is not much more than a specialized
615 @code{std::list} from the @acronym{STL}, holding pointers to objects
616 of type @class{CPlayerDesc}, which are explained below. Look into the
617 @acronym{STL} documentation for more information on @code{std::list}
620 The @class{CPlayerDesc} class is essentially an information-holder,
621 describing all needed characteristics of a player class, to create an
622 instance and load a supported file with it. It has two public
626 @item Factory factory
627 The @code{Factory} type defines a pointer to a static method inside a
628 class, inherited from @code{CPlayer}, taking a pointer to a
629 @code{Copl}-derived object as the sole argument. The meaning of this
630 attribute is to provide a pointer to the factory method of the player
631 class, which takes a pointer to an initialized @code{Copl}-derived
632 object and returns a pointer to an initialized instance of the same
633 player class, this @code{CPlayerDesc} object describes.
635 @item std::string filetype
636 This is a string containing the unique file type identifier of the
637 player class, this @code{CPlayerDesc} object describes. The string
638 normally contains the name of the file format, which the belonging
639 player class handles. This string should be unique.
642 In addition, @code{CPlayerDesc} has the following methods:
645 @item CPlayerDesc(Factory f, const std::string &type, const char *ext)
646 A specialized constructor, which initializes the whole object at
647 once. The first argument is the pointer to the factory method of the
648 accompanying player class. The second argument is a string with the
649 unique file type description, this player class handles. The last
650 argument is a pseudo @acronym{ASCIIZ} string, holding many
651 @acronym{ASCIIZ} strings with all file extensions to be associated
652 with the accompanying player class. To create such a string, include
653 the leading @samp{.} with all file extensions and terminate any file
654 extension entry with a @samp{\0} character. Concatenate all entries
655 one after the other, forming a string of strings. Terminate the last
656 entry with another @samp{\0} character, so the final string is doubly
659 @item void add_extension(const std::string &ext)
660 Adds the single file extension, passed as the only argument, to the
661 list of file extensions, the accompanying player class handles.
663 @item const char *get_extension(unsigned int n)
664 Returns a pointer to the @var{n}-th file extension string in the file
665 extension list. If @var{n} is out of range, a @samp{NULL}-pointer is
669 The @code{CPlayers} class itself adds two more methods to the
670 inherited @code{std::list} interface:
673 @item const CPlayerDesc *lookup_filetype(const std::string &ftype)
674 Returns a pointer to the first occurence of a @code{CPlayerDesc}
675 object with a file type of @var{ftype}, passed as the only
676 argument. This should also be the only object with that file type in
677 the list. If an object with the given file type is not found, a
678 @samp{NULL}-pointer if returned instead.
680 @item const CPlayerDesc *lookup_extension(const std::string &extension)
681 Returns a pointer to the first occurence of a @code{CPlayerDesc}
682 object, defining a file extension of @var{extension}, passed as the
683 only argument. Since file extensions are not necessarily unique in a
684 @code{CPlayers} list, it is often much more efficient to use the
685 search facilities provided by the @acronym{STL}. If no object,
686 specifying the given file extension, could be found, a
687 @samp{NULL}-pointer is returned instead.
690 Thus, the @code{CPlayers} class holds a list of player
691 descriptions. This list is used by the @code{CAdPlug::factory()}
692 method for the list of players to try out on a given filename. If no
693 list is passed to the method, it is @code{CAdPlug::players} by
694 default. This list always holds all players compiled into the AdPlug
695 library and is also your starting point for generating lists of your
699 @section File Providers
701 @dfn{File Providers} are special classes that provide abstracted
702 access to files. AdPlug's player classes request files using a file
703 provider, in their @code{load()} methods. This system is necessary
704 because some players require multiple files in their load stage and
705 these files cannot all be passed to their @code{load()} method
706 because the application's programmer would have to be aware of each of
707 the player's characteristics to know which files to pass.
709 A file provider class is derived from the abstract base class
710 @class{CFileProvider}, which is declared in the header
711 @file{fprovide.h}. This class defines the following methods:
714 @item binistream *open(std::string) const
715 An abstract virtual method that takes a string containing a filename
716 as the only argument and returns an initialized input-only binary
717 stream to that file. The stream is always created with x86
718 capabilities (i.e. Little-Endian, @acronym{IEEE-754} floating-point
719 numbers). If the file could not be opened, the @samp{NULL}-pointer is
722 @item void close(binistream *) const
723 An abstract virtual method that takes an input-only binary stream,
724 which was formerly created with the @code{open()} method, and closes
727 @item bool extension(const std::string &filename, const std::string &extension)
728 This static method takes a string holding a filename as its first and
729 another string holding a file extension as its last argument. It does
730 a caseless compare of the given file extension to the extension of the
731 given filename and returns @samp{true} if they match. @samp{false} is
734 @item unsigned long filesize(binistream *f)
735 This static method takes an input-only binary stream, previously
736 returned by the @code{open()} method, and returns the total size, in
737 bytes, of the associated file. The stream's state is not altered.
740 If you like to create your own file provider, you have to inherit from
741 this class and implement the methods @code{open()} and
742 @code{close()}. Remember to open the stream with x86 capabilites! One
743 situation in which you would have to create your own file provider is
744 when your application doesn't load the files from the machine's local
745 filesystem. For example, when it supports reading from archives, you
746 would use your file provider to fetch and depack the file from the
747 archive first, before passing it to AdPlug.
749 One derived file provider class is already defined in
750 @file{fprovide.h}: @class{CProvider_Filesystem}. This file provider
751 supports loading from the machine's local filesystem. File names are
752 normal paths in the operating system's common notation.
754 A file provider object can also be passed to the
755 @code{CAdPlug::factory()} method as last argument. If it is not
756 provided, it is a temporary instance of @code{CProvider_Filesystem} by
757 default. The method passes this object on to all player objects'
758 @code{load()} methods, it tries to open the file with. The player
759 objects' @code{load()} methods also take the file provider object as
760 their last argument and default to @code{CProvider_Filesystem} if none
763 @node Using the Database
764 @section Using the Database
766 AdPlug recently features a full-blown database, specialized for
767 storing information relevant to the replay of AdLib-specific music
770 The database can be maintained by using the @command{adplugdb}
771 command. Usage of this command is explained in its own manual page.
773 The application's interface to the database is defined through the
774 @class{CAdPlugDatabase} class, residing in the header file
777 If you just want to pass a database for AdPlug to make use of it,
778 reading @ref{Usage with CAdPlug} is sufficient. If you want to write a
779 complete database manipulation application, you have to read the other
783 * Usage with CAdPlug::
786 * Players using the Database::
790 @node Usage with CAdPlug
791 @subsection Usage with CAdPlug
793 You can pass AdPlug a database for it to get specific information
794 about a file. Some file formats store insufficient information within
795 themselves and AdPlug uses the database to get the missing data. You
796 do not need to include any more header files other than
797 @file{adplug.h} within your application to do this.
799 To hand a database to AdPlug, you have to initialize an instance of
800 @code{CAdPlugDatabase} first. To do this, you just have to declare an
801 object of this class. This creates an empty database for
804 Additionally, for the database to be of any use to AdPlug, you have to
805 fill it with some records (see @ref{Records}). This is most preferably
806 done by loading an already existing database from a file. To do this,
807 you use the @code{load(std::string @var{db_name})} method of the
808 class. This will merge any records in the database file @var{db_name}
809 into your database object. You can merge any more database files, if
810 you wish. Only new records will be merged. Duplicate records will be
813 To hand your database to AdPlug, you simply call
814 @code{CAdPlug::set_database(CAdPlugDatabase *db)} and pass a pointer
815 to your database object as the only argument. From now on, AdPlug will
816 use your database to do lookups for special information about some
817 file types. You have to keep your instance of the database until you
818 close AdPlug and free it by yourself after that.
823 @dfn{Records} are the primary data containers in the database. A
824 record is a very flexible object. It can store virtually any number of
825 different data types, you can think of.
827 All record classes are derived from the common abstract base class
828 @code{CAdPlugDatabase::CRecord}. All records have at least three
832 @item RecordType type
833 Specifies what type of data this record holds. @code{RecordType} is an
834 enumeration variable with the following values:
838 This record doesn't store any more information than the three standard
841 This record additionally stores song name and author information.
843 This record additionally stores timer clock speed information.
847 This is the unique key, allocated for any record in the
848 database. @xref{Keys}.
850 @item std::string filetype
851 Holds the unique file type of the file associated with the
852 record. This value is taken from the player list (see
856 The common base class @code{CAdPlugDatabase::CRecord} defines a
857 static method @code{factory(RecordType type)} for application usage
858 that returns a pointer to a newly allocated @class{CRecord} object, or
859 the @samp{NULL}-pointer if an error occured. You pass the type of the
860 record to be created as the only argument.
862 All other public methods are meant for internal use of the database
863 only and should not be called from an application. They are explained
864 here anyway, for informational purposes:
867 @item CRecord *factory(binistream &in)
868 Another factory method that takes a reference to an input-only binary
869 stream as the only argument. It tries to extract a record from the
870 stream's current position, initializes a new record object with the
871 data and returns a pointer to that record object. The
872 @samp{NULL}-pointer is returned if the record type couldn't be
873 determined from the stream's data.
875 @item void write(binostream &out)
876 Writes the record's contents to the output-only binary stream,
877 referenced by the only argument.
879 @item bool user_read(std::istream &in, std::ostream &out)
880 Attaches to the input and output streams, referenced by the first and
881 second arguments and tries to prompt an apparent user for the relevant
884 @item bool user_write(std::ostream &out)
885 Attaches to the output stream, referenced by the only argument and
886 writes the record's contents in human-readable form to it.
888 @item void read_own(binistream &in)
889 @itemx void write_own(binostream &out)
890 @itemx bool user_read_own(std::istream &in, std::ostream &out)
891 @itemx bool user_write_own(std::ostream &out)
892 Abstract virtual base methods to be inherited by the real record
893 classes to read and write their own data, in both binary and
896 @item unsigned long get_size()
897 Abstract virtual base method to be inherited by the real record
898 classes to report the size of the extra data defined by them.
904 @dfn{Keys} are @acronym{CRC32}:@acronym{CRC16} pairs that uniquely
905 identify a file's contents and are used to associate a record with a
906 file. Only if the file's key match with the record key, that record is
907 actually used for that file.
909 Keys are stored in key objects, which are instances of the
910 @code{CAdPlugDatabase::CKey} class. The class has two attributes,
911 @code{crc16} and @code{crc32} which store the two @acronym{CRC}
912 values, respectively. It also has the following methods:
916 A constructor that creates an empty key object.
917 @item CKey(binistream &in)
918 A constructor that creates a key from the contents of the input-only
919 binary stream, referenced by the only argument.
921 @item bool operator==(const CKey &key)
922 Operator that compares two key objects and returns @samp{true} when
923 they are equal. @samp{false} is returned otherwise.
926 @node Players using the Database
927 @subsection Players using the Database
929 The following players make active use of the database:
933 The IMF player uses the database to find out about the timer clock
934 speed of a file, since this data is not stored in the file itself.
938 @subsection Direct Usage
940 The following methods are for application usage of the database:
943 @item bool load(std::string db_name)
944 @itemx bool load(binistream &f)
945 Two versions to load a database. The first method takes a string
946 containing a file name of a file from which the database is
947 loaded. The second method takes a reference to an input-only binary
948 stream to load the database from.
950 @item bool save(std::string db_name)
951 @itemx bool save(binostream &f)
952 Two versions to save the database. These work analogous to the
953 @code{load()} methods, above.
955 @item bool insert(CRecord *record)
956 Inserts the record object, pointed to by the only argument, into the
957 database and returns @samp{true} on successful operation. @samp{false}
958 is returned otherwise. Duplicate record entries (i.e. records that
959 have the same key) cannot be inserted into the database and old ones
960 will not automatically be overwritten by the new ones with this
961 method. @samp{false} is returned in this case.
963 @item void wipe(CRecord *record)
965 Two versions of a method to remove (wipe) a record from the
966 database. The first version takes a pointer to a record object as the
967 only argument and removes exactly this record from the database. The
968 record object itself is deallocated, too. Do not reference it again!
969 If the record object is not in the database, nothing is done. The
970 second version removes the record at the current position in the
973 @item CRecord *search(CKey const &key)
974 Takes a reference to a key object, searches for a record with the same
975 key value in the database and returns a pointer to this record. The
976 @samp{NULL}-pointer is returned if the record could not be found.
978 @item bool lookup(CKey const &key)
979 The same as @code{search()}, but instead of returning a pointer to the
980 record, it just positions the internal database pointer to the
981 corresponding record. Returns @samp{true} if the record could be found
982 and @samp{false} otherwise.
984 @item CRecord *get_record()
985 Returns a pointer to the record at the current position in the
986 database. The @samp{NULL}-pointer is returned if an error occured.
988 @item bool go_forward()
989 Advances the internal position in the database by one record. Returns
990 @samp{true} on success, @samp{false} otherwise.
991 @item bool go_backward()
992 The same as @code{go_forward()}, but goes backward by one record.
993 @item void goto_begin()
994 Goes to the beginning (i.e. the first record) of the database.
995 @item void goto_end()
996 Goes to the end (i.e. the last record) of the database.
999 @node Without CAdPlug
1000 @section Without CAdPlug
1002 It is also possible to only use specific players from the AdPlug
1003 library, without using the @code{CAdPlug} class to cycle through them
1006 If you just want to use a single player class from the library, you
1007 only include that player's header file in your application's source
1010 You can construct an instance of that player by either using its
1011 constructor or by using the @code{factory()} method of that
1012 class. Both have the same syntax and take a pointer to an initialized
1013 @code{Copl}-derived object.
1015 Use the player's @code{load()} method to load a file. It takes a
1016 filename as the first argument and, optionally, a file provider class
1017 as its last argument.
1019 All other methods have already been explained in the text above.
1024 This chapter gives some coding guidelines for people wishing to hack
1025 around in AdPlug. Be sure to also read the overall and system-specific
1026 @file{INSTALL} files in the distribution's base directory to learn
1027 more about the build systems.
1035 @section Coding Style
1036 I do not really enforce any coding style guidelines (i don't adhere to any
1037 style guidelines myself, so... ;) ), but it would be nice if you follow the
1038 overall coding style, used throughout most of AdPlug's source files. If you
1039 don't, that's perfectly okay, too.
1041 Most of today's "super-intelligent" editors, like MSVC's one or GNU Emacs'
1042 cc-mode, have their own idea of what the code has to look like, anyway. And
1043 since most people tend to use these, there's no point in torturing them to
1044 always having to change anything their editor thinks it knows better. ;)
1047 @section Debug Logging
1049 AdPlug recently offers centralized debug log management. If you like to
1050 implement debug logging inside your code, please follow these guidelines:
1052 To implement debug logging, @code{#include "debug.h"} in your code
1053 (this header is @emph{not} being installed with the rest of the
1054 AdPlug header files into your standard include directory! It is only
1055 available in AdPlug's @file{src/} subdirectory!).
1057 @file{debug.h} is C code, so it is useable from both C and C++
1058 sources. The only function you have to use is the
1059 @code{LogWrite(fmt, ...)} function. @code{LogFile()} is used by AdPlug
1060 internally. @code{LogWrite()} works exactly like @code{printf()},
1061 instead that it writes to a logfile, rather than on the console.
1063 Please format your log messages like this:
1067 If your method/function is going to output a lot of debug info
1068 (i.e. more than one line), please put a @code{LogWrite()} directly at
1069 the beginning of your function, which looks like this:
1072 LogWrite("*** yourclass::yourmethod(@var{param1}, @var{param2}, @var{...}) ***\n");
1075 And put the following line before every return from your function:
1078 LogWrite("--- yourclass::yourmethod ---\n");
1081 This way, one can easily inspect the logfile and know to which
1082 function every logfile-line belongs. The @code{***} lines mark the
1083 start of a function, and the @code{---} lines mark the end.
1085 Please substitute @var{param*} with the corresponding parameter values
1086 of your function, if that is reasonable. For example, it won't help
1087 much to log a pointer value --- just put something bogus or helpful
1088 there, or noting (i.e. just a comma, so the logfile reader knows, to
1089 which parameters the other values correspond). But logging the values
1090 of passed ints or strings could be very helpful.
1093 If your method/function is going to output just one line, format the
1094 line something like this:
1097 LogWrite("yourclass::yourmethod(@var{param1}, @var{param2}): your message\n");
1100 You don't need the @code{***} and @code{---} beginning and end markers
1104 For threads, there is no way but to prefix any line with the function
1105 name, because these messages will be sprayed throughout the logfile.
1108 @node Player development
1109 @chapter Player development
1111 Before you try to write a new player for AdPlug, be sure to also read
1112 through @ref{Hacking}.
1117 * Loading and File Providers::
1118 * Sound generation::
1121 @node Before the work
1122 @section Before the work
1124 Your player normally consists of two files (the @file{.h} &
1125 @file{.cpp} files) and you normally name them by the file extensions,
1126 your player handles. For example, the HSC player consists of the files
1127 @file{hsc.cpp} & @file{hsc.h}, because it handles @file{.hsc}
1128 files. This is the same with your player class name. Thus, the HSC
1129 player's class is called @class{ChscPlayer}. If any of these names
1130 happens to be already taken for other purposes, just name your player
1131 something else, appropriately.
1133 @file{player.h} contains the abstract player interface. You have to
1134 include it in your player to communicate with AdPlug. It also contains
1135 some very helpful structures for use in your player. You don't need to
1136 use the structs, but you have to use the methods provided by the
1137 @code{opl} object (declared in @file{opl.h}, but automatically
1138 included from @file{player.h}) inside the player class to do the OPL
1139 I/O and initialization work.
1144 All you have to do now is to inherit the @class{CPlayer} class into
1145 your own player class and fill the abstract methods with code. You at
1146 least have to fill in the following methods:
1149 bool load(const std::string &filename, const CFileProvider &fp);
1151 void rewind(int subsong);
1153 std::string gettype();
1156 The other methods from @code{CPlayer} just serve informational
1157 purposes (as does @code{gettype()}, but it's required anyway) for
1158 AdPlug's info box and needn't to be filled. It would be nice if you
1159 fill them anyway, if that's reasonable for your player.
1161 There's one more public method you have to define in your player
1165 static CPlayer *factory(Copl *newopl);
1168 Since it is static, it isn't already virtually defined in the
1169 @code{CPlayer} class and you have to add it manually. This method
1170 should return a pointer to a freshly initialized object of your player
1171 class. If any errors occured (e.g. not enough memory), return @samp{0}
1174 Return true from your @code{load()} method, if the file was loaded
1175 successfully, or false if it couldn't be loaded for any reason (e.g.
1176 because AdPlug passed a wrong file to your player). Your
1177 @code{update()} method will be called with the frequency, you return
1178 from your @code{getrefresh()} method, in Hz. Return true from
1179 @code{update()} if your module hasn't ended yet. If it looped or
1180 ended, return false from that point, but play further for any
1181 subsequent calls to @code{update()}. AdPlug will rewind or stop your
1182 player by itself, using the @code{rewind()} method, when necessary.
1184 AdPlug passes the number of the subsong, it wants to play next, to the
1185 @code{rewind()} method of your player. This can be any value from
1186 @samp{0} to the value returned by @code{getsubsongs()}. If you haven't
1187 provided your own @code{getsubsongs()}, AdPlug will presume your
1188 player doesn't have support for subsongs. In that case, AdPlug will
1189 always @code{rewind(0)}. Please ignore any value passed to
1190 @code{rewind()} that is out of spec for your player. This should
1191 virtually never happen, but who knows. If a value of @samp{-1} is
1192 given as an argument, you should rewind the currently playing
1195 After initializing your player (either by a call to @code{factory()}
1196 or by creating an instance by itself), AdPlug normally first calls
1197 @code{load()} and then @code{getrefresh()} and @code{update()} in a
1198 loop until something happens (i.e. the user stops playback or the song
1199 ends). @code{rewind()} and all the informational methods can be called
1200 anytime in between the other calls, but of course only after
1201 @code{load()} has been called.
1203 You can add your own constructors, destructors and methods to your
1204 player object, as you like. AdPlug won't care in any way.
1206 @node Loading and File Providers
1207 @section Loading and File Providers
1209 The @code{load(const std::string &filename, const CFileProvider &fp)}
1210 method needs some special explanation. This method takes two
1211 arguments. The first is a reference to a string containing the
1212 filename of the main file for your player to load. This is the
1213 filename the user selected in the frontend (maybe altered by the
1214 frontend, but not by AdPlug) and does not need to have any meaning to
1217 To finally load your files to get to their data, you have to request
1218 them. This is done through a @dfn{File Provider}. A reference to a
1219 file provider is always passed as the second argument to your
1220 @code{load()} method. You will most likely want to load the file,
1221 using the filename passed as the first argument. To do this, you
1222 simply call @code{binistream *f = fp.open(filename)}. This method
1223 returns a pointer to an open, input-only binary stream of the
1224 requested file. You can now operate on this stream, using its standard
1225 interface (refer to the manual of the binary I/O stream class library
1226 for further information). When you're done loading your file, don't
1227 forget to call @code{fp.close(f)} to close it again. It is very
1228 important to do this anytime you leave your @code{load()} method! Any
1229 streams not closed will be left open for the whole lifetime of the
1230 controlling process!
1232 Don't worry about the passed filename. It normally doesn't need to
1233 have any meaning to your player. The file provider will know how and
1234 from where to open the file.
1236 @code{fp.open()} returns a null-pointer if something went wrong
1237 (e.g. file not found or access denied, etc.). If this happens, return
1238 @samp{false} from your @code{load()} method immediately. You do not
1239 have to call @code{fp.close()} in this case.
1241 The @class{CFileProvider} class offers two convenience methods. These
1242 are @code{unsigned long filesize(binistream *f)} and @code{bool
1243 extension(const std::string &filename, const std::string
1246 @code{filesize()} returns the size in bytes of the stream, pointed to
1247 by @code{f}, without altering it otherwise. @code{extension()} does a
1248 filename extension check as follows: The first argument is a reference
1249 to a string containing a filename. The second argument is a reference
1250 to a string containing a file extension to check for. If the passed
1251 filename has got exactly this extension (caselessly), the method
1252 returns @samp{true}. @code{false} is returned otherwise.
1254 @node Sound generation
1255 @section Sound generation
1257 You generate sound by using the @code{Copl::write(@var{reg},
1258 @var{val})} method of the @code{Copl} class, which has been passed to
1261 @var{reg} is the number of the register of the OPL chip, you want to
1262 write data into. @var{val} is the value to write into it. There is no
1263 method to read back written data from an OPL chip, as this also was
1264 not possible with the original hardware. Log all data into an array if
1265 you have to remember written values.
1267 If your player supports the dual-OPL2 or OPL3 configurations, you can
1268 use the method @code{Copl::setchip(@var{n})} to set the output chip
1269 number, all subsequent @code{write()} methods will write to. As two
1270 chips can be supported at maximum, the value of @var{n} may only be 0
1271 or 1 for the first or the second chip, respectively.
1273 Before switching to another chip, your player always has to make sure
1274 that the configuration, you are going to address, is supported by the
1275 current OPL class. This can be done by calling the
1276 @code{Copl::gettype()} method, which will return the currently
1277 supported OPL chip type as an enumeration of type
1278 @code{Copl::ChipType}.
1280 If the desired configuration is not supported, your player should
1281 support playback on any of the other configurations. Your player
1282 should never switch to another OPL chip when this is not actually
1283 supported by the OPL class! The sound will be totally messed up.
1285 @node Protracker based players
1286 @chapter Protracker based players
1288 If you want to create a player for a Protracker-derivative format, the
1289 generic Protracker player @class{CmodPlayer} that comes with AdPlug can
1290 be of great help. It supports all standard Protracker features, plus a
1291 good set of extensions to cope with most derivative formats.
1293 When writing a player for a Protracker-derivative format, it is almost
1294 always better to use and extend the @code{CmodPlayer} class, instead
1295 of writing a whole new player.
1300 * Protracker Loaders::
1301 * Designing your Loader::
1302 * Loading Patterns::
1303 * Loading Instruments::
1305 * Special Arpeggio::
1311 In addition to handling your data just like the original Protracker
1312 would, AdPlug's generic Protracker player has the following extra
1316 @item Special Arpeggio lists, compatible with the SA2 format.
1317 @item Extendable set of up to 256 note commands.
1318 @item Simulates many different tracker flavors.
1319 @item Arbitrary numbers of rows, patterns, tracks, instruments and
1323 The only current limitation is that it has a maximum 9 voice
1324 polyphony, which isn't really a limitation, since the OPL2 is just 9
1330 For historical reasons, @code{CmodPlayer} sets defaults to some
1331 values, so they need not be initialized. These are:
1334 @item The orderlist is preallocated to 128 entries.
1335 @item The patterndata is preinitialized to 64 patterns with 9 channels
1337 @item The instruments array is preallocated to 250 instruments.
1338 @item All flags are cleared (simulates Protracker flavor).
1341 These are mostly standard Protracker limits. They stem from the
1342 original SA2 defaults, for which this was once the player. Look at the
1343 @code{CmodPlayer} constructor for info on which variables are
1346 @node Protracker Loaders
1347 @section Protracker Loaders
1349 When you decided to extend the @code{CmodPlayer} class, instead of
1350 writing a whole new player, you do this by writing a loader for
1351 it. This is done very similarily to writing a unique player for
1352 AdPlug. Thus, reading the @ref{Player development} chapter is
1353 recommended for this task, too.
1355 Instead of naming your player class @code{CxxxPlayer}, you should name
1356 it @code{CxxxLoader} or something appropriate if the name is already
1357 taken. You then publicly inherit the @code{CmodPlayer} class and fill
1358 the missing methods with code. These are now:
1361 static CPlayer *factory(Copl *newopl);
1362 bool load(const std::string &filename, const CFileProvider &fp);
1364 std::string gettype();
1367 Plus maybe some (or all) of the other informational methods, listed in
1368 the @ref{Player development} chapter. Refer also to that chapter to
1369 see what the above methods are about.
1371 @node Designing your Loader
1372 @section Designing your Loader
1374 File validation and initial loading is the same as it would be with
1375 any other player. One speciality is that you have to call
1376 @code{rewind(0)} whenever you completely loaded a valid file. Don't
1377 call it when you just exit your loader because the file was invalid!
1379 The Protracker player needs at least an orderlist, the patterns and
1380 the instruments to function. Most of the time, you have to convert
1381 these between your file's ordering and @code{CmodPlayer}'s internal
1382 ordering. Look in the file @file{protrack.cpp}, @code{CmodPlayer}'s
1383 actual sources, for a list on how these constructs are ordered
1386 Also, please look up the @ref{Defaults} section to see if you need to
1387 reallocate any of the defaults.
1389 There are some variables that you have automatically inherited with
1390 your new loader and that you have to set in order to tell the
1391 Protracker player something about your loaded module. These are the
1396 The orderlist length. When @code{CmodPlayer}'s orderlist pointer
1397 equals or is bigger than this length, it is automatically wrapped
1398 around to @code{restartpos}. This variable has no default.
1401 Refer to @ref{Loading Patterns} below on this one. This variable
1402 defaults to @samp{0}.
1405 The restarting position in the orderlist, when @code{length} is
1406 exceeded. This variable has no default.
1409 A flag array, telling the player which channels in every pattern are
1410 actually active and to be played. The ordering of this variable is a
1411 bit awkward, so be careful! It is a 32-bit @code{unsigned long},
1412 holding the activeness of a channel in each of its bits,
1413 @emph{starting at the highest order bit}. It can hold values for up to
1414 32 channels. So, to set channel 0 active, you have to set bit 31
1415 (counting from bit 0) to @samp{1} and so on. Setting any bits for
1416 channels that are not defined has no effect. This variable defaults to
1417 all bits set to 1, meaning all channels are enabled.
1420 Initial protracker-compatible speed setting. This variable defaults to
1421 @samp{6}, the standard Protracker speed setting.
1424 Initial protracker-compatible bpm (sometimes called tempo)
1425 setting. This variable has no default.
1428 Refer to @ref{Special Flags} below. This variable defaults to
1429 @samp{Standard}, which sets standard Protracker defaults and imposes
1433 The number of patterns in your module. You don't need to set this
1434 value. If you leave it at @samp{0}, @code{CmodPlayer} will
1435 automatically determine the number of @emph{accessed} patterns (which
1436 need not be the same as the actual number of patterns in your module)
1437 from the orderlist, in the @code{rewind()} method. The value serves
1438 only informational purposes, anyway. It is not needed for the actual
1439 playback. If you think you know better than @code{CmodPlayer}, feel
1440 free to set it to something else and @code{CmodPlayer} won't touch it
1441 anymore and display your value instead. This variable defaults to
1445 @node Loading Patterns
1446 @section Loading Patterns
1448 AdPlug's Protracker player stores the tracks (or channels, as some may
1449 call them), that make up a pattern, in a way that makes it possible
1450 for you to reorder and reuse them in an easy way. This also makes
1451 storing patterns in the classic way a bit awkward.
1453 If you just want to store your tracks the classic Protracker way
1454 (usually the case), first use the @code{CmodPlayer::init_trackord()}
1455 method to do an initial setup. Then store your tracks in a sequential
1456 manner, counting from 0, in the @code{tracks} array. That is, for the
1457 first 9 channels of your first pattern, use @code{tracks[0..9]}. The
1458 second dimension of this array holds the rows of each channel. For the
1459 next 9 channels, you use @code{tracks[10..19]}, and so on.
1461 If you want to make use of the reorder/reuse feature of the
1462 @code{trackord} array, please refer to the @file{sa2.cpp} source
1463 file. This player utilizes this method. Basically, the
1464 @code{trackord} array tells the player which track out of the
1465 @code{tracks} array it has to insert for each of the 9 tracks of a
1466 pattern. Thus, the first dimension of this array stands for the
1467 corresponding pattern and the next dimension holds the entries for all
1470 @code{CmodPlayer} orders its note data, in the @code{Tracks} struct,
1473 @code{note} holds the note value. A value of @samp{0} means @samp{no
1474 note}. A value of @samp{127} means @samp{key off}. Values from
1475 @samp{1} to @samp{96} are actual notes to be played. Everything else
1476 is ignored. The octaves are encoded with the actual note values. Thus,
1477 notes from @samp{1} to @samp{12} are the 12 halftone-steps of the
1478 first, lowest octave, @samp{13} to @samp{24} are those of the next
1479 lowest octave, and so on. Refer to the source code to see which
1480 frequencies are actually associated with the note values.
1482 @code{inst} holds the instrument to be played with this note. Again, a
1483 @samp{0} value means no instrument is associated with this note and
1484 the last active instrument is taken instead. Otherwise, the instrument
1485 with the number @code{inst} minus 1 is fetched from the @code{inst}
1486 array (it's 0 based).
1488 @code{command} holds the command to be issued with this note. All
1489 available commands are listed in the following table:
1491 @multitable {@code{255--}} {Command descriptionwifuehwuifhw} {Parametersewufwuhwjjhhui} {@code{[0-3,F]iufhu}}
1492 @headitem Value @tab Command description @tab Parameters @tab Range
1493 @item @code{@ @ 0xy} @tab Arpeggio @tab @code{xy}=1st note,2nd note @tab @code{[0-F]}
1494 @item @code{@ @ 1xx} @tab Frequency slide up @tab @code{xx}=sliding speed @tab @code{[0-FF]}
1495 @item @code{@ @ 2xx} @tab Frequency slide down @tab @code{xx}=sliding speed @tab @code{[0-FF]}
1496 @item @code{@ @ 3xx} @tab Tone portamento @tab @code{xx}=sliding speed @tab @code{[0-FF]}
1497 @item @code{@ @ 4xy} @tab Vibrato @tab @code{xx}=speed,depth @tab @code{[0-F]}
1498 @item @code{@ @ 5xy} @tab Tone portamento & volume slide @tab @code{xy}=vol up|vol down @tab @code{[0-FF]}
1499 @item @code{@ @ 6xy} @tab Vibrato & volume slide @tab @code{xy}=vol up|vol down @tab @code{[0-FF]}
1500 @item @code{@ @ 7xx} @tab Set tempo @tab @code{xx}=new tempo @tab @code{[0-FF]}
1501 @item @code{@ @ 8--} @tab Release sustaining note
1502 @item @code{@ @ 9xy} @tab Set carrier/modulator volume @tab @code{xy}=car vol|mod vol @tab @code{[0-F]}
1503 @item @code{@ 10xy} @tab SA2 volume slide @tab @code{xy}=vol up|vol down @tab @code{[0-F]}
1504 @item @code{@ 11xx} @tab Position jump @tab @code{xx}=new position @tab @code{[0-FF]}
1505 @item @code{@ 12xx} @tab Set carr. & mod. volume @tab @code{xx}=new volume @tab @code{[0-3F]}
1506 @item @code{@ 13xx} @tab Pattern break @tab @code{xx}=new row @tab @code{[0-FF]}
1507 @item @code{@ 14??} @tab Extended command:
1508 @item @code{@ @ @ 0y} @tab Set chip tremolo @tab @code{y}=new depth @tab @code{[0-1]}
1509 @item @code{@ @ @ 1y} @tab Set chip vibrato @tab @code{y}=new depth @tab @code{[0-1]}
1510 @item @code{@ @ @ 3y} @tab Retrig note @tab @code{y}=retrig speed @tab @code{[0-F]}
1511 @item @code{@ @ @ 4y} @tab Fine volume slide up @tab @code{y}=vol up @tab @code{[0-F]}
1512 @item @code{@ @ @ 5y} @tab Fine volume slide down @tab @code{y}=vol down @tab @code{[0-F]}
1513 @item @code{@ @ @ 6y} @tab Fine frequency slide up @tab @code{y}=freq up @tab @code{[0-F]}
1514 @item @code{@ @ @ 7y} @tab Fine frequency slide down @tab @code{y}=freq down @tab @code{[0-F]}
1515 @item @code{@ @ @ 8y} @tab Pattern delay (rows) @tab @code{y}=rows to delay @tab @code{[0-F]}
1516 @item @code{@ 15xx} @tab SA2 set speed @tab @code{xx}=new speed @tab @code{[0-FF]}
1517 @item @code{@ 16xy} @tab AMD volume slide @tab @code{xy}=vol up|vol down @tab @code{[0-F]}
1518 @item @code{@ 17xx} @tab Set instrument volume @tab @code{xx}=new volume @tab @code{[0-3F]}
1519 @item @code{@ 18xx} @tab AMD set speed @tab @code{xx}=new speed @tab @code{[0-FF]}
1520 @item @code{@ 19xx} @tab RAD set speed @tab @code{xx}=new speed @tab @code{[0-FF]}
1521 @item @code{@ 20xx} @tab RAD volume slide @tab @code{xx}=vol up/down @tab @code{[0-FF]}
1522 @item @code{@ 21xx} @tab Set modulator volume @tab @code{xx}=new volume @tab @code{[0-3F]}
1523 @item @code{@ 22xx} @tab Set carrier volume @tab @code{xx}=new volume @tab @code{[0-3F]}
1524 @item @code{@ 23xx} @tab Fine frequency slide up @tab @code{xx}=freq up @tab @code{[0-FF]}
1525 @item @code{@ 24xx} @tab Fine frequency slide down @tab @code{xx}=freq down @tab @code{[0-FF]}
1526 @item @code{@ 25xy} @tab Set carrier/modulator waveform @tab @code{xy}=carr wav|mod wav @tab @code{[0-3,F]}
1527 @item @code{@ 26xy} @tab Volume slide @tab @code{xy}=vol up|vol down @tab @code{[0-F]}
1528 @item @code{@ 27xy} @tab Set chip tremolo/vibrato @tab @code{xy}=tr depth|vb depth @tab @code{[0-1]}
1529 @item @code{@ 28xy} @tab DTM frequency slide @tab @code{xy}=frames up|down @tab @code{[0-F]}
1530 @item @code{@ 29xx} @tab Pattern delay (frames) @tab @code{xx}=frames to delay @tab @code{[0-FF]}
1531 @item @code{255--} @tab No operation (NOP)
1534 The @code{param1} and @code{param2} variables hold the command's
1535 parameters. These are command-dependant. Refer to the table above to
1536 see what they do with each of the commands and their value ranges. An
1537 @samp{xx} in the @emph{Parameters} column means that @code{param1} and
1538 @code{param2} form one 2-digit parameter, with @code{param1} being the
1539 leftmost decimal. Otherwise, @samp{x} refers to @code{param1} and
1540 @samp{y} to @code{param2}.
1542 @node Loading Instruments
1543 @section Loading Instruments
1545 For the instrument data, @code{CmodPlayer} stores it in the
1546 @code{inst[].data[]} array, in the following way:
1548 @multitable {Index} {Modulator} {Amp Mod / Vib / EG type / Key Scaling / Multiple} {@samp{0x00}}
1549 @headitem Index @tab Operator @tab Description @tab Register
1550 @item 0 @tab Channel @tab (Panning) / Feedback strength / Connection type @tab @samp{0xc0}
1551 @item 1 @tab Modulator @tab Tremolo / Vibrato / Sustain / KSR / Multiple @tab @samp{0x20}
1552 @item 2 @tab Carrier @tab Tremolo / Vibrato / Sustain / KSR / Multiple @tab @samp{0x23}
1553 @item 3 @tab Modulator @tab Attack Rate / Decay Rate @tab @samp{0x60}
1554 @item 4 @tab Carrier @tab Attack Rate / Decay Rate @tab @samp{0x63}
1555 @item 5 @tab Modulator @tab Sustain Level / Release Rate @tab @samp{0x80}
1556 @item 6 @tab Carrier @tab Sustain Level / Release Rate @tab @samp{0x83}
1557 @item 7 @tab Modulator @tab Wave Select @tab @samp{0xe0}
1558 @item 8 @tab Carrier @tab Wave Select @tab @samp{0xe3}
1559 @item 9 @tab Modulator @tab Key scaling level / Operator output level @tab @samp{0x40}
1560 @item 10 @tab Carrier @tab Key scaling level / Operator output level @tab @samp{0x43}
1563 There are three extensions to the standard instrument data. These are
1564 also stored within the @code{inst[]} array.
1567 @item The @emph{Special Arpeggio}. This is explained in the
1568 @ref{Special Arpeggio} section, below.
1570 @item The @code{slide} variable. This is a pre-slide value that is
1571 always added to the frequency of the note, whenever this instrument is
1574 @item The @code{misc} variable. This is just the holder for the value
1575 of the 0xbd register (i.e. the "drums'n'misc" register) of the OPL.
1579 @section Special Flags
1581 The @code{flags} variable holds special flags to change the behaviour
1582 of the player. These are:
1586 Act like standard Protracker would. This is the default.
1589 Command parameters are decimal values, not hexadecimal. For split
1590 parameter commands (i.e. commands with two parameters, like
1591 @samp{0xy}), this has no effect, since decimal values would be from
1592 @samp{0} to @samp{9}, anyway. But commands that take both parameters
1593 as one value (i.e. like @samp{1xx}) now take values from @samp{0} to
1594 @samp{99} and handle them properly (i.e. decimal wrap-around is now at
1595 @samp{9} to @samp{10} and not at @samp{F} to @samp{10}).
1598 Treat the files like @emph{Faust Music Creator} does. This tracker
1599 uses a different volume handling scheme. In standard Protracker, the
1600 volume is computed as follows:
1603 final volume = channel volume = instrument volume
1606 In @emph{Faust Music Creator}, it is done like this:
1609 final volume = (channel volume + instrument volume) / 2
1613 This prevents the OPL key off/on toggle on every newly played
1614 note. Some trackers require it that way...
1617 Sets the player into OPL3 mode. Extended register settings of the OPL3
1618 become effective and the player initializes the OPL chip to OPL3
1619 mode. This has no effect if the hardware does not support OPL3
1620 features. Be careful to set panning information in register
1621 @code{0xc0} or else no sound will appear.
1624 Sets tremolo depth to 4.8dB upon each @code{rewind()}.
1627 Sets Vibrato depth to 14 cents upon each @code{rewind()}.
1630 Enables the OPL percussion mode.
1633 These flags can be set and unset at any time. To set a flag, just
1634 binary @emph{OR} it with the @code{flags} variable. Use the
1635 @code{enum Flags} data type, defined in the @code{CmodPlayer} class
1638 @node Special Arpeggio
1639 @section Special Arpeggio
1641 To use the @emph{Special Arpeggio} facility, you have to initalize it
1642 first. Use the @code{init_specialarp()} method for this
1643 purpose. @code{CmodPlayer}'s deconstructor automatically handles the
1646 The special arpeggio uses the 4 variables @code{arpstart},
1647 @code{arpspeed}, @code{arppos} and @code{arpspdcnt} of the
1648 @code{Instrument} struct.
1650 [TODO: actually explain. Refer to sa2.[cpp,h] and the original SA2 docs in
1651 the meantime. The following table summarizes the special commands.]
1653 @multitable {Value} {Set carr. & mod. volume}
1654 @headitem Value @tab Command description
1655 @item @samp{252} @tab Set carr. & mod. volume
1656 @item @samp{253} @tab Release sustaining note
1657 @item @samp{254} @tab Arpeggio loop
1658 @item @samp{255} @tab End of special arpeggio
1661 @node Copying This Manual
1662 @appendix Copying This Manual
1665 * GNU Free Documentation License:: License for copying this manual.
1671 @unnumbered Method Index
1675 @node Variable Index
1676 @unnumbered Variable Index
1681 @unnumbered Class Index