1 This is libadplug.info, produced by makeinfo version 4.13 from
4 This manual documents the AdPlug core library, version 2.2.1.
6 Copyright (C) 2002 - 2010 Simon Peter <dn.tlp@gmx.net>
8 Permission is granted to copy, distribute and/or modify this
9 document under the terms of the GNU Free Documentation License,
10 Version 1.1 or any later version published by the Free Software
11 Foundation; with no Invariant Sections, with the Front-Cover texts
12 being "A GNU Manual," and with the Back-Cover Texts as in (a)
13 below. A copy of the license is included in the section entitled
14 "GNU Free Documentation License."
16 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
17 modify this GNU Manual, like GNU software. Copies published by
18 the Free Software Foundation raise funds for GNU development."
20 INFO-DIR-SECTION Software Libraries
22 * AdPlug Core Library: (libadplug). AdPlug Core Library 2.2.1
26 File: libadplug.info, Node: Top, Next: Introduction, Up: (dir)
31 This manual documents the AdPlug core library, version 2.2.1.
33 Copyright (C) 2002 - 2010 Simon Peter <dn.tlp@gmx.net>
35 Permission is granted to copy, distribute and/or modify this
36 document under the terms of the GNU Free Documentation License,
37 Version 1.1 or any later version published by the Free Software
38 Foundation; with no Invariant Sections, with the Front-Cover texts
39 being "A GNU Manual," and with the Back-Cover Texts as in (a)
40 below. A copy of the license is included in the section entitled
41 "GNU Free Documentation License."
43 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
44 modify this GNU Manual, like GNU software. Copies published by
45 the Free Software Foundation raise funds for GNU development."
49 * Introduction:: What is AdPlug?
50 * Basic Usage:: Using AdPlug in your programs the easy way.
51 * Advanced Usage:: Using AdPlug in your programs the hard way.
52 * Hacking:: How to hack around in AdPlug.
53 * Player development:: How to write new replayers for AdPlug.
54 * Protracker based players:: How to write Protracker based players.
55 * Copying This Manual:: Your rights and freedoms.
61 File: libadplug.info, Node: Introduction, Next: Basic Usage, Prev: Top, Up: Top
66 AdPlug is a free, multi-platform, hardware independent AdLib sound
67 player library, mainly written in C++. AdPlug plays sound data,
68 originally created for the AdLib and Sound Blaster (OPL2/OPL3) audio
69 boards, on top of an OPL emulator or by using the real hardware. No OPL
70 chip is required for playback.
78 File: libadplug.info, Node: Supported Formats, Next: Concepts, Up: Introduction
83 AdPlug implements unique file replayers for each supported format in
84 order to achieve the best possible replay quality. Below is a list of
85 all currently supported file formats along with information about
86 possible replay issues. Players marked as "preliminary" aren't
87 considered final by the author(s) and may contain many replay issues,
88 but are included for testing purposes anyway.
90 * `A2M': AdLib Tracker 2 by subz3ro
91 * File format versions 1, 4, 5 and 8 are supported
93 * Unimplemented commands (versions 1-4): `FF1 - FF9, FAx - FEx'
95 * Unimplemented commands (versions 5-8): `Gxy, Hxy, Kxy - &xy'
97 * In version 5-8 files, some parts of the flags byte are ignored
99 * Only SixPack compressed and uncompressed files are supported
101 * `ADL': Westwood ADL File Format
103 * `AMD': AMUSIC Adlib Tracker by Elyssis
105 * `BAM': Bob's Adlib Music Format by Bob
107 * `CFF': BoomTracker 4.0 by CUD
109 * `CMF': Creative Music File Format by Creative Technology
111 * `D00': EdLib by Vibrants
112 * Bugs: Hard restart SR sometimes sounds wrong
114 * `DFM': Digital-FM by R.Verhaag
116 * `DMO': Twin TrackPlayer by TwinTeam
118 * `DRO': DOSBox Raw OPL Format
120 * `DTM': DeFy Adlib Tracker by DeFy
122 * `HSC': HSC Adlib Composer by Hannes Seifert, HSC-Tracker by
125 * `HSP': HSC Packed by Number Six / Aegis Corp.
127 * `IMF': Apogee IMF File Format by Apogee
129 * `KSM': Ken Silverman's Adlib Music Format by Ken Silverman
130 * Needs file `insts.dat' in the same directory as loaded file
132 * `LAA': LucasArts AdLib Audio File Format by LucasArts
133 * Bugs: Some volumes are a bit off
135 * `LDS': LOUDNESS Music Format by Andras Molnar
137 * `M': Ultima 6 Music Format by Origin
139 * `MAD': Mlat Adlib Tracker
141 * `MID': MIDI Audio File Format
143 * `MKJ': MKJamz by M \ K Productions *(preliminary)*
145 * `MSC': AdLib MSCplay
147 * `MTK': MPU-401 Trakker by SuBZeR0
149 * `RAD': Reality ADlib Tracker by Reality
151 * `RAW': RdosPlay RAW file format by RDOS
153 * `RIX': Softstar RIX OPL Music Format
155 * `ROL': AdLib Visual Composer by AdLib Inc.
156 * Needs file `standard.bnk' in the same directory as loaded file
158 * `S3M': Scream Tracker 3 by Future Crew
159 * Bugs: Extra Fine Slides (`EEx, FEx') & Fine Vibrato (`Uxy')
162 * `SA2': Surprise! Adlib Tracker 2 by Surprise! Productions
164 * `SAT': Surprise! Adlib Tracker by Surprise! Productions
166 * `SCI': Sierra's AdLib Audio File Format by Sierra On-Line Inc.
167 * Needs file `???patch.003' in the same directory as loaded
168 file, where ??? are the first 3 characters of the loaded
171 * Bugs: Some instruments are messed up
173 * `SNG': SNGPlay by BUGSY of OBSESSION
175 * `SNG': Faust Music Creator by FAUST
177 * `SNG': Adlib Tracker 1.0 by TJ
178 * Needs file `SONGNAME.ins' in the same directory as loaded
179 file, where SONGNAME is the song's filename without `.sng'
182 * `XAD': eXotic ADlib Format by Riven the Mage
184 * `XMS': XMS-Tracker by MaDoKaN/E.S.G
186 * `XSM': eXtra Simple Music by Davey W Taylor
188 Whenever a player requires more files to be present in a given
189 directory, be especially careful under UNIX systems, because all file
190 names are case-sensitive.
193 File: libadplug.info, Node: Concepts, Prev: Supported Formats, Up: Introduction
198 All of AdPlug's header files are installed under the directory `adplug'
199 inside your specified include path. Whenever a specific header file in
200 this manual is referred to, the filename with the path `adplug/'
203 AdPlug can be divided into 2 sections and 3 layers of functionality.
204 These are the "Playback" and "Sound generation" sections and the
205 "Frontend", "Mid-End" and "Backend" layers.
207 The Frontend layer is simply your application itself, using AdPlug.
208 It is above of it all and does not belong to any particular section.
209 Anything that provides the user-interface to AdPlug or an interface to
210 another application is in the Frontend layer.
215 * Sound generation section::
218 File: libadplug.info, Node: Playback section, Next: Sound generation section, Up: Concepts
220 1.2.1 Playback section
221 ----------------------
223 The Playback section is divided into the Mid-End and the Backend
224 layers. As a whole, it is responsible for making the sound files play
227 The Mid-End layer provides the glue between the Frontend and the
228 Backend layers. It provides methods and classes for these layers to
229 communicate. The headers `adplug.h', `fprovide.h', `players.h' and
230 `database.h' belong to the Mid-End layer. From your application's point
231 of view, you only have to include the file `adplug.h' in your source
232 files, which automatically includes all the other Mid-End headers.
234 The Backend layer is responsible for reading and decoding the sound
235 files into OPL command data. It then passes this data to the sound
236 generation section, which generates the final audio data. The header
237 `player.h' and all player header files belong to the Backend layer.
240 File: libadplug.info, Node: Sound generation section, Prev: Playback section, Up: Concepts
242 1.2.2 Sound generation section
243 ------------------------------
245 The Sound generation section is responsible for generating the OPL's
246 sound, according to the input of the Playback section. This sound is
247 either routed back to the application for it to do something with it or
248 routed directly to a specific audio hardware.
250 The following headers provide the interface to the sound generation
251 section: `emuopl.h', `temuopl.h', `kemuopl.h', `realopl.h',
252 `silentopl.h', `analopl.h' and `diskopl.h'. All classes inside these
253 headers are derived from the abstract base class `Copl', declared
254 inside the file `opl.h', which provides the common interface for the
255 Backend layer of the Playback section. This interface is not meant for
256 the Frontend layer (i.e. your application). Your application, however,
257 has to call special methods of these classes in order to route the data
258 back, if there is any.
260 `emuopl.h' provides the class `CEmuopl', which implements a virtual
261 OPL emulator, which automatically selects the best available OPL chip
262 emulation and type for each replayer.
264 `temuopl.h' provides the class `CTEmuopl', which is a wrapper class
265 around Tatsuyuki Satoh's fmopl OPL2 emulator, which generates wave
266 audio data to be routed back to the application.
268 `kemuopl.h' provides the class `CKemuopl', which is a wrapper class
269 around Ken Silverman's adlibemu OPL2 emulator, which generates wave
270 audio data to be routed back to the application.
272 `realopl.h' provides the class `CRealopl', which outputs to a real
273 hardware OPL2 or OPL3 chip. No data is routed back to the application.
274 This class is currently only working on x86 hardware.
276 `silentopl.h' provides the class `CSilentopl', which is a dummy
277 OPL2/3, which generates nothing. All data sent to it is forgotten
278 immediately. No data is routed back to the application.
280 `analopl.h' provides the class `CAnalopl', which is the same as `CRealopl',
281 but also provides a 9-channel loudness pseudo-analyzer interface for
282 the application. The loudness data is the only data routed back to the
285 `diskopl.h' provides the class `CDiskopl', which is an OPL3 emulator
286 that does not output any sound to the soundcard, but instead writes all
287 received OPL commands to a file in the RdosPlay RAW format.
290 File: libadplug.info, Node: Basic Usage, Next: Advanced Usage, Prev: Introduction, Up: Top
295 AdPlug provides convenience methods and classes inside its Mid-End
296 layer that make generic usage in your applications pretty easy. This is
297 most probably all that you need. For very advanced usage of particular
298 features of AdPlug, please refer to *note Advanced Usage::.
300 For basic usage, you need to include the header `adplug.h' inside
301 your application's source code. In addition, you need one of the
302 headers from the sound generation section, if you want sound output.
304 `adplug.h' provides the class `CAdPlug', which in turn provides the
305 load and playback facilities for the song files. `CAdPlug' is a static
306 class, you do not need to instantiate an object of it.
313 * Chip support selection::
314 * Getting Playback Information::
318 File: libadplug.info, Node: Loading, Next: Playback, Up: Basic Usage
323 To load a supported file for playback, you use the method
324 `CAdPlug::factory(const std::string &FILENAME, Copl *OPL, ...)'. The
325 method takes more arguments, but we don't need them for basic usage.
326 They are explained in *note Advanced Usage::.
328 The first argument, FILENAME, is a string object, containing the
329 filename of the sound file to be loaded with AdPlug. The second
330 argument, OPL, is a pointer to an already initialized object from the
331 sound generation section of the library.
333 The method returns a pointer to an initialized player object from the
334 Backend layer, or the NULL pointer if the file couldn't be loaded for
337 I guess FILENAME does not need any more explanation, so i will just
338 explain how to get an instance of a `Copl' derived class:
340 If you want to use the OPL emulator class `CEmuopl', you have to
341 include the header `emuopl.h' inside your application's source code.
342 `CEmuopl''s constructor looks like this: `CEmuopl::CEmuopl(int RATE,
343 bool BIT16, bool USESTEREO)'. The RATE argument specifies the playback
344 frequency rate in Hz. The BIT16 argument specifies whether to create 8
345 bit or 16 bit wave audio data. If it is set, 16 bit data is created.
346 The USESTEREO argument specifies whether to create stereo or mono audio
347 data. If it is set, stereo data is created.
349 If you want to use real hardware OPL2 output, you have to include the
350 header `realopl.h' inside your application and use the class
351 `CRealopl'. Its constructor just takes one optional argument,
352 specifying the hardware OPL2's base port, which is `0x388' by default.
353 As an option, you can include `analopl.h' instead, using the class
354 `CAnalopl', and also use the analyzer interface instead. This is
355 explained in *note Audio output::.
357 For no audio generation at all, include the header `silentopl.h'
358 inside your application and use the class `CSilentopl'. Its constructor
359 does not take any arguments.
362 File: libadplug.info, Node: Playback, Next: Audio output, Prev: Loading, Up: Basic Usage
367 On successful operation, `CAdPlug''s `factory()' method returns a
368 pointer to an initialized player object from the Backend layer. You use
369 this object to do the main song playback. The important methods for
372 `void seek(unsigned long ms)'
373 Use this to seek inside the song. The only argument specifies the
374 number of milliseconds to seek from the beginning of the song.
377 The most important method of them all. You have to call this
378 method in a loop. As long as it returns `true', the song has not
379 ended yet. At some point, it will start to always return `false'.
380 When it does this, the song has ended. The song will play on (and
381 is maybe already automatically rewound by the player itself), but
382 you should use the `rewind()' method to rewind it or stop playing.
384 `void rewind(int subsong = -1)'
385 This method rewinds the song to the beginning of the subsong,
386 specified by the only argument. If no argument or `-1' is given,
387 the currently selected subsong will be rewound. If the player does
388 not support subsongs, just don't provide an argument.
391 Returns a float containing the player object's idea of with what
392 frequency its `update()' method should be called, in Hz. This can
393 change at any time, so you have to poll it before every call to
396 `unsigned int getsubsongs()'
397 Returns the number of subsongs of the currently loaded song. If the
398 player doesn't support subsongs, `1' is returned, representing the
402 File: libadplug.info, Node: Audio output, Next: Chip support selection, Prev: Playback, Up: Basic Usage
407 To actually generate some sound, you probably additionally have to make
408 some calls to the OPL object. While the two hardware OPL2 output and
409 the silent OPL2 classes do not need any additional calls, the `CEmuopl'
410 class provides methods for your application's readback of the generated
413 To get a buffer of wave audio data from the emulator, you have to
414 call the `void CEmuopl::update(short *BUF, int SAMPLES)' method. The
415 BUF argument is a pointer to a previously allocated memory block of the
416 size specified by the SAMPLES argument, in samples. The method will
417 fill the specified amount of samples into the buffer. Multibyte samples
418 have the machine's byte ordering.
420 For easier and more uniform handling of the different OPL classes,
421 the `Copl' base class also provides the `update()' method. For
422 subclasses that do not support read back of the audio data (and for
423 which this is not necessary), the method is empty and does nothing.
425 The volume analyzing hardware OPL class `CAnalopl' also has some
426 data readback methods:
428 `int getcarriervol(unsigned int v)'
429 Returns the carrier's current volume of the OPL2 channel given as
432 `int getmodulatorvol(unsigned int v)'
433 Returns the modulator's current volume of the OPL2 channel given as
436 `bool getkeyon(unsigned int v)'
437 Returns whether a key-on event just happened on the OPL2 channel
438 given as the only argument.
441 File: libadplug.info, Node: Chip support selection, Next: Getting Playback Information, Prev: Audio output, Up: Basic Usage
443 2.4 Chip support selection
444 ==========================
446 With some OPL classes, like `CEmuopl' and `CRealopl', it is also
447 possible to select the chip type to support. The hardware OPL class
448 will of course only be able to support those chip types that are
449 available in the system. The emulated OPL class will be able to support
450 all chip types that it can emulate, provided the corresponding
451 emulators are compiled in.
453 Three different OPL chip configurations can be identified, which can
454 all be support by AdPlug.
456 * Single OPL2: This is the classic configuration found on the
457 standard AdLib boards. One OPL2 chip is supported.
459 * Dual OPL2: This configuration was first implemented on the Sound
460 Blaster Pro II boards. Two independant OPL2 chips are on this card.
462 * OPL3: This is the configuration found on all newer sound cards. An
463 OPL3 chip is supported, which is capable of emulating the other
466 In accordance to this, AdPlug's `Copl' base class defines the
467 enumeration type `ChipType', containing the items `TYPE_OPL2',
468 `TYPE_OPL3' and `TYPE_DUAL_OPL2'.
470 OPL classes supporting multiple OPL interfaces have the
471 `settype(TYPE)' method, which can be used to set the chip interface to
472 support, using the `ChipType' enumeration type.
474 The chip type needs not to be set, as all supporting classes
475 automatically set the best available chip type, they can support, but
476 you may like to provide your user with this selection to suite his
477 listenting preferences.
479 You may retrieve the currently supported chip type of a class by
480 using the method `Copl::gettype()', which returns a variable of type
481 `ChipType'. This method is defined in the `Copl' base class and thus
482 supported by all of the OPL classes.
485 File: libadplug.info, Node: Getting Playback Information, Next: Example, Prev: Chip support selection, Up: Basic Usage
487 2.5 Getting Playback Information
488 ================================
490 During playback, it is possible to gain some replay statistics with
491 some players. The following methods are for getting playback
494 `std::string gettype()'
495 Returns a descriptive string containing the current file's format
496 type. This is for user information only and cannot be interpreted
499 `std::string gettitle()'
500 Returns a string holding the current song's title. An empty string
501 is returned if the song's format does not support title
504 `std::string getauthor()'
505 Returns a string containing the current song's author name. An
506 empty string is returned if the song's format doesn't support
509 `std::string getdesc()'
510 Returns a string with the current song's description. An empty
511 string is returned if the song's format doesn't support a
514 `unsigned int getpatterns()'
515 Returns the number of patterns in the current song. `0' is
516 returned if the format isn't pattern-based.
518 `unsigned int getpattern()'
519 Returns the number of the currently playing pattern. `0' is
520 returned if the format isn't pattern-based.
522 `unsigned int getorders()'
523 Returns the length of the order list of the current song. `0' is
524 returned if the format doesn't have an order list.
526 `unsigned int getorder()'
527 Returns the number of the currently playing order list entry. `0'
528 is returned if the format doesn't have an order list.
530 `unsigned int getrow()'
531 Returns the number of the currently playing row inside the current
532 pattern. `0' is returned if the format isn't pattern-based.
534 `unsigned int getspeed()'
535 Returns the current speed setting of the song. `0' is returned if
536 the format doesn't support Protracker-based speed settings.
538 `unsinged int getinstruments()'
539 Returns the number of defined instruments in the song. This does
540 not necessarily mean that any of the defined instruments has an
541 instrument name attached to it. `0' is returned if the format
542 doesn't define any instruments.
544 `std::string getinstrument(unsigned int n)'
545 Returns a string with the name of the instrument, specified by the
546 only argument. If the specified instrument doesn't have a name, an
547 empty string is returned instead.
549 These methods may be called at any time on an initialized player
550 object (i.e. a file has already been loaded). If a player or song does
551 not support any of the above methods, or their values are not
552 meaningful for a format, reasonable bogus values are returned instead.
554 Some informational methods may not be called while the song itself is
555 playing because they change the internal replay state and will destroy
556 the running playback. These are:
558 `unsigned long songlength(int subsong = -1)'
559 This method returns the total length in milliseconds of the subsong
560 given as the only argument. If it is omitted or `-1', the
561 currently selected subsong's length will be returned.
564 File: libadplug.info, Node: Example, Prev: Getting Playback Information, Up: Basic Usage
569 This is an example of a minimal playback utility that reads the
570 filename to be played from the commandline, uses the emulator to
571 generate the sound and writes the raw wave audio data back to disk:
575 #include <adplug/adplug.h>
576 #include <adplug/emuopl.h>
578 #define RATE 44100 // Output frequency in Hz
579 #define BIT16 true // true when 16bit samples should be used
580 #define STEREO false // true when stereo samples should be used
581 #define BUFSIZE 512 // Sound buffer size in samples
583 bool play(const char *filename, const char *output)
585 * Main playback function. Returns true on successful playback.
586 * false is returned otherwise.
589 CEmuopl opl(RATE, BIT16, STEREO);
590 CPlayer *p = CAdPlug::factory(filename, &opl);
593 unsigned long towrite, write;
595 if(!p) return false; // File couldn't be loaded
597 f = fopen(output, "wb");
599 for(towrite = RATE / p->getrefresh(); towrite; towrite -= write) {
600 write = (towrite > BUFSIZE ? BUFSIZE : towrite);
601 opl.update(buf, write);
602 fwrite(buf, write, 2, f);
609 int main(int argc, char **argv)
612 cout << "usage: " << argv[0] << " <filename> <output>" << endl;
616 if(play(argv[1], argv[2]))
623 File: libadplug.info, Node: Advanced Usage, Next: Hacking, Prev: Basic Usage, Up: Top
628 This chapter explains very advanced usage of AdPlug. You do not
629 normally need to read this if you just want to write a usual frontend
630 application for AdPlug.
636 * Using the Database::
640 File: libadplug.info, Node: Player Lists, Next: File Providers, Up: Advanced Usage
645 There is another argument to the `CAdPlug::factory(const std::string
646 &fn, Copl *opl, const CPlayers &PL = players, ...)' method. The
647 argument PL is a reference to an object holding a "Player List".
649 A player list object is an instance of the `CPlayers' class (not to
650 be confused with the `CPlayer' class). The object can be constant and
651 even static (so it is possible to pass a temporary object, created on
654 The `CPlayers' class itself is not much more than a specialized
655 `std::list' from the STL, holding pointers to objects of type `CPlayerDesc',
656 which are explained below. Look into the STL documentation for more
657 information on `std::list' functionality.
659 The `CPlayerDesc' class is essentially an information-holder,
660 describing all needed characteristics of a player class, to create an
661 instance and load a supported file with it. It has two public
665 The `Factory' type defines a pointer to a static method inside a
666 class, inherited from `CPlayer', taking a pointer to a
667 `Copl'-derived object as the sole argument. The meaning of this
668 attribute is to provide a pointer to the factory method of the
669 player class, which takes a pointer to an initialized
670 `Copl'-derived object and returns a pointer to an initialized
671 instance of the same player class, this `CPlayerDesc' object
674 `std::string filetype'
675 This is a string containing the unique file type identifier of the
676 player class, this `CPlayerDesc' object describes. The string
677 normally contains the name of the file format, which the belonging
678 player class handles. This string should be unique.
680 In addition, `CPlayerDesc' has the following methods:
682 `CPlayerDesc(Factory f, const std::string &type, const char *ext)'
683 A specialized constructor, which initializes the whole object at
684 once. The first argument is the pointer to the factory method of
685 the accompanying player class. The second argument is a string
686 with the unique file type description, this player class handles.
687 The last argument is a pseudo ASCIIZ string, holding many ASCIIZ
688 strings with all file extensions to be associated with the
689 accompanying player class. To create such a string, include the
690 leading `.' with all file extensions and terminate any file
691 extension entry with a `\0' character. Concatenate all entries one
692 after the other, forming a string of strings. Terminate the last
693 entry with another `\0' character, so the final string is doubly
696 `void add_extension(const std::string &ext)'
697 Adds the single file extension, passed as the only argument, to the
698 list of file extensions, the accompanying player class handles.
700 `const char *get_extension(unsigned int n)'
701 Returns a pointer to the N-th file extension string in the file
702 extension list. If N is out of range, a `NULL'-pointer is returned
705 The `CPlayers' class itself adds two more methods to the inherited
706 `std::list' interface:
708 `const CPlayerDesc *lookup_filetype(const std::string &ftype)'
709 Returns a pointer to the first occurence of a `CPlayerDesc' object
710 with a file type of FTYPE, passed as the only argument. This
711 should also be the only object with that file type in the list. If
712 an object with the given file type is not found, a `NULL'-pointer
715 `const CPlayerDesc *lookup_extension(const std::string &extension)'
716 Returns a pointer to the first occurence of a `CPlayerDesc'
717 object, defining a file extension of EXTENSION, passed as the only
718 argument. Since file extensions are not necessarily unique in a
719 `CPlayers' list, it is often much more efficient to use the search
720 facilities provided by the STL. If no object, specifying the given
721 file extension, could be found, a `NULL'-pointer is returned
724 Thus, the `CPlayers' class holds a list of player descriptions. This
725 list is used by the `CAdPlug::factory()' method for the list of players
726 to try out on a given filename. If no list is passed to the method, it
727 is `CAdPlug::players' by default. This list always holds all players
728 compiled into the AdPlug library and is also your starting point for
729 generating lists of your own.
732 File: libadplug.info, Node: File Providers, Next: Using the Database, Prev: Player Lists, Up: Advanced Usage
737 "File Providers" are special classes that provide abstracted access to
738 files. AdPlug's player classes request files using a file provider, in
739 their `load()' methods. This system is necessary because some players
740 require multiple files in their load stage and these files cannot all
741 be passed to their `load()' method because the application's programmer
742 would have to be aware of each of the player's characteristics to know
745 A file provider class is derived from the abstract base class `CFileProvider',
746 which is declared in the header `fprovide.h'. This class defines the
749 `binistream *open(std::string) const'
750 An abstract virtual method that takes a string containing a
751 filename as the only argument and returns an initialized
752 input-only binary stream to that file. The stream is always
753 created with x86 capabilities (i.e. Little-Endian, IEEE-754
754 floating-point numbers). If the file could not be opened, the
755 `NULL'-pointer is returned instead.
757 `void close(binistream *) const'
758 An abstract virtual method that takes an input-only binary stream,
759 which was formerly created with the `open()' method, and closes
762 `bool extension(const std::string &filename, const std::string &extension)'
763 This static method takes a string holding a filename as its first
764 and another string holding a file extension as its last argument.
765 It does a caseless compare of the given file extension to the
766 extension of the given filename and returns `true' if they match.
767 `false' is returned otherwise.
769 `unsigned long filesize(binistream *f)'
770 This static method takes an input-only binary stream, previously
771 returned by the `open()' method, and returns the total size, in
772 bytes, of the associated file. The stream's state is not altered.
774 If you like to create your own file provider, you have to inherit
775 from this class and implement the methods `open()' and `close()'.
776 Remember to open the stream with x86 capabilites! One situation in
777 which you would have to create your own file provider is when your
778 application doesn't load the files from the machine's local filesystem.
779 For example, when it supports reading from archives, you would use your
780 file provider to fetch and depack the file from the archive first,
781 before passing it to AdPlug.
783 One derived file provider class is already defined in `fprovide.h': `CProvider_Filesystem'.
784 This file provider supports loading from the machine's local
785 filesystem. File names are normal paths in the operating system's
788 A file provider object can also be passed to the
789 `CAdPlug::factory()' method as last argument. If it is not provided, it
790 is a temporary instance of `CProvider_Filesystem' by default. The
791 method passes this object on to all player objects' `load()' methods,
792 it tries to open the file with. The player objects' `load()' methods
793 also take the file provider object as their last argument and default
794 to `CProvider_Filesystem' if none is given.
797 File: libadplug.info, Node: Using the Database, Next: Without CAdPlug, Prev: File Providers, Up: Advanced Usage
799 3.3 Using the Database
800 ======================
802 AdPlug recently features a full-blown database, specialized for storing
803 information relevant to the replay of AdLib-specific music data.
805 The database can be maintained by using the `adplugdb' command.
806 Usage of this command is explained in its own manual page.
808 The application's interface to the database is defined through the `CAdPlugDatabase'
809 class, residing in the header file `database.h'.
811 If you just want to pass a database for AdPlug to make use of it,
812 reading *note Usage with CAdPlug:: is sufficient. If you want to write a
813 complete database manipulation application, you have to read the other
818 * Usage with CAdPlug::
821 * Players using the Database::
825 File: libadplug.info, Node: Usage with CAdPlug, Next: Records, Up: Using the Database
827 3.3.1 Usage with CAdPlug
828 ------------------------
830 You can pass AdPlug a database for it to get specific information about
831 a file. Some file formats store insufficient information within
832 themselves and AdPlug uses the database to get the missing data. You do
833 not need to include any more header files other than `adplug.h' within
834 your application to do this.
836 To hand a database to AdPlug, you have to initialize an instance of
837 `CAdPlugDatabase' first. To do this, you just have to declare an object
838 of this class. This creates an empty database for you.
840 Additionally, for the database to be of any use to AdPlug, you have
841 to fill it with some records (see *note Records::). This is most
842 preferably done by loading an already existing database from a file. To
843 do this, you use the `load(std::string DB_NAME)' method of the class.
844 This will merge any records in the database file DB_NAME into your
845 database object. You can merge any more database files, if you wish.
846 Only new records will be merged. Duplicate records will be ignored.
848 To hand your database to AdPlug, you simply call
849 `CAdPlug::set_database(CAdPlugDatabase *db)' and pass a pointer to your
850 database object as the only argument. From now on, AdPlug will use your
851 database to do lookups for special information about some file types.
852 You have to keep your instance of the database until you close AdPlug
853 and free it by yourself after that.
856 File: libadplug.info, Node: Records, Next: Keys, Prev: Usage with CAdPlug, Up: Using the Database
861 "Records" are the primary data containers in the database. A record is
862 a very flexible object. It can store virtually any number of different
863 data types, you can think of.
865 All record classes are derived from the common abstract base class
866 `CAdPlugDatabase::CRecord'. All records have at least three common
870 Specifies what type of data this record holds. `RecordType' is an
871 enumeration variable with the following values:
874 This record doesn't store any more information than the three
878 This record additionally stores song name and author
882 This record additionally stores timer clock speed information.
885 This is the unique key, allocated for any record in the database.
888 `std::string filetype'
889 Holds the unique file type of the file associated with the record.
890 This value is taken from the player list (see *note Player
893 The common base class `CAdPlugDatabase::CRecord' defines a static
894 method `factory(RecordType type)' for application usage that returns a
895 pointer to a newly allocated `CRecord' object, or the `NULL'-pointer if
896 an error occured. You pass the type of the record to be created as the
899 All other public methods are meant for internal use of the database
900 only and should not be called from an application. They are explained
901 here anyway, for informational purposes:
903 `CRecord *factory(binistream &in)'
904 Another factory method that takes a reference to an input-only
905 binary stream as the only argument. It tries to extract a record
906 from the stream's current position, initializes a new record
907 object with the data and returns a pointer to that record object.
908 The `NULL'-pointer is returned if the record type couldn't be
909 determined from the stream's data.
911 `void write(binostream &out)'
912 Writes the record's contents to the output-only binary stream,
913 referenced by the only argument.
915 `bool user_read(std::istream &in, std::ostream &out)'
916 Attaches to the input and output streams, referenced by the first
917 and second arguments and tries to prompt an apparent user for the
920 `bool user_write(std::ostream &out)'
921 Attaches to the output stream, referenced by the only argument and
922 writes the record's contents in human-readable form to it.
924 `void read_own(binistream &in)'
925 `void write_own(binostream &out)'
926 `bool user_read_own(std::istream &in, std::ostream &out)'
927 `bool user_write_own(std::ostream &out)'
928 Abstract virtual base methods to be inherited by the real record
929 classes to read and write their own data, in both binary and
932 `unsigned long get_size()'
933 Abstract virtual base method to be inherited by the real record
934 classes to report the size of the extra data defined by them.
937 File: libadplug.info, Node: Keys, Next: Players using the Database, Prev: Records, Up: Using the Database
942 "Keys" are CRC32:CRC16 pairs that uniquely identify a file's contents
943 and are used to associate a record with a file. Only if the file's key
944 match with the record key, that record is actually used for that file.
946 Keys are stored in key objects, which are instances of the
947 `CAdPlugDatabase::CKey' class. The class has two attributes, `crc16'
948 and `crc32' which store the two CRC values, respectively. It also has
949 the following methods:
952 A constructor that creates an empty key object.
954 `CKey(binistream &in)'
955 A constructor that creates a key from the contents of the
956 input-only binary stream, referenced by the only argument.
958 `bool operator==(const CKey &key)'
959 Operator that compares two key objects and returns `true' when
960 they are equal. `false' is returned otherwise.
963 File: libadplug.info, Node: Players using the Database, Next: Direct Usage, Prev: Keys, Up: Using the Database
965 3.3.4 Players using the Database
966 --------------------------------
968 The following players make active use of the database:
971 The IMF player uses the database to find out about the timer clock
972 speed of a file, since this data is not stored in the file itself.
975 File: libadplug.info, Node: Direct Usage, Prev: Players using the Database, Up: Using the Database
980 The following methods are for application usage of the database:
982 `bool load(std::string db_name)'
983 `bool load(binistream &f)'
984 Two versions to load a database. The first method takes a string
985 containing a file name of a file from which the database is
986 loaded. The second method takes a reference to an input-only binary
987 stream to load the database from.
989 `bool save(std::string db_name)'
990 `bool save(binostream &f)'
991 Two versions to save the database. These work analogous to the
992 `load()' methods, above.
994 `bool insert(CRecord *record)'
995 Inserts the record object, pointed to by the only argument, into
996 the database and returns `true' on successful operation. `false'
997 is returned otherwise. Duplicate record entries (i.e. records that
998 have the same key) cannot be inserted into the database and old
999 ones will not automatically be overwritten by the new ones with
1000 this method. `false' is returned in this case.
1002 `void wipe(CRecord *record)'
1004 Two versions of a method to remove (wipe) a record from the
1005 database. The first version takes a pointer to a record object as
1006 the only argument and removes exactly this record from the
1007 database. The record object itself is deallocated, too. Do not
1008 reference it again! If the record object is not in the database,
1009 nothing is done. The second version removes the record at the
1010 current position in the database.
1012 `CRecord *search(CKey const &key)'
1013 Takes a reference to a key object, searches for a record with the
1014 same key value in the database and returns a pointer to this
1015 record. The `NULL'-pointer is returned if the record could not be
1018 `bool lookup(CKey const &key)'
1019 The same as `search()', but instead of returning a pointer to the
1020 record, it just positions the internal database pointer to the
1021 corresponding record. Returns `true' if the record could be found
1022 and `false' otherwise.
1024 `CRecord *get_record()'
1025 Returns a pointer to the record at the current position in the
1026 database. The `NULL'-pointer is returned if an error occured.
1029 Advances the internal position in the database by one record.
1030 Returns `true' on success, `false' otherwise.
1032 `bool go_backward()'
1033 The same as `go_forward()', but goes backward by one record.
1036 Goes to the beginning (i.e. the first record) of the database.
1039 Goes to the end (i.e. the last record) of the database.
1042 File: libadplug.info, Node: Without CAdPlug, Prev: Using the Database, Up: Advanced Usage
1047 It is also possible to only use specific players from the AdPlug
1048 library, without using the `CAdPlug' class to cycle through them all.
1050 If you just want to use a single player class from the library, you
1051 only include that player's header file in your application's source
1054 You can construct an instance of that player by either using its
1055 constructor or by using the `factory()' method of that class. Both have
1056 the same syntax and take a pointer to an initialized `Copl'-derived
1059 Use the player's `load()' method to load a file. It takes a filename
1060 as the first argument and, optionally, a file provider class as its
1063 All other methods have already been explained in the text above.
1066 File: libadplug.info, Node: Hacking, Next: Player development, Prev: Advanced Usage, Up: Top
1071 This chapter gives some coding guidelines for people wishing to hack
1072 around in AdPlug. Be sure to also read the overall and system-specific
1073 `INSTALL' files in the distribution's base directory to learn more
1074 about the build systems.
1082 File: libadplug.info, Node: Coding Style, Next: Debug Logging, Up: Hacking
1087 I do not really enforce any coding style guidelines (i don't adhere to
1088 any style guidelines myself, so... ;) ), but it would be nice if you
1089 follow the overall coding style, used throughout most of AdPlug's
1090 source files. If you don't, that's perfectly okay, too.
1092 Most of today's "super-intelligent" editors, like MSVC's one or GNU
1093 Emacs' cc-mode, have their own idea of what the code has to look like,
1094 anyway. And since most people tend to use these, there's no point in
1095 torturing them to always having to change anything their editor thinks
1099 File: libadplug.info, Node: Debug Logging, Prev: Coding Style, Up: Hacking
1104 AdPlug recently offers centralized debug log management. If you like to
1105 implement debug logging inside your code, please follow these
1108 To implement debug logging, `#include "debug.h"' in your code (this
1109 header is _not_ being installed with the rest of the AdPlug header
1110 files into your standard include directory! It is only available in
1111 AdPlug's `src/' subdirectory!).
1113 `debug.h' is C code, so it is useable from both C and C++ sources.
1114 The only function you have to use is the `LogWrite(fmt, ...)' function.
1115 `LogFile()' is used by AdPlug internally. `LogWrite()' works exactly
1116 like `printf()', instead that it writes to a logfile, rather than on
1119 Please format your log messages like this:
1121 * If your method/function is going to output a lot of debug info
1122 (i.e. more than one line), please put a `LogWrite()' directly at
1123 the beginning of your function, which looks like this:
1125 LogWrite("*** yourclass::yourmethod(PARAM1, PARAM2, ...) ***\n");
1127 And put the following line before every return from your function:
1129 LogWrite("--- yourclass::yourmethod ---\n");
1131 This way, one can easily inspect the logfile and know to which
1132 function every logfile-line belongs. The `***' lines mark the
1133 start of a function, and the `---' lines mark the end.
1135 Please substitute PARAM* with the corresponding parameter values
1136 of your function, if that is reasonable. For example, it won't help
1137 much to log a pointer value -- just put something bogus or helpful
1138 there, or noting (i.e. just a comma, so the logfile reader knows,
1139 to which parameters the other values correspond). But logging the
1140 values of passed ints or strings could be very helpful.
1142 * If your method/function is going to output just one line, format
1143 the line something like this:
1145 LogWrite("yourclass::yourmethod(PARAM1, PARAM2): your message\n");
1147 You don't need the `***' and `---' beginning and end markers then.
1149 * For threads, there is no way but to prefix any line with the
1150 function name, because these messages will be sprayed throughout
1154 File: libadplug.info, Node: Player development, Next: Protracker based players, Prev: Hacking, Up: Top
1156 5 Player development
1157 ********************
1159 Before you try to write a new player for AdPlug, be sure to also read
1160 through *note Hacking::.
1166 * Loading and File Providers::
1167 * Sound generation::
1170 File: libadplug.info, Node: Before the work, Next: Main work, Up: Player development
1175 Your player normally consists of two files (the `.h' & `.cpp' files)
1176 and you normally name them by the file extensions, your player handles.
1177 For example, the HSC player consists of the files `hsc.cpp' & `hsc.h',
1178 because it handles `.hsc' files. This is the same with your player
1179 class name. Thus, the HSC player's class is called `ChscPlayer'. If any
1180 of these names happens to be already taken for other purposes, just
1181 name your player something else, appropriately.
1183 `player.h' contains the abstract player interface. You have to
1184 include it in your player to communicate with AdPlug. It also contains
1185 some very helpful structures for use in your player. You don't need to
1186 use the structs, but you have to use the methods provided by the `opl'
1187 object (declared in `opl.h', but automatically included from
1188 `player.h') inside the player class to do the OPL I/O and
1189 initialization work.
1192 File: libadplug.info, Node: Main work, Next: Loading and File Providers, Prev: Before the work, Up: Player development
1197 All you have to do now is to inherit the `CPlayer' class into your own
1198 player class and fill the abstract methods with code. You at least have
1199 to fill in the following methods:
1201 bool load(const std::string &filename, const CFileProvider &fp);
1203 void rewind(int subsong);
1205 std::string gettype();
1207 The other methods from `CPlayer' just serve informational purposes
1208 (as does `gettype()', but it's required anyway) for AdPlug's info box
1209 and needn't to be filled. It would be nice if you fill them anyway, if
1210 that's reasonable for your player.
1212 There's one more public method you have to define in your player
1215 static CPlayer *factory(Copl *newopl);
1217 Since it is static, it isn't already virtually defined in the
1218 `CPlayer' class and you have to add it manually. This method should
1219 return a pointer to a freshly initialized object of your player class.
1220 If any errors occured (e.g. not enough memory), return `0' instead.
1222 Return true from your `load()' method, if the file was loaded
1223 successfully, or false if it couldn't be loaded for any reason (e.g.
1224 because AdPlug passed a wrong file to your player). Your `update()'
1225 method will be called with the frequency, you return from your
1226 `getrefresh()' method, in Hz. Return true from `update()' if your
1227 module hasn't ended yet. If it looped or ended, return false from that
1228 point, but play further for any subsequent calls to `update()'. AdPlug
1229 will rewind or stop your player by itself, using the `rewind()' method,
1232 AdPlug passes the number of the subsong, it wants to play next, to
1233 the `rewind()' method of your player. This can be any value from `0' to
1234 the value returned by `getsubsongs()'. If you haven't provided your own
1235 `getsubsongs()', AdPlug will presume your player doesn't have support
1236 for subsongs. In that case, AdPlug will always `rewind(0)'. Please
1237 ignore any value passed to `rewind()' that is out of spec for your
1238 player. This should virtually never happen, but who knows. If a value
1239 of `-1' is given as an argument, you should rewind the currently playing
1242 After initializing your player (either by a call to `factory()' or
1243 by creating an instance by itself), AdPlug normally first calls
1244 `load()' and then `getrefresh()' and `update()' in a loop until
1245 something happens (i.e. the user stops playback or the song ends).
1246 `rewind()' and all the informational methods can be called anytime in
1247 between the other calls, but of course only after `load()' has been
1250 You can add your own constructors, destructors and methods to your
1251 player object, as you like. AdPlug won't care in any way.
1254 File: libadplug.info, Node: Loading and File Providers, Next: Sound generation, Prev: Main work, Up: Player development
1256 5.3 Loading and File Providers
1257 ==============================
1259 The `load(const std::string &filename, const CFileProvider &fp)' method
1260 needs some special explanation. This method takes two arguments. The
1261 first is a reference to a string containing the filename of the main
1262 file for your player to load. This is the filename the user selected in
1263 the frontend (maybe altered by the frontend, but not by AdPlug) and
1264 does not need to have any meaning to your player.
1266 To finally load your files to get to their data, you have to request
1267 them. This is done through a "File Provider". A reference to a file
1268 provider is always passed as the second argument to your `load()'
1269 method. You will most likely want to load the file, using the filename
1270 passed as the first argument. To do this, you simply call `binistream
1271 *f = fp.open(filename)'. This method returns a pointer to an open,
1272 input-only binary stream of the requested file. You can now operate on
1273 this stream, using its standard interface (refer to the manual of the
1274 binary I/O stream class library for further information). When you're
1275 done loading your file, don't forget to call `fp.close(f)' to close it
1276 again. It is very important to do this anytime you leave your `load()'
1277 method! Any streams not closed will be left open for the whole lifetime
1278 of the controlling process!
1280 Don't worry about the passed filename. It normally doesn't need to
1281 have any meaning to your player. The file provider will know how and
1282 from where to open the file.
1284 `fp.open()' returns a null-pointer if something went wrong (e.g.
1285 file not found or access denied, etc.). If this happens, return `false'
1286 from your `load()' method immediately. You do not have to call
1287 `fp.close()' in this case.
1289 The `CFileProvider' class offers two convenience methods. These are
1290 `unsigned long filesize(binistream *f)' and `bool extension(const
1291 std::string &filename, const std::string &extension)'.
1293 `filesize()' returns the size in bytes of the stream, pointed to by
1294 `f', without altering it otherwise. `extension()' does a filename
1295 extension check as follows: The first argument is a reference to a
1296 string containing a filename. The second argument is a reference to a
1297 string containing a file extension to check for. If the passed filename
1298 has got exactly this extension (caselessly), the method returns `true'.
1299 `false' is returned otherwise.
1302 File: libadplug.info, Node: Sound generation, Prev: Loading and File Providers, Up: Player development
1304 5.4 Sound generation
1305 ====================
1307 You generate sound by using the `Copl::write(REG, VAL)' method of the
1308 `Copl' class, which has been passed to your constructor.
1310 REG is the number of the register of the OPL chip, you want to write
1311 data into. VAL is the value to write into it. There is no method to
1312 read back written data from an OPL chip, as this also was not possible
1313 with the original hardware. Log all data into an array if you have to
1314 remember written values.
1316 If your player supports the dual-OPL2 or OPL3 configurations, you can
1317 use the method `Copl::setchip(N)' to set the output chip number, all
1318 subsequent `write()' methods will write to. As two chips can be
1319 supported at maximum, the value of N may only be 0 or 1 for the first
1320 or the second chip, respectively.
1322 Before switching to another chip, your player always has to make sure
1323 that the configuration, you are going to address, is supported by the
1324 current OPL class. This can be done by calling the `Copl::gettype()'
1325 method, which will return the currently supported OPL chip type as an
1326 enumeration of type `Copl::ChipType'.
1328 If the desired configuration is not supported, your player should
1329 support playback on any of the other configurations. Your player should
1330 never switch to another OPL chip when this is not actually supported by
1331 the OPL class! The sound will be totally messed up.
1334 File: libadplug.info, Node: Protracker based players, Next: Copying This Manual, Prev: Player development, Up: Top
1336 6 Protracker based players
1337 **************************
1339 If you want to create a player for a Protracker-derivative format, the
1340 generic Protracker player `CmodPlayer' that comes with AdPlug can be of
1341 great help. It supports all standard Protracker features, plus a good
1342 set of extensions to cope with most derivative formats.
1344 When writing a player for a Protracker-derivative format, it is
1345 almost always better to use and extend the `CmodPlayer' class, instead
1346 of writing a whole new player.
1352 * Protracker Loaders::
1353 * Designing your Loader::
1354 * Loading Patterns::
1355 * Loading Instruments::
1357 * Special Arpeggio::
1360 File: libadplug.info, Node: Features, Next: Defaults, Up: Protracker based players
1365 In addition to handling your data just like the original Protracker
1366 would, AdPlug's generic Protracker player has the following extra
1369 * Special Arpeggio lists, compatible with the SA2 format.
1371 * Extendable set of up to 256 note commands.
1373 * Simulates many different tracker flavors.
1375 * Arbitrary numbers of rows, patterns, tracks, instruments and
1378 The only current limitation is that it has a maximum 9 voice
1379 polyphony, which isn't really a limitation, since the OPL2 is just 9
1383 File: libadplug.info, Node: Defaults, Next: Protracker Loaders, Prev: Features, Up: Protracker based players
1388 For historical reasons, `CmodPlayer' sets defaults to some values, so
1389 they need not be initialized. These are:
1391 * The orderlist is preallocated to 128 entries.
1393 * The patterndata is preinitialized to 64 patterns with 9 channels
1396 * The instruments array is preallocated to 250 instruments.
1398 * All flags are cleared (simulates Protracker flavor).
1400 These are mostly standard Protracker limits. They stem from the
1401 original SA2 defaults, for which this was once the player. Look at the
1402 `CmodPlayer' constructor for info on which variables are involved.
1405 File: libadplug.info, Node: Protracker Loaders, Next: Designing your Loader, Prev: Defaults, Up: Protracker based players
1407 6.3 Protracker Loaders
1408 ======================
1410 When you decided to extend the `CmodPlayer' class, instead of writing a
1411 whole new player, you do this by writing a loader for it. This is done
1412 very similarily to writing a unique player for AdPlug. Thus, reading
1413 the *note Player development:: chapter is recommended for this task,
1416 Instead of naming your player class `CxxxPlayer', you should name it
1417 `CxxxLoader' or something appropriate if the name is already taken. You
1418 then publicly inherit the `CmodPlayer' class and fill the missing
1419 methods with code. These are now:
1421 static CPlayer *factory(Copl *newopl);
1422 bool load(const std::string &filename, const CFileProvider &fp);
1424 std::string gettype();
1426 Plus maybe some (or all) of the other informational methods, listed
1427 in the *note Player development:: chapter. Refer also to that chapter to
1428 see what the above methods are about.
1431 File: libadplug.info, Node: Designing your Loader, Next: Loading Patterns, Prev: Protracker Loaders, Up: Protracker based players
1433 6.4 Designing your Loader
1434 =========================
1436 File validation and initial loading is the same as it would be with any
1437 other player. One speciality is that you have to call `rewind(0)'
1438 whenever you completely loaded a valid file. Don't call it when you
1439 just exit your loader because the file was invalid!
1441 The Protracker player needs at least an orderlist, the patterns and
1442 the instruments to function. Most of the time, you have to convert
1443 these between your file's ordering and `CmodPlayer''s internal
1444 ordering. Look in the file `protrack.cpp', `CmodPlayer''s actual
1445 sources, for a list on how these constructs are ordered internally.
1447 Also, please look up the *note Defaults:: section to see if you need
1448 to reallocate any of the defaults.
1450 There are some variables that you have automatically inherited with
1451 your new loader and that you have to set in order to tell the
1452 Protracker player something about your loaded module. These are the
1456 The orderlist length. When `CmodPlayer''s orderlist pointer equals
1457 or is bigger than this length, it is automatically wrapped around
1458 to `restartpos'. This variable has no default.
1461 Refer to *note Loading Patterns:: below on this one. This variable
1465 The restarting position in the orderlist, when `length' is
1466 exceeded. This variable has no default.
1469 A flag array, telling the player which channels in every pattern
1470 are actually active and to be played. The ordering of this
1471 variable is a bit awkward, so be careful! It is a 32-bit `unsigned
1472 long', holding the activeness of a channel in each of its bits,
1473 _starting at the highest order bit_. It can hold values for up to
1474 32 channels. So, to set channel 0 active, you have to set bit 31
1475 (counting from bit 0) to `1' and so on. Setting any bits for
1476 channels that are not defined has no effect. This variable
1477 defaults to all bits set to 1, meaning all channels are enabled.
1480 Initial protracker-compatible speed setting. This variable
1481 defaults to `6', the standard Protracker speed setting.
1484 Initial protracker-compatible bpm (sometimes called tempo)
1485 setting. This variable has no default.
1488 Refer to *note Special Flags:: below. This variable defaults to
1489 `Standard', which sets standard Protracker defaults and imposes no
1493 The number of patterns in your module. You don't need to set this
1494 value. If you leave it at `0', `CmodPlayer' will automatically
1495 determine the number of _accessed_ patterns (which need not be the
1496 same as the actual number of patterns in your module) from the
1497 orderlist, in the `rewind()' method. The value serves only
1498 informational purposes, anyway. It is not needed for the actual
1499 playback. If you think you know better than `CmodPlayer', feel
1500 free to set it to something else and `CmodPlayer' won't touch it
1501 anymore and display your value instead. This variable defaults to
1505 File: libadplug.info, Node: Loading Patterns, Next: Loading Instruments, Prev: Designing your Loader, Up: Protracker based players
1507 6.5 Loading Patterns
1508 ====================
1510 AdPlug's Protracker player stores the tracks (or channels, as some may
1511 call them), that make up a pattern, in a way that makes it possible for
1512 you to reorder and reuse them in an easy way. This also makes storing
1513 patterns in the classic way a bit awkward.
1515 If you just want to store your tracks the classic Protracker way
1516 (usually the case), first use the `CmodPlayer::init_trackord()' method
1517 to do an initial setup. Then store your tracks in a sequential manner,
1518 counting from 0, in the `tracks' array. That is, for the first 9
1519 channels of your first pattern, use `tracks[0..9]'. The second
1520 dimension of this array holds the rows of each channel. For the next 9
1521 channels, you use `tracks[10..19]', and so on.
1523 If you want to make use of the reorder/reuse feature of the
1524 `trackord' array, please refer to the `sa2.cpp' source file. This
1525 player utilizes this method. Basically, the `trackord' array tells the
1526 player which track out of the `tracks' array it has to insert for each
1527 of the 9 tracks of a pattern. Thus, the first dimension of this array
1528 stands for the corresponding pattern and the next dimension holds the
1529 entries for all the 9 tracks.
1531 `CmodPlayer' orders its note data, in the `Tracks' struct, the
1534 `note' holds the note value. A value of `0' means `no note'. A value
1535 of `127' means `key off'. Values from `1' to `96' are actual notes to
1536 be played. Everything else is ignored. The octaves are encoded with the
1537 actual note values. Thus, notes from `1' to `12' are the 12
1538 halftone-steps of the first, lowest octave, `13' to `24' are those of
1539 the next lowest octave, and so on. Refer to the source code to see which
1540 frequencies are actually associated with the note values.
1542 `inst' holds the instrument to be played with this note. Again, a
1543 `0' value means no instrument is associated with this note and the last
1544 active instrument is taken instead. Otherwise, the instrument with the
1545 number `inst' minus 1 is fetched from the `inst' array (it's 0 based).
1547 `command' holds the command to be issued with this note. All
1548 available commands are listed in the following table:
1550 Value Command description Parameters Range
1551 ----------------------------------------------------------------------------------------
1552 ` 0xy' Arpeggio `xy'=1st note,2nd note `[0-F]'
1553 ` 1xx' Frequency slide up `xx'=sliding speed `[0-FF]'
1554 ` 2xx' Frequency slide down `xx'=sliding speed `[0-FF]'
1555 ` 3xx' Tone portamento `xx'=sliding speed `[0-FF]'
1556 ` 4xy' Vibrato `xx'=speed,depth `[0-F]'
1557 ` 5xy' Tone portamento & volume slide `xy'=vol up|vol down `[0-FF]'
1558 ` 6xy' Vibrato & volume slide `xy'=vol up|vol down `[0-FF]'
1559 ` 7xx' Set tempo `xx'=new tempo `[0-FF]'
1560 ` 8--' Release sustaining note
1561 ` 9xy' Set carrier/modulator volume `xy'=car vol|mod vol `[0-F]'
1562 ` 10xy' SA2 volume slide `xy'=vol up|vol down `[0-F]'
1563 ` 11xx' Position jump `xx'=new position `[0-FF]'
1564 ` 12xx' Set carr. & mod. volume `xx'=new volume `[0-3F]'
1565 ` 13xx' Pattern break `xx'=new row `[0-FF]'
1566 ` 14??' Extended command:
1567 ` 0y' Set chip tremolo `y'=new depth `[0-1]'
1568 ` 1y' Set chip vibrato `y'=new depth `[0-1]'
1569 ` 3y' Retrig note `y'=retrig speed `[0-F]'
1570 ` 4y' Fine volume slide up `y'=vol up `[0-F]'
1571 ` 5y' Fine volume slide down `y'=vol down `[0-F]'
1572 ` 6y' Fine frequency slide up `y'=freq up `[0-F]'
1573 ` 7y' Fine frequency slide down `y'=freq down `[0-F]'
1574 ` 8y' Pattern delay (rows) `y'=rows to delay `[0-F]'
1575 ` 15xx' SA2 set speed `xx'=new speed `[0-FF]'
1576 ` 16xy' AMD volume slide `xy'=vol up|vol down `[0-F]'
1577 ` 17xx' Set instrument volume `xx'=new volume `[0-3F]'
1578 ` 18xx' AMD set speed `xx'=new speed `[0-FF]'
1579 ` 19xx' RAD set speed `xx'=new speed `[0-FF]'
1580 ` 20xx' RAD volume slide `xx'=vol up/down `[0-FF]'
1581 ` 21xx' Set modulator volume `xx'=new volume `[0-3F]'
1582 ` 22xx' Set carrier volume `xx'=new volume `[0-3F]'
1583 ` 23xx' Fine frequency slide up `xx'=freq up `[0-FF]'
1584 ` 24xx' Fine frequency slide down `xx'=freq down `[0-FF]'
1585 ` 25xy' Set carrier/modulator waveform `xy'=carr wav|mod wav `[0-3,F]'
1586 ` 26xy' Volume slide `xy'=vol up|vol down `[0-F]'
1587 ` 27xy' Set chip tremolo/vibrato `xy'=tr depth|vb depth `[0-1]'
1588 ` 28xy' DTM frequency slide `xy'=frames up|down `[0-F]'
1589 ` 29xx' Pattern delay (frames) `xx'=frames to delay `[0-FF]'
1590 `255--' No operation (NOP)
1592 The `param1' and `param2' variables hold the command's parameters.
1593 These are command-dependant. Refer to the table above to see what they
1594 do with each of the commands and their value ranges. An `xx' in the
1595 _Parameters_ column means that `param1' and `param2' form one 2-digit
1596 parameter, with `param1' being the leftmost decimal. Otherwise, `x'
1597 refers to `param1' and `y' to `param2'.
1600 File: libadplug.info, Node: Loading Instruments, Next: Special Flags, Prev: Loading Patterns, Up: Protracker based players
1602 6.6 Loading Instruments
1603 =======================
1605 For the instrument data, `CmodPlayer' stores it in the `inst[].data[]'
1606 array, in the following way:
1608 Index Operator Description Register
1609 --------------------------------------------------------------------------------
1610 0 Channel (Panning) / Feedback strength / Connection type `0xc0'
1611 1 Modulator Tremolo / Vibrato / Sustain / KSR / Multiple `0x20'
1612 2 Carrier Tremolo / Vibrato / Sustain / KSR / Multiple `0x23'
1613 3 Modulator Attack Rate / Decay Rate `0x60'
1614 4 Carrier Attack Rate / Decay Rate `0x63'
1615 5 Modulator Sustain Level / Release Rate `0x80'
1616 6 Carrier Sustain Level / Release Rate `0x83'
1617 7 Modulator Wave Select `0xe0'
1618 8 Carrier Wave Select `0xe3'
1619 9 Modulator Key scaling level / Operator output level `0x40'
1620 10 Carrier Key scaling level / Operator output level `0x43'
1622 There are three extensions to the standard instrument data. These are
1623 also stored within the `inst[]' array.
1625 1. The _Special Arpeggio_. This is explained in the *note Special
1626 Arpeggio:: section, below.
1628 2. The `slide' variable. This is a pre-slide value that is always
1629 added to the frequency of the note, whenever this instrument is to
1632 3. The `misc' variable. This is just the holder for the value of the
1633 0xbd register (i.e. the "drums'n'misc" register) of the OPL.
1636 File: libadplug.info, Node: Special Flags, Next: Special Arpeggio, Prev: Loading Instruments, Up: Protracker based players
1641 The `flags' variable holds special flags to change the behaviour of the
1645 Act like standard Protracker would. This is the default.
1648 Command parameters are decimal values, not hexadecimal. For split
1649 parameter commands (i.e. commands with two parameters, like
1650 `0xy'), this has no effect, since decimal values would be from `0'
1651 to `9', anyway. But commands that take both parameters as one
1652 value (i.e. like `1xx') now take values from `0' to `99' and
1653 handle them properly (i.e. decimal wrap-around is now at `9' to
1654 `10' and not at `F' to `10').
1657 Treat the files like _Faust Music Creator_ does. This tracker uses
1658 a different volume handling scheme. In standard Protracker, the
1659 volume is computed as follows:
1661 final volume = channel volume = instrument volume
1663 In _Faust Music Creator_, it is done like this:
1665 final volume = (channel volume + instrument volume) / 2
1668 This prevents the OPL key off/on toggle on every newly played
1669 note. Some trackers require it that way...
1672 Sets the player into OPL3 mode. Extended register settings of the
1673 OPL3 become effective and the player initializes the OPL chip to
1674 OPL3 mode. This has no effect if the hardware does not support OPL3
1675 features. Be careful to set panning information in register `0xc0'
1676 or else no sound will appear.
1679 Sets tremolo depth to 4.8dB upon each `rewind()'.
1682 Sets Vibrato depth to 14 cents upon each `rewind()'.
1685 Enables the OPL percussion mode.
1687 These flags can be set and unset at any time. To set a flag, just
1688 binary _OR_ it with the `flags' variable. Use the `enum Flags' data
1689 type, defined in the `CmodPlayer' class for this purpose.
1692 File: libadplug.info, Node: Special Arpeggio, Prev: Special Flags, Up: Protracker based players
1694 6.8 Special Arpeggio
1695 ====================
1697 To use the _Special Arpeggio_ facility, you have to initalize it first.
1698 Use the `init_specialarp()' method for this purpose. `CmodPlayer''s
1699 deconstructor automatically handles the deinit for you.
1701 The special arpeggio uses the 4 variables `arpstart', `arpspeed',
1702 `arppos' and `arpspdcnt' of the `Instrument' struct.
1704 [TODO: actually explain. Refer to sa2.[cpp,h] and the original SA2
1705 docs in the meantime. The following table summarizes the special
1708 Value Command description
1709 ----------------------------------
1710 `252' Set carr. & mod. volume
1711 `253' Release sustaining note
1713 `255' End of special arpeggio
1716 File: libadplug.info, Node: Copying This Manual, Next: Method Index, Prev: Protracker based players, Up: Top
1718 Appendix A Copying This Manual
1719 ******************************
1723 * GNU Free Documentation License:: License for copying this manual.
1726 File: libadplug.info, Node: GNU Free Documentation License, Up: Copying This Manual
1728 A.1 GNU Free Documentation License
1729 ==================================
1731 Version 1.1, March 2000
1733 Copyright (C) 2000 Free Software Foundation, Inc.
1734 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
1736 Everyone is permitted to copy and distribute verbatim copies
1737 of this license document, but changing it is not allowed.
1741 The purpose of this License is to make a manual, textbook, or other
1742 written document "free" in the sense of freedom: to assure everyone
1743 the effective freedom to copy and redistribute it, with or without
1744 modifying it, either commercially or noncommercially. Secondarily,
1745 this License preserves for the author and publisher a way to get
1746 credit for their work, while not being considered responsible for
1747 modifications made by others.
1749 This License is a kind of "copyleft", which means that derivative
1750 works of the document must themselves be free in the same sense.
1751 It complements the GNU General Public License, which is a copyleft
1752 license designed for free software.
1754 We have designed this License in order to use it for manuals for
1755 free software, because free software needs free documentation: a
1756 free program should come with manuals providing the same freedoms
1757 that the software does. But this License is not limited to
1758 software manuals; it can be used for any textual work, regardless
1759 of subject matter or whether it is published as a printed book.
1760 We recommend this License principally for works whose purpose is
1761 instruction or reference.
1763 1. APPLICABILITY AND DEFINITIONS
1765 This License applies to any manual or other work that contains a
1766 notice placed by the copyright holder saying it can be distributed
1767 under the terms of this License. The "Document", below, refers to
1768 any such manual or work. Any member of the public is a licensee,
1769 and is addressed as "you".
1771 A "Modified Version" of the Document means any work containing the
1772 Document or a portion of it, either copied verbatim, or with
1773 modifications and/or translated into another language.
1775 A "Secondary Section" is a named appendix or a front-matter
1776 section of the Document that deals exclusively with the
1777 relationship of the publishers or authors of the Document to the
1778 Document's overall subject (or to related matters) and contains
1779 nothing that could fall directly within that overall subject.
1780 (For example, if the Document is in part a textbook of
1781 mathematics, a Secondary Section may not explain any mathematics.)
1782 The relationship could be a matter of historical connection with
1783 the subject or with related matters, or of legal, commercial,
1784 philosophical, ethical or political position regarding them.
1786 The "Invariant Sections" are certain Secondary Sections whose
1787 titles are designated, as being those of Invariant Sections, in
1788 the notice that says that the Document is released under this
1791 The "Cover Texts" are certain short passages of text that are
1792 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
1793 that says that the Document is released under this License.
1795 A "Transparent" copy of the Document means a machine-readable copy,
1796 represented in a format whose specification is available to the
1797 general public, whose contents can be viewed and edited directly
1798 and straightforwardly with generic text editors or (for images
1799 composed of pixels) generic paint programs or (for drawings) some
1800 widely available drawing editor, and that is suitable for input to
1801 text formatters or for automatic translation to a variety of
1802 formats suitable for input to text formatters. A copy made in an
1803 otherwise Transparent file format whose markup has been designed
1804 to thwart or discourage subsequent modification by readers is not
1805 Transparent. A copy that is not "Transparent" is called "Opaque".
1807 Examples of suitable formats for Transparent copies include plain
1808 ASCII without markup, Texinfo input format, LaTeX input format,
1809 SGML or XML using a publicly available DTD, and
1810 standard-conforming simple HTML designed for human modification.
1811 Opaque formats include PostScript, PDF, proprietary formats that
1812 can be read and edited only by proprietary word processors, SGML
1813 or XML for which the DTD and/or processing tools are not generally
1814 available, and the machine-generated HTML produced by some word
1815 processors for output purposes only.
1817 The "Title Page" means, for a printed book, the title page itself,
1818 plus such following pages as are needed to hold, legibly, the
1819 material this License requires to appear in the title page. For
1820 works in formats which do not have any title page as such, "Title
1821 Page" means the text near the most prominent appearance of the
1822 work's title, preceding the beginning of the body of the text.
1826 You may copy and distribute the Document in any medium, either
1827 commercially or noncommercially, provided that this License, the
1828 copyright notices, and the license notice saying this License
1829 applies to the Document are reproduced in all copies, and that you
1830 add no other conditions whatsoever to those of this License. You
1831 may not use technical measures to obstruct or control the reading
1832 or further copying of the copies you make or distribute. However,
1833 you may accept compensation in exchange for copies. If you
1834 distribute a large enough number of copies you must also follow
1835 the conditions in section 3.
1837 You may also lend copies, under the same conditions stated above,
1838 and you may publicly display copies.
1840 3. COPYING IN QUANTITY
1842 If you publish printed copies of the Document numbering more than
1843 100, and the Document's license notice requires Cover Texts, you
1844 must enclose the copies in covers that carry, clearly and legibly,
1845 all these Cover Texts: Front-Cover Texts on the front cover, and
1846 Back-Cover Texts on the back cover. Both covers must also clearly
1847 and legibly identify you as the publisher of these copies. The
1848 front cover must present the full title with all words of the
1849 title equally prominent and visible. You may add other material
1850 on the covers in addition. Copying with changes limited to the
1851 covers, as long as they preserve the title of the Document and
1852 satisfy these conditions, can be treated as verbatim copying in
1855 If the required texts for either cover are too voluminous to fit
1856 legibly, you should put the first ones listed (as many as fit
1857 reasonably) on the actual cover, and continue the rest onto
1860 If you publish or distribute Opaque copies of the Document
1861 numbering more than 100, you must either include a
1862 machine-readable Transparent copy along with each Opaque copy, or
1863 state in or with each Opaque copy a publicly-accessible
1864 computer-network location containing a complete Transparent copy
1865 of the Document, free of added material, which the general
1866 network-using public has access to download anonymously at no
1867 charge using public-standard network protocols. If you use the
1868 latter option, you must take reasonably prudent steps, when you
1869 begin distribution of Opaque copies in quantity, to ensure that
1870 this Transparent copy will remain thus accessible at the stated
1871 location until at least one year after the last time you
1872 distribute an Opaque copy (directly or through your agents or
1873 retailers) of that edition to the public.
1875 It is requested, but not required, that you contact the authors of
1876 the Document well before redistributing any large number of
1877 copies, to give them a chance to provide you with an updated
1878 version of the Document.
1882 You may copy and distribute a Modified Version of the Document
1883 under the conditions of sections 2 and 3 above, provided that you
1884 release the Modified Version under precisely this License, with
1885 the Modified Version filling the role of the Document, thus
1886 licensing distribution and modification of the Modified Version to
1887 whoever possesses a copy of it. In addition, you must do these
1888 things in the Modified Version:
1890 A. Use in the Title Page (and on the covers, if any) a title
1891 distinct from that of the Document, and from those of
1892 previous versions (which should, if there were any, be listed
1893 in the History section of the Document). You may use the
1894 same title as a previous version if the original publisher of
1895 that version gives permission.
1897 B. List on the Title Page, as authors, one or more persons or
1898 entities responsible for authorship of the modifications in
1899 the Modified Version, together with at least five of the
1900 principal authors of the Document (all of its principal
1901 authors, if it has less than five).
1903 C. State on the Title page the name of the publisher of the
1904 Modified Version, as the publisher.
1906 D. Preserve all the copyright notices of the Document.
1908 E. Add an appropriate copyright notice for your modifications
1909 adjacent to the other copyright notices.
1911 F. Include, immediately after the copyright notices, a license
1912 notice giving the public permission to use the Modified
1913 Version under the terms of this License, in the form shown in
1916 G. Preserve in that license notice the full lists of Invariant
1917 Sections and required Cover Texts given in the Document's
1920 H. Include an unaltered copy of this License.
1922 I. Preserve the section entitled "History", and its title, and
1923 add to it an item stating at least the title, year, new
1924 authors, and publisher of the Modified Version as given on
1925 the Title Page. If there is no section entitled "History" in
1926 the Document, create one stating the title, year, authors,
1927 and publisher of the Document as given on its Title Page,
1928 then add an item describing the Modified Version as stated in
1929 the previous sentence.
1931 J. Preserve the network location, if any, given in the Document
1932 for public access to a Transparent copy of the Document, and
1933 likewise the network locations given in the Document for
1934 previous versions it was based on. These may be placed in
1935 the "History" section. You may omit a network location for a
1936 work that was published at least four years before the
1937 Document itself, or if the original publisher of the version
1938 it refers to gives permission.
1940 K. In any section entitled "Acknowledgments" or "Dedications",
1941 preserve the section's title, and preserve in the section all
1942 the substance and tone of each of the contributor
1943 acknowledgments and/or dedications given therein.
1945 L. Preserve all the Invariant Sections of the Document,
1946 unaltered in their text and in their titles. Section numbers
1947 or the equivalent are not considered part of the section
1950 M. Delete any section entitled "Endorsements". Such a section
1951 may not be included in the Modified Version.
1953 N. Do not retitle any existing section as "Endorsements" or to
1954 conflict in title with any Invariant Section.
1956 If the Modified Version includes new front-matter sections or
1957 appendices that qualify as Secondary Sections and contain no
1958 material copied from the Document, you may at your option
1959 designate some or all of these sections as invariant. To do this,
1960 add their titles to the list of Invariant Sections in the Modified
1961 Version's license notice. These titles must be distinct from any
1962 other section titles.
1964 You may add a section entitled "Endorsements", provided it contains
1965 nothing but endorsements of your Modified Version by various
1966 parties--for example, statements of peer review or that the text
1967 has been approved by an organization as the authoritative
1968 definition of a standard.
1970 You may add a passage of up to five words as a Front-Cover Text,
1971 and a passage of up to 25 words as a Back-Cover Text, to the end
1972 of the list of Cover Texts in the Modified Version. Only one
1973 passage of Front-Cover Text and one of Back-Cover Text may be
1974 added by (or through arrangements made by) any one entity. If the
1975 Document already includes a cover text for the same cover,
1976 previously added by you or by arrangement made by the same entity
1977 you are acting on behalf of, you may not add another; but you may
1978 replace the old one, on explicit permission from the previous
1979 publisher that added the old one.
1981 The author(s) and publisher(s) of the Document do not by this
1982 License give permission to use their names for publicity for or to
1983 assert or imply endorsement of any Modified Version.
1985 5. COMBINING DOCUMENTS
1987 You may combine the Document with other documents released under
1988 this License, under the terms defined in section 4 above for
1989 modified versions, provided that you include in the combination
1990 all of the Invariant Sections of all of the original documents,
1991 unmodified, and list them all as Invariant Sections of your
1992 combined work in its license notice.
1994 The combined work need only contain one copy of this License, and
1995 multiple identical Invariant Sections may be replaced with a single
1996 copy. If there are multiple Invariant Sections with the same name
1997 but different contents, make the title of each such section unique
1998 by adding at the end of it, in parentheses, the name of the
1999 original author or publisher of that section if known, or else a
2000 unique number. Make the same adjustment to the section titles in
2001 the list of Invariant Sections in the license notice of the
2004 In the combination, you must combine any sections entitled
2005 "History" in the various original documents, forming one section
2006 entitled "History"; likewise combine any sections entitled
2007 "Acknowledgments", and any sections entitled "Dedications". You
2008 must delete all sections entitled "Endorsements."
2010 6. COLLECTIONS OF DOCUMENTS
2012 You may make a collection consisting of the Document and other
2013 documents released under this License, and replace the individual
2014 copies of this License in the various documents with a single copy
2015 that is included in the collection, provided that you follow the
2016 rules of this License for verbatim copying of each of the
2017 documents in all other respects.
2019 You may extract a single document from such a collection, and
2020 distribute it individually under this License, provided you insert
2021 a copy of this License into the extracted document, and follow
2022 this License in all other respects regarding verbatim copying of
2025 7. AGGREGATION WITH INDEPENDENT WORKS
2027 A compilation of the Document or its derivatives with other
2028 separate and independent documents or works, in or on a volume of
2029 a storage or distribution medium, does not as a whole count as a
2030 Modified Version of the Document, provided no compilation
2031 copyright is claimed for the compilation. Such a compilation is
2032 called an "aggregate", and this License does not apply to the
2033 other self-contained works thus compiled with the Document, on
2034 account of their being thus compiled, if they are not themselves
2035 derivative works of the Document.
2037 If the Cover Text requirement of section 3 is applicable to these
2038 copies of the Document, then if the Document is less than one
2039 quarter of the entire aggregate, the Document's Cover Texts may be
2040 placed on covers that surround only the Document within the
2041 aggregate. Otherwise they must appear on covers around the whole
2046 Translation is considered a kind of modification, so you may
2047 distribute translations of the Document under the terms of section
2048 4. Replacing Invariant Sections with translations requires special
2049 permission from their copyright holders, but you may include
2050 translations of some or all Invariant Sections in addition to the
2051 original versions of these Invariant Sections. You may include a
2052 translation of this License provided that you also include the
2053 original English version of this License. In case of a
2054 disagreement between the translation and the original English
2055 version of this License, the original English version will prevail.
2059 You may not copy, modify, sublicense, or distribute the Document
2060 except as expressly provided for under this License. Any other
2061 attempt to copy, modify, sublicense or distribute the Document is
2062 void, and will automatically terminate your rights under this
2063 License. However, parties who have received copies, or rights,
2064 from you under this License will not have their licenses
2065 terminated so long as such parties remain in full compliance.
2067 10. FUTURE REVISIONS OF THIS LICENSE
2069 The Free Software Foundation may publish new, revised versions of
2070 the GNU Free Documentation License from time to time. Such new
2071 versions will be similar in spirit to the present version, but may
2072 differ in detail to address new problems or concerns. See
2073 `http://www.gnu.org/copyleft/'.
2075 Each version of the License is given a distinguishing version
2076 number. If the Document specifies that a particular numbered
2077 version of this License "or any later version" applies to it, you
2078 have the option of following the terms and conditions either of
2079 that specified version or of any later version that has been
2080 published (not as a draft) by the Free Software Foundation. If
2081 the Document does not specify a version number of this License,
2082 you may choose any version ever published (not as a draft) by the
2083 Free Software Foundation.
2085 A.1.1 ADDENDUM: How to use this License for your documents
2086 ----------------------------------------------------------
2088 To use this License in a document you have written, include a copy of
2089 the License in the document and put the following copyright and license
2090 notices just after the title page:
2092 Copyright (C) YEAR YOUR NAME.
2093 Permission is granted to copy, distribute and/or modify this document
2094 under the terms of the GNU Free Documentation License, Version 1.1
2095 or any later version published by the Free Software Foundation;
2096 with the Invariant Sections being LIST THEIR TITLES, with the
2097 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
2098 A copy of the license is included in the section entitled ``GNU
2099 Free Documentation License''.
2101 If you have no Invariant Sections, write "with no Invariant Sections"
2102 instead of saying which ones are invariant. If you have no Front-Cover
2103 Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
2104 LIST"; likewise for Back-Cover Texts.
2106 If your document contains nontrivial examples of program code, we
2107 recommend releasing these examples in parallel under your choice of
2108 free software license, such as the GNU General Public License, to
2109 permit their use in free software.
2112 File: libadplug.info, Node: Method Index, Next: Variable Index, Prev: Copying This Manual, Up: Top
2120 * binistream *open(std::string) const: File Providers. (line 18)
2121 * bool extension(const std::string &filename, const std::string &extension): File Providers.
2123 * bool getkeyon(unsigned int v): Audio output. (line 35)
2124 * bool go_backward(): Direct Usage. (line 58)
2125 * bool go_forward(): Direct Usage. (line 54)
2126 * bool insert(CRecord *record): Direct Usage. (line 20)
2127 * bool load(binistream &f): Direct Usage. (line 9)
2128 * bool load(std::string db_name): Direct Usage. (line 8)
2129 * bool lookup(CKey const &key): Direct Usage. (line 44)
2130 * bool operator==(const CKey &key): Keys. (line 22)
2131 * bool save(binostream &f): Direct Usage. (line 16)
2132 * bool save(std::string db_name): Direct Usage. (line 15)
2133 * bool update(): Playback. (line 15)
2134 * bool user_read(std::istream &in, std::ostream &out): Records.
2136 * bool user_read_own(std::istream &in, std::ostream &out): Records.
2138 * bool user_write(std::ostream &out): Records. (line 65)
2139 * bool user_write_own(std::ostream &out): Records. (line 72)
2140 * CKey(): Keys. (line 15)
2141 * CKey(binistream &in): Keys. (line 18)
2142 * const char *get_extension(unsigned int n): Player Lists. (line 61)
2143 * const CPlayerDesc *lookup_extension(const std::string &extension): Player Lists.
2145 * const CPlayerDesc *lookup_filetype(const std::string &ftype): Player Lists.
2147 * CPlayerDesc(Factory f, const std::string &type, const char *ext): Player Lists.
2149 * CRecord *factory(binistream &in): Records. (line 48)
2150 * CRecord *get_record(): Direct Usage. (line 50)
2151 * CRecord *search(CKey const &key): Direct Usage. (line 38)
2152 * float getrefresh(): Playback. (line 29)
2153 * int getcarriervol(unsigned int v): Audio output. (line 27)
2154 * int getmodulatorvol(unsigned int v): Audio output. (line 31)
2155 * std::string getauthor(): Getting Playback Information.
2157 * std::string getdesc(): Getting Playback Information.
2159 * std::string getinstrument(unsigned int n): Getting Playback Information.
2161 * std::string gettitle(): Getting Playback Information.
2163 * std::string gettype(): Getting Playback Information.
2165 * unsigned int getorder(): Getting Playback Information.
2167 * unsigned int getorders(): Getting Playback Information.
2169 * unsigned int getpattern(): Getting Playback Information.
2171 * unsigned int getpatterns(): Getting Playback Information.
2173 * unsigned int getrow(): Getting Playback Information.
2175 * unsigned int getspeed(): Getting Playback Information.
2177 * unsigned int getsubsongs(): Playback. (line 35)
2178 * unsigned long filesize(binistream *f): File Providers. (line 38)
2179 * unsigned long get_size(): Records. (line 77)
2180 * unsigned long songlength(int subsong = -1): Getting Playback Information.
2182 * unsinged int getinstruments(): Getting Playback Information.
2184 * void add_extension(const std::string &ext): Player Lists. (line 57)
2185 * void close(binistream *) const: File Providers. (line 26)
2186 * void goto_begin(): Direct Usage. (line 61)
2187 * void goto_end(): Direct Usage. (line 64)
2188 * void read_own(binistream &in): Records. (line 69)
2189 * void rewind(int subsong = -1): Playback. (line 23)
2190 * void seek(unsigned long ms): Playback. (line 11)
2191 * void wipe(): Direct Usage. (line 29)
2192 * void wipe(CRecord *record): Direct Usage. (line 28)
2193 * void write(binostream &out): Records. (line 56)
2194 * void write_own(binostream &out): Records. (line 70)
2197 File: libadplug.info, Node: Variable Index, Next: Class Index, Prev: Method Index, Up: Top
2205 * activechan: Designing your Loader.
2207 * bpm: Designing your Loader.
2209 * CKey key: Records. (line 29)
2210 * ClockSpeed: Records. (line 26)
2211 * Factory factory: Player Lists. (line 25)
2212 * flags: Designing your Loader.
2214 * initspeed: Designing your Loader.
2216 * length: Designing your Loader.
2218 * nop: Designing your Loader.
2220 * Plain: Records. (line 18)
2221 * RecordType type: Records. (line 14)
2222 * restartpos: Designing your Loader.
2224 * SongInfo: Records. (line 22)
2225 * std::string filetype <1>: Records. (line 33)
2226 * std::string filetype: Player Lists. (line 35)
2227 * trackord: Designing your Loader.
2231 File: libadplug.info, Node: Class Index, Prev: Variable Index, Up: Top
2239 * CAdPlug: Basic Usage. (line 15)
2240 * CAdPlugDatabase: Using the Database. (line 12)
2241 * CAnalopl: Sound generation section.
2243 * CDiskopl: Sound generation section.
2245 * CEmuopl: Sound generation section.
2247 * CFileProvider <1>: Loading and File Providers.
2249 * CFileProvider: File Providers. (line 14)
2250 * ChscPlayer: Before the work. (line 10)
2251 * CKemuopl: Sound generation section.
2253 * CmodPlayer: Protracker based players.
2255 * Copl: Sound generation section.
2257 * CPlayer <1>: Main work. (line 6)
2258 * CPlayer: Player Lists. (line 11)
2259 * CPlayerDesc: Player Lists. (line 16)
2260 * CPlayers: Player Lists. (line 10)
2261 * CProvider_Filesystem: File Providers. (line 52)
2262 * CRealopl: Sound generation section.
2264 * CRecord: Records. (line 40)
2265 * CSilentopl: Sound generation section.
2267 * CTEmuopl: Sound generation section.
2274 Node: Introduction
\7f2423
2275 Node: Supported Formats
\7f2890
2276 Node: Concepts
\7f6360
2277 Node: Playback section
\7f7202
2278 Node: Sound generation section
\7f8176
2279 Node: Basic Usage
\7f10547
2280 Node: Loading
\7f11471
2281 Node: Playback
\7f13483
2282 Node: Audio output
\7f15186
2283 Node: Chip support selection
\7f16786
2284 Node: Getting Playback Information
\7f18677
2285 Node: Example
\7f21855
2286 Node: Advanced Usage
\7f23372
2287 Node: Player Lists
\7f23748
2288 Node: File Providers
\7f28182
2289 Node: Using the Database
\7f31390
2290 Node: Usage with CAdPlug
\7f32296
2291 Node: Records
\7f33804
2293 Node: Players using the Database
\7f37860
2294 Node: Direct Usage
\7f38257
2295 Node: Without CAdPlug
\7f40939
2296 Node: Hacking
\7f41800
2297 Node: Coding Style
\7f42199
2298 Node: Debug Logging
\7f42881
2299 Node: Player development
\7f45158
2300 Node: Before the work
\7f45503
2301 Node: Main work
\7f46523
2302 Node: Loading and File Providers
\7f49346
2303 Node: Sound generation
\7f51848
2304 Node: Protracker based players
\7f53333
2305 Node: Features
\7f54119
2306 Node: Defaults
\7f54780
2307 Node: Protracker Loaders
\7f55510
2308 Node: Designing your Loader
\7f56569
2309 Node: Loading Patterns
\7f59798
2310 Node: Loading Instruments
\7f65734
2311 Node: Special Flags
\7f67544
2312 Node: Special Arpeggio
\7f69539
2313 Node: Copying This Manual
\7f70334
2314 Node: GNU Free Documentation License
\7f70592
2315 Node: Method Index
\7f90474
2316 Node: Variable Index
\7f96117
2317 Node: Class Index
\7f97948
projects / 16.git / blob