Resource Library: Multimedia

home *** CD-ROM | disk | FTP | other *** search

/ Resource Library: Multimedia / Resource Library: Multimedia.iso / utils / sound / convrtr / amiga / dstrck14 / dtl / dtlib.rdm next >

Wrap

Text File | 1992-10-01 | 22.1 KB | 482 lines

Documentation for the DES-Tracker Library system version 1.4 ============================================================ October 2, 1992 Written by Darren Schebek destracker.library, LScope, and DTC are all designed and written by Darren Schebek copyright (c)1992 by Darren Schebek All rights reserved INTRODUCTION ============ Programmers! Now you can have the great sound of Tracker music in your programs with a minimum of fuss and your program can still be user friendly and elegant in nature! Now you can have more control over syncing program events to music and have much more control over the music you play! Even ARexx programmers can make full use of the library's powerful features and ample status information! This is the DES-Tracker library system. The library does all the work for you and provides lots of helpful information about the song that's playing as well. This library system is NOT public domain. However, it is freely distributable as long as it is distrubuted unmodified and in it's entirety, which includes the following files: DTL/DTLib.ReadMe This file that you're reading now. DTL/ReadMe.Install How to install the library system. DTL/History.TXT A revision history of DES-Tracker. DTL/FAQ.TXT Frequently asked questions about DES-Tracker. DTL/libs/destracker.library The actual DES-Tracker library itself. DTL/libs/req.library Brand new (!) req.library v2.7! WB2.04-compat. DTL/c/DTC Lets you command the library from the CLI. DTL/c/LScope A visual scope example that runs in the B/G. DTL/c/LScope.info The .info file for the LScope program. DTL/docs/LibFuncs.DOC Docs for the library functions. DTL/docs/RexxFuncs.DOC Docs for the library's ARexx commands. DTL/docs/Structures.DOC Docs for the custom library structures. DTL/rexx/Jukebox.rexx A simple jukebox script example. DTL/rexx/Play.rexx A simple load and go script example. DTL/include/clib/dtlib_protos.h C prototype file DTL/include/pragmas/dtlib_pragmas.h C pragmas file for SAS/C. DTL/include/fd/dtlib.fd C function definition file. DTL/include/libraries/dtlib.i The include file for assembly language. DTL/include/libraries/dtlib.h The include file for C. DTL/include/proto/dtlib.h The main include file for C. You can use this library to your heart's desire, but if you use it for a commercial application, there is a fee. The fee is a complimentary copy of the final program. :) Of course, I'm also interested in non-commercial uses as well. If you pass this library system on to others, you must distribute the library package in its entirety (as previously mentioned) and each file must remain pristine (do not modify any of the files. Make copies for yourself and modify those instead). Lastly, you use the DES-Tracker library and included programs at your own risk. I assume no responsibility for any damage, data-loss, etc. that may be caused by DES-Tracker. Also note, however, that this version contains no known bugs. Here is a run-down of each file in this package: DTL/DTLib.ReadMe ---------------- This is the text file that you are now reading. DTL/ReadMe.Install ------------------ This text file simply mentions how to install the library system so that you can proceed to use it. It also mentions how you can order the source code to both the DTC program and the LScope visual library scope program. DTL/History.TXT --------------- This is a text file containing a revision history of the DES-Tracker library package, listing enhancements made for this version. DTL/FAQ.TXT ----------- This is a text file containing frequently asked questions about DES-Tracker. Answers are also included as a bonus. :) DTL/libs/destracker.library --------------------------- This is the actual library itself. The features of this library will be discussed later on, and is the main focus of the "LibFuncs.DOC" file. The library currently understands Noisetracker v2.0 format, Protracker v1.1a and up, and Soundtracker v2.6 format, and can read and write in both formats (the S/T v2.6 format is much more efficient than Noisetracker, BTW). I should also mention that the library also supports the Protracker extended "E" commands. DTL/libs/req.library -------------------- This is Colin Fox's requester library. Note that this is a BRAND NEW version of req.library (version 2.7). It includes bug fixes for WB2.04. It's totally cool. Spread this version of req.library far and wide. Give it to everybody you know, even if they don't have a computer! =u) DTL/c/DTC --------- A small program that you can use from a CLI window to feed commands to the library. This program is pure code. ie, it can be made resident using the "resident" command, or New WShell's "resi" command. This program is just over 4100 bytes in size (quite small). Due to the nature of libraries - they have a nasty tendency to be suddenly expunged whenever nobody is using them - it is best to first run the LScope program before using DTC. That way, LScope will keep the library open. DTC, when run, will open the library, give it the command(s) you specify, and then exit, closing the library. If DTC is the only user of the library, then, when DTC runs and finishes, the library is closed and expungable, and will be expunged if the Amiga decides that it needs the extra memory used by the library. With LScope running in the background, the library will remain open between calls to DTC. To get a list of the commands that DTC supports, just run DTC from the command line without any arguments. DTC supports multiple commands in a single invocation. Each command should be separated by a space character. For example, before, when you wanted to use DTC to reset the library defaults, load a tune (called HamsterDance, for instance) and then start the song playing, you had to type this: DTC rd (reset default playback parameters) DTC lm HamsterDance (load the song file called "HamsterDance") DTC bp ...Well now you can just type this: DTC rd lp HamsterDance (Reset defaults, then Load & Play "HamsterDance") ...which is much more economical. See the History.TXT file for details on changes made to DES-Tracker for this release. DTL/c/LScope ------------ A visual scope program example for the library system. You can run LScope from the CLI by typing "lscope" at the CLI prompt, or you can run it from a Workbench window by double-clicking on the LScope icon.This program serves two purposes. It is a great example of what you can do with the DES-Tracker library, and it's a useful tool for spying on the library to see what it's doing at any given time. LScope runs in the background, automatically giving you back your command-line prompt after you run it. The display runs at 60 frames per second with minimal use of CPU time. It is only around 15K bytes in length, and requires about 45K of memory total, including memory required for the display. The LScope program is completely system friendly, allowing you to do what ever you like (eg, modeming, programming, etc) at the same time that it is running. It took me all of two days to write it in assembly language. Version 1.2 of LScope looks pretty much the same as version 1.1, since the only changes made were bug fixes (well, bug *fix*, actually). LScope has not changed for this release of DES-Tracker. DTL/c/LScope.info ----------------- This is just the .info file for the LScope program so you can run LScope from a Workbench window. DTL/docs/LibFuncs.DOC --------------------- This text file contains documentation for each of the library's function calls. Handy dandy. :) DTL/docs/RexxFuncs.DOC ---------------------- This text file contains documentation for each of the library's ARexx function calls. There are just over 40 of them, mostly because I haven't yet implemented auto stem variable creation. Perhaps in a future release... DTL/docs/Structures.DOC ----------------------- This text file contains documentation on the custom library structures used by the DES-Tracker library, including the library base structure itself. DTL/rexx/Jukebox.rexx --------------------- A simple jukebox program written in ARexx. Plays all modules in the given path in a random order. DTL/rexx/Play.rexx ------------------ Another simple ARexx program. This one just loads up the specified module and starts it playing. Unlike the jukebox above, this program gives you back your command line prompt right away. Note that this ARexx program requires req.library. That's my excuse for including req.library in the DES-Tracker package. :) DTL/include/clib/dtlib_protos.h ------------------------------- This is the prototypes file. It is only needed for applications written in C. DTL/include/pragmas/dtlib_pragmas.h ----------------------------------- This is the pragmas file for use with SAS/C. DTL/include/fd/dtlib.fd ----------------------- This is the function definitions file used for creating pragmas. It is only needed for applications written in C. DTL/include/libraries/dtlib.i ----------------------------- This is the include file for assembly language applications. If you're writing an assembly language program that uses the DES-Tracker library, you will need to include this file. DTL/include/libraries/dtlib.h ----------------------------- This is the C version of the above include file. DTL/include/proto/dtlib.h ------------------------- This is the file you include if you're writing a C application that uses the DES-Tracker library. As well as defining the library base pointer, this file will also include dtlib_pragmas.h and dtlib_protos.h for you. Features of destracker.library ============================== Here is a brief list of the functions supported by the DES-Tracker library and what they do (a more detailed explanation of these functions can be found in both the LibFuncs.DOC and RexxFuncs.DOC file): Function Name: What it does: OwnPlayer Lock out other programs from using the library. DisownPlayer Allow others programs to use the library again. SetFilter Turn low-pass filter on/off (Amiga power light). SetChannelEnable Selectively enable/disable specific sound channels. SetStartPosition Set the position in a song at which to begin a play seq. SetEndPosition Set the position in a song at which to end a play seq. SetIterations Set the number of times to play a play sequence. PausePlaySeq Temporarily suspend an active play sequence. ContinuePlaySeq Resume a play seq. from the point at which it was paused. SetGlobalVolume Set the global volume that music will play at. SetInstVolume Set the default volume of a specific instrument. SetDefaultTempo Set default tempo for the beginning of a play sequence. SetGlobalTempo Set the global tempo for a song to play at. SetFineTempo Set the global fine tempo for a song to play at. SetTimingMode Set internal player timing to PAL (50Hz) or NTSC (60Hz). SetLoopIntent Set/clear flag for whether a song is meant to loop or not. FadeGlobalVolume Fade the global volume to a specific volume. SetVolumeFadeRate Set the speed at which volume fades transpire. LoadModule Load a song module into memory. UnloadModule Release a song module from memory. BeginPlaySeq Begin playing the predefined play sequence. VerifyModule Determine if a disk file is a recognizable module format. SetDefaultPath Set default path to use for file operations. RetitleModule Provide a new name for a module. ApplyGlobalTempo Permanently alter a module's global tempo. SetCurPosition Set the current play position in a loaded module. SaveModule Save a module back to disk in Soundtracker v2.6 format. SetSaveFormat Set format for SaveModule to use (Soundtracker/Noisetracker). SetAutoTiming Turn on/off auto timing detection (not available yet). ResetDefaults Reset library parameters to their default values. SetTempoInt Set tempo interpretation mode (BPM / Non-BPM). AddStatusSignal Add a status-change signal bit to library's signal queue. RemStatusSignal Remove a signal bit from library's signal queue. The above functions can be called from your own programs, regardless of what language you program in (providing that the language allows you to make calls to libraries, which is most likely). The exception is ARexx, but of course, the DES-Tracker library has full ARexx support as well. From looking at the above routines, it would appear that they are mostly input routines. That is, you give the functions input, but they don't yield any output, short of an error-status return code. Well, the DES-Tracker Library gives as well as takes. Read on... You open the library for use in the same way that you'd open the Dos library or Intuition Library (or any library, for that matter). When you open the DES-Tracker library successfully, you get back a pointer to the DES-Tracker library base structure. A pointer to the same instance of this structure is passed to all who open this library, and its elements are READ ONLY. You must never write to them. The "PSC0" Construct ==================== "PSC0" essentially means "Playback Status Construct". Future versions of this construct will have the name "PSC1", "PSC2", etc, so if you are scanning a file looking for this construct for your own purposes, you should only check for "PSC" and then check the fourth character for a valid digit. Whenever you tell the DES-Tracker library to save a song module back to disk (using the SaveModule function, see LibFuncs.DOC), the library will also append extra information about the song at the very end of the song file (it is put at the very end so you can still load the song up into the Soundtracker v2.6 or Noisetracker v2.0 editors). This information is contained in a PSC0 construct, a small block of data that looks like this: ULONG "PSC0" The PSC0 Identifier. ULONG size Size of the data portion of the PSC0 construct. UBYTE PBFlags Playback flags (see below) BYTE FineTempo Fine tempo setting (-128..127) UBYTE DefaultTempo Default tempo of the song (0..31). UBYTE Iterations Default number of iterations for song. The size field is the size of the entire PSC0 construct less the first two fields (ie, size is currently 4). The PBFlags field contains the following flags: Bit 7: PF_LOOPINTENT Set to 1 if this song is supposed to loop at the end (see Structures.DOC for an explanation of this flag as well as the SetLoopIntent function in LibFuncs.DOC). Bit 6: PF_TIMINGMODE Set to 0 for 60Hz (NTSC), 1 for 50Hz (PAL) timing. Bit 5: PF_TEMPOINT Set to 0 if song uses "BPM" (Beats Per Minute) tempo interpretation. Set to 1 if song only uses normal tempos in 1..255 range. The FineTempo field contains the fine tempo setting at the time that the song module was saved. Its range is -128..127. A value of 0 is the normal default. The DefaultTempo field contains the default tempo setting for when the song first starts playing. This is useful for songs that don't have any tempo commands in them (with songs like this, the ApplyGlobalTempo function won't work, see LibFuncs.DOC). You can use the SetDefaultTempo function to set this parameter prior to saving a module to disk. The last field was unused in versions 1.2 and earlier. It's function now is to hold the default number of iterations for the song. This is provided so that you can play a song from DTC and have it play a given number of times automatically. A value of 0 here means iterate infinitely. Note that if you are writing a jukebox program (for example) you can use the loop intent flag to override the number of iterations if you like. Or you can use the loop intent flag such that if it is clear, then play the song for the default number of iterations. If it is set, then play the song for the default number of iterations plus one extra iteration, and fade out on the last iteration. Now, when you tell the library to save a module to disk, a PSC0 construct automatically gets appended to the end of the song file. The next time you load up the song, the library will detect this PSC0 construct, extract the information from it and automatically set the respective parameters. Please bear in mind that if you load a module into the Soundtracker editor or Noisetracker editor and the song has a PSC0 construct at the end of it, the editor will throw away this information. So, if you save the song from the editor, the PSC0 construct will be lost. WHEW! ===== Having said all that, I hope you enjoy using this library system. I wrote the entire thing (DTC, LScope, the library itself) in 100% assembly language using Charlie Gibbs' a68k assembler. If you have any comments, criticisms, or suggestions (or just unbridled praise, ha ha), please let me know and help me to make this library system better and better. I'd also *really* like to see any programs you write that use the DES-Tracker library (a deluge of scopes? :). Have fun! SPECIAL THANKS ============== I must give special thanks to Colin Fox (of req.library fame, a good friend of mine for many years now) who helped me a great deal during the course of this project. Not only did he do most of the work in creating the C bindings (and at the last minute, no less), but he also drew the nifty little icon for the LScope program at great expense, and at the last minute. =u) Thanks, dude. Special thanks must also go to David Knox who brought a bug to my attention that occurred when DES-Tracker was used from within the Director II program. I would not have found them for quite some time otherwise. In return, I will give him a free plug. :) David is head of the "Ready Robot Club" headquartered in Carmichael, California. He publishes a monthly disk of educational games, stories and puzzles for kids from Kindergarten to Grade 6. He's been doing it for two years now, and has been mentioned in several magazines. If you would like information about the Club, his address is as follows: David Knox P.O. Box 628 Carmichael, CA 95609-0628 U.S.A. I feel I must also thank everybody who composes great Amiga tunes, as it was the excellent sound capabilities of the Amiga (and all these excellent tunes) that made me get an Amiga (I used to be an Atari ST owner, now it sits in the corner holding my door open). :) BTW, my current fave tunes are Klisje Paa Klisje (sp?), Heaven & Hell, and everything written by Maruku Buranu (aka Marc Brown, the man's a total Protracker Wizard, and his SampleText idea is brilliant). I wish I knew who wrote the first two tunes, but I thank them greatly for not stomping the instrument names in the module with inane comments. :) (Marc Brown: With the totally brilliant idea of using SampleText in your mods, *why* do you still trash the instrument names?). Also, kudos to Ed Mackey (Ed-Player looks great, I love the buttons), but I wish he wouldn't condone destroying instrument names in favor of author comments (couldn't people at least use the unused instrument slots for that kind of thing?) And I still don't know what the heck "Klisje Paa Klisje" means. :) WHAT'S IN STORE =============== - Amazing things are still in the works. Every once in a while, though, I will release a new version of DES-Tracker in the meantime, since people keep asking for more features, and I'm trying to design my amazing things. :) - Darren Schebek, October 2, 1992 NOTE: My usenet address is still dschebek@outb.wimsey.bc.ca as of this writing. I sure hope it doesn't bloody well change on me again... You can write to me here: or contact me on usenet at: Darren Schebek dschebek@outb.wimsey.bc.ca 5620 Sherwood Blvd. Delta, B.C. or call the Wizard BBS (my hangout): CANADA V4L-2C5 (604)322-3266 or (604)322-3972 (Sysop is Roger Earl)