@database Developer.guide @Author Jarkko Vatjus-Anttila @width 80 @$VER: BFBPlayMaster.library developer.guide v1.0 @node main "The BFBPlayMaster.library developer guide." The BFBPlayMaster.library developer guide v1.0 ---------------------------------------------- Legal: 1.1 @{" Introduction " link intro } Important text. Please read. 1.2 @{" Disclaimer " link disclaimer } Disclaimer. 1.3 @{" Copyrights " link copyrights } People involved in this project. 1.4 @{" Licence " link registration } Who may use freely and who not. Techical information: 2.1 @{" Requirements " link requirements } Hardware requirements. 2.2 @{" Features " link features } Build in features. 2.3 @{" Replayer notes " link notes } Notes about replayers. Other documents: 2.1 @{" BFBPlayMaster.guide " link BFBPlayMaster.guide/main } Autodocs for BFBPlayMaster.library 2.2 @{" BFBPlayXXXX.guide " link BFBPlayXXXX.guide/main } Autodocs for sublibraries. 2.3 @{" BFBPlayer.guide " link BFBPlayer.guide/main } Guide file for BFBPlayer. 2.4 @{" Tag items " link tags } Descriptions of the valid tagitems. 2.5 @{" Modinfo structure " link modinfo } Description about the modinfo structure. Other information: 3.1 @{" Registration " link registration } This is actually shareware. 3.2 @{" Bug reports " link bugreports } A bug report form. 3.3 @{" New replayers " link replayers } How to adapt new replayers. 3.4 @{" Thanks " link thanks } Who I want to thank. 3.5 @{" Author " link author } How to get in touch with me. 3.6 @{" BMOD " link BMOD } Introduction to new powerful module format! (c) 1996 by Jarkko Vatjus-Anttila (A BFB Team prodiction) @endnode @node intro "Introduction" Introduction ------------ Welcome to the finest multi-format-replay-library-system so far. Where did all this start from?? Well, when this project was started I wanted to build a multiformat library system and a powerful module replayer program to use these libraries. During the days I actually wrote code, my opinnions have changed and now my primary goal has been to develop an easy-to-use library system with developer material that everyone who may want to use these in his/ her own programs would be able to do so. The replayer program has been only my second program which you may notice by comparing it to other module replayers. Or to be more honest, the player has only been a tool for me to test the libraries. Still, I think it's good enough to release it and the libs as the User package and the documents, sources and libs as the developer package. I think I've reached my goals with this project. I made a multi format replayer library system, which is damn easy to use and I'm able to offer the developer material for you. Still after a huge amount of hours spent writing assembly code, I couldn't do this by myself. See the @{" thanks " link thanks } section for more details. :) I think it's now time to take a deep breath. :) I'm not forgetting this if someone thought that. I'll adapt replayers if I get them and keep updating the libs, but now when the hardest work is done, I'm sure I can be a bit more relaxed. I hope you find something for yourself, too, in these packages. And if you do, then please contact me. I'd be more than happy to hear your opinnions about this piece of work. Flames are accepted too. :) But, 'till then, bye... @{" Jarkko Vatjus-Anttila " link author } @endnode @node requirements "System and hardware requirements" HW Requirements --------------- There is no special requirements in using these libraries. Only THX sound system is meant to be used with mc68020 CPU or above, but if you try to use it in incompatible system, the library will inform you about it, so you don't need to worry about it. The libs work and have been tested under following machine configurations: A1200, mc68030, 68882, 2Mb Chip and 16Mb Fast. KickStart 3.0/3.1 A500, mc68000, 1/2Mb Chip and 1/2Mb Fast. KickStart 1.3 @endnode @node features "Feature list" Library Features: ----------------- BFBPlayMaster.library offers you following features to ease your work with it and the module files. - AutoLoading functions. You only pass the filename for the library and takes care of the choosing and allocation of the correct memory type. You only need to deal with one pointer, a pointer to moduleinfo structure. - All loading function calls are done with the taglists. Through a taglist you may specify loading methods like with the xpkmaster library. - If module type supports pagejump, pause/unpause or other misc options, the bfbplaymaster.library takes automaticly advantage over the features. You do NOT need to quess if the module type supports the options or not. Call the routine and it tells you if it's not available. - All module texts can be fetched with special @{" BFBGetSamplenames() " link bfbplaymaster,guide/bfbgetsamplenames } function. If the moduletype includes samplenames or other texts you get an access to them easily with this function. - You do not need to know what you are loading. BFBPlayMaster will tell you if the file is not a valid module. - Currently supportted module formats: 1) ProTracker 2) MED / OctaMED 3) QuadraComposer 4) The Player 6.0a 5) The Player 6.1a 6) David Whittaker 7) GMOD 8) DigiBooster 9) Oktalyzer 10) PSID 11) THX Sound-System 12) @{" BMOD " link bmod} If these features are not enough for you, then I'm surprised. When I wrote the program BFBPlayer (A multiformat moduleplayer that uses bfbplaymaster.library) I was happy to use such easy libraries. I can say that if you have had problems with modules before (for example with interrupts), these problems do not need to exist anymore. BFBPlayMaster.library is a very good sollution for this. @endnode @node bugreports "A bug report form" Bug reports: ------------ I've used days for just debugging but I' absolutely positive that these still are some left. If you notice one or more of these bastards, then please @{" contact me " link author }. When making a report, please fill the report form below and send it to me. If you have noticed the bug with a certain module file, then please send the module to me as well. Machine : CPU : FPU (if any) : Chip memory : Fast memory (if any) : TurboBoards (if any) : Other hardware : KickStart version : WorkBench version : How did the bug appear : How can I remake it : Here's an example report that I would make: Machine : Amiga 1200 CPU : mc68030 FPU : 68882 Chip memory : 2 Mb Fast memory : 16 Mb TurboBoards : A1230-III (Blizzard) Other hardware : no KickStart version : 39.106 WorkBench version : 39.29 How did the bug appear : Sometimes the BFBPlayer crashes to guru 80000004 How can I remake it : Just open the filerequster and quit right away it : and whole program. A Crash is certain. The problem descibed above is not real. Just my weird imagination. :) @endnode @node thanks "Thanks" I want to thank following people for the assitance in this project: Ville Helin : MEGA-Thanks for betatesting, example sources and : other misc help :) Kari-Pekka Koljonen : For some sources, help testing and commenting : my work and for invaluable help in my audio : related problems (like those CIA timers. This time : I do it right!!) Also thanks for the HippoPlayer, : the best moduleplayer around. Samu Nuojua : Thanks for making the best macro-assembler for : the amiga, SNMA. Without it, this wouldn't have : been possible. (BTW: SNMA is freeware and can be : found in aminet: @{"dev/asm/SNMA????.lha" link snma}) Replayer authors : Thanks for making the replayer sources. @{" Copyrights " link copyrights } @endnode @node copyrights "Copyrights:" People involved on this project: -------------------------------- See also @{" licence " link registration } A list of people who are involved in this project in someway or another: Tomasz Piasta : The author of the DigiBooster Jarno Paananen : The author of The Player 6.0a and 6.1a Bo Lincoln : The author of the QuadraCompser Teijo Kinnunen : The author of the MED / OctaMED Peter Hanning : The author of original ProTracker replayer routine. Bryan Ford : The author of the GMOD module structure A. Sander : The author of the Oktalyzer. Martin Wodok : The author of THX Sound-System. Håkan Sundell and Ron Birk : The authors of playsid.library Tuomas Lukinmaa : The author of @{" BMOD " link bmod } module format. Samu Nuojua : The author of my asm compiler @{" SNMA " link snma } Ville Helin : The betatester and author of some example sources. Jarkko Vatjus-Anttila : The author of bfbplaymaster.library, sublibs, : BFBPlayer, example sources, includes, autodocs : and documents. The copyrights belong to their respective owners, so you may not disassemble, modify or reverse engineer in any way these libraries. Some of the replayer sources are public domain, so if you want them then get them from aminet or ask me to send them to you, but remember to show some respect over the hard work. @endnode @node registration "Registration" Registration: ------------- What!! I thought this would be freeware!! Hold on. This is freeware. That shareware thing before meant that if you use these libs in your own programs, freeware, shareware or whatever-ware, then you have to send one free copy of your program for me. After doing it you may consider yourself as "registered" user of bfbplaymaster.library and are added to a list of people that receive the latest updates to the libs immediately after their release. I think that's not too much asked. That text above is only for NON-COMMERCIAL software writers only. If you want to use these libs to assist you in your COMMERCIAL project, then you are strongly engouraged to contact me. The usage of these libs is strictly forbidden without the written permission from the author himself. (That's me :) ) @{" Contact " link author} PD companies and similiars may add this package in its complete form to their libraries, CDROMs or whatever, but I'd be very happy to get a free copy of the disk where my work is included. @endnode @node replayers "New replayer libraries" How to adapt replayers. ----------------------- Well actually this is a bit though. :) I tried to make this replayer library system so flexible that there would be no problems but this one is quite kinky. First I thought that I'd put a ready library structure with this package that you could just write your replayer there and then use the library, but unless the master library is not updated, the sub library is quite silly to use. That's why I didn't include the library code in this package. Instead I encourage you to send me the possible new replayer sources and I'll adapt them in this library collection if possible. And if you send a new replayer source, it would be nice to see some test modules too. :) I hope this is the best sollution. I tried to think of something that is good for everyone. I hope I succeed. @endnode @node author "Author information" Author information: ------------------- Don't even think about hesitating if you need to reach me for some reason. Anything, questions, bug reports, problems, anything. I'm here. :) EMail: quaid@kempele.fi SMail: Jarkko Vatjus-Anttila Linnukkatie 2 http://www.kempele.fi/~quaid/ 90450 Kempele Finland @endnode @endnode @node disclaimer "DISCLAIMER" THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. @endnode @node snma "SNMA" Short: 680x0/6888x amiga macro assembler Type: dev/asm Author: snuojua@cc.helsinki.fi (Samu Nuojua) Uploader: snuojua@cc.helsinki.fi (Samu Nuojua) Replaces: snma-2.02.* SNMA is freeware conditional 680x0/688x macro assembler for the Amiga. It supports the most common directives, generates Amiga object-files and/or executables. It is used mainly from the shell. Arexx port. AmigaOS 2.0 and greater only. AmigaGuide docs only. This is version 2.03. New features in 2.x: - Options setting program, SnmaOpts - some minor changes and additions + bugs fixed Changes since 2.02: SNMA o One bug fixed from the option file loading, which caused random crash. o Bitfields can be defined like ",{o:w}". o Some movec problems disappeared (this one is little mysterious, since I didn't touch the whole movec thing). o In ARexx mode, snma could flag some addressing modes as invalid, because certain data structures had spurious values left from the previous assembly. o ARexx SET command works again. o In (BD,An,Xn) register equates, which started with z, were not recognized. o QUIET switch disables now all output to Output(). o If expression ended to operator, snma read one long from the address which was fetched from the string (one indirection too much). This could cause buserr exception in 68000, depending on value it read. o @ character is now normal symbol character, by default. @ character in the beginning of symbol meant octal number specifier. Since SAS/C uses it in the beginning of __regargs function names, its behaviour has been changed. Use OCT commandline toggle to allow octal numbers. There was also a bug, which caused no error telling in @symbol case, when it was actually coded as octal number - unsuccessfully. 2.02 fixes the following bugs since 2.00: SNMA o BSS sections didn't honor mem type bits. o Sometimes pc-relative addressing modes allowed small data references. (if small data references were allowed). o RTM was coded badly. o Forcing Base Displacement to word or long didn't work always. o " macro " finally works. SnmaOpts o Some checkbox gadgets were mixed with each other o If started from project icon, doesn't try to read project file as option file if it doesn't exist. @endnode @node notes "Notes about the replayers" @{b}Notes about the replayers:@{ub} -------------------------- When Writing programs depending on these replayer libraries you should be aware of following things about the libraries: (Some libraries don't exist in this list because they work exactly like descibed in the documents) - @{b}DigiBooster (bfbplayDIGI.library)@{ub} Nothing too important. After I received the v1.6 replay sources from the authors, all of the enforcer hits are vanished. This one works as should be. - @{b}MED / OctaMED (bfbplayMED!.library)@{ub} The library uses medplayer.library v2 to play back the modules, so make sure that it exist in your LIBS: drawer. And make sure it's te version 2!! - @{b}The Player 6.0a (bfbplayP60A.library)@{ub} When the module is started, there happens few enforcer hits but then they are gone. I know where the hits are coming but I don't know why. I'm trying to fix. - @{b}PlaySID (bfbplayPSID.library)@{ub} bfbplayPSID.library uses playsib.library 1.1 to play the PSID tunes. Make sure it exists in your LIBS: path. Due to a bug in the playsid.library it doesn't work with the KickStart 1.3. Make sure you check the kickstart version before using this library. - @{b}ProTracker (bfbplayPT20.library)@{ub} Used replaycode is from ProTracker 2.2, but although it has been almost completely rewritten, I don't know anything about the possible ProTracker 3.0+ commands. So if there exist any this replayer most likely isn't capable to play them. - @{b}THX sound system (bfbplayTHXS.library)@{ub} Needs 020+ CPU to play the tunes. The library checks for the CPU, so you cannot start playback if you don't have 020+ CPU. - @{b}TrackerPacker III (bfbplayTRP3.library)@{ub} Doesn't work at all when system is not turned off. It seems to be a cool replayer, but I'm not going to spend my time to debug it. Removed from library collection. @endnode @node tags "Tagitems" These are the tags that bfbplaymaster.library accepts. Input tags ---------- Input tags tell the bfbplaymaster.library what to do or how is the input data meant to be loaded. At least one of the input tags has to be defined or you get a "Taglist invalid!" error. If more than one moduletag or more than one sampletag is defined, only the first one has effect and the rest are ignored. BFBTAG_SongName (char *) Pointer to a null terminated string that is the filename of the requested module file. BFBTAG_SampleName (char *) Pointer to a null terminated string that is the filename of the requested sample file. (This is not supported by most module formats. Currently only P60A and P61A sublibs accept this tag.) BFBTAG_SongFH (BPTR) A filehandle of the requested module file. BFBTAG_SampleFH (BPTR) A filehandle of the requested sample file. BFBTAG_SongBuf UBYTE *) A pointer to buffer where the module is loaded by your application. Make sure that you've loaded the module into right kind of the memory and make also sure that you pass the tag BFBTAG_SongBufLen. BFBTAG_SampleBuf UBYTE *) A pointer to buffer where the samples are loaded by your application. Make sure that you've loaded the samples into right kind of the memory and make also sure that you pass the tag BFBTAG_SampleBufLen. Additional ---------- BFBTAG_ModInfo (APTR) ti_Data should point to a modinfo structure (see bfbplay.i). If the pointer is provided, the library automagically initializes the structure which may be then used for user's purposes. If the ti_Data contains NULL, then the structure is allocated for you by the master library. The pointer of the structure is saved in the ti_Data field and should be fetched from there right after any load function. Remember that when calling @{" BFBUnLoadModule " link BFBPlayMaster.guide/bfbunloadmodule } this structure is deallocated, no matter who allocated it in first place. This tag has to be defined *always*. BFBTAG_SongBufLen (LONG) Length of the module buffer. *Must* be defined if the BFBTAG_SongBuf is defined. BFBTAG_SampleBufLen (LONG) Length of the sample buffer. *Must* be defined if the BFBTAG_SampleBuf is defined. BFBTAG_Modtype (ULONG) A number specifying the moduletype. This tag has only effect when calling @{" BFBForceLoadModule " link BFBPlayMaster.guide/bfbforceloadmodule }. Otherwise it's ignored. @endnode @node modinfo "Description about the modinfo structure." This page describes the meaning of each field in structure modinfo. I've taken here the assembly language version of the structure, but the same fields can be found from the C version too. STRUCTURE modinfo,0 BYTE mi_moduletype BYTE mi_playflag - Mi_moduletype tells you the current module format. Each replayer has its own "code" and that code is stored here. The codes are described in the include files. - Mi_playflag tells you if the module is currently playing or not. If this field is non-zero, then the module is playing. APTR mi_bufferptr ; pointer to module buffer APTR mi_samplebufferptr ; pointer to sample buffer LONG mi_bufferlen LONG mi_samplebufferlen WORD mi_positions ; number of positions WORD mi_songs ; number of songs WORD mi_currentposition ; current position number WORD mi_currentsong ; current song number - Mi_bufferptr is the start address of the songdata buffer. - Mi_samplebufferptr is the corresponding address for separate sample buffer if there's one. - Mi_bufferlen and Mi_samplebufferlen tell you the length of the previously mentioned buffers. - Mi_positions is the number of positions in current module. If the amount cannot be calculated, this field is zero. - Mi_songs tells you the number of songs in this module. Because the count starts from 0, you have to add 1 to the value in this field if you want to get the real number of songs inside the module. For example, if this field contains number 5, then the amount of songs inside this module is 5+1=6. I use this method because it makes calculations easier inside the libraries. - Mi_currentposition and mi_currentsong tell you the current numbers of position and song. If these cannot be calculated, then the fields contain zero. ; ** Text fields. May be read and used as will. APTR mi_moduletypename ; Name of the current format APTR mi_modulename ; Name of the module or NULL LONG mi_modulenamelen ; maxlength of modulename in chars APTR mi_samplenamebuffer ; ptr to struct samplename LONG mi_samplenamebufferlen - Mi_moduletypename points to a null a terminated string that tells the current module format in words. - Mi_modulename is a pointer to the real module name if there exists one. Some modules support this, some don't. For example protracker has a name inside it. If the module doesn't have a name inside it, then this field is zero. - Mi_modulenamelen is the length of modulename in chars. This value is passed in case the real module name is not null terminated. First count the length of the modulename and then compare it to this value. If the result you got is bigger than the value in this field, then use this value instead. - Mi_samplenamebuffer points to a structure that holds to sample names of the current module. (in case there exists sample names of course). Note that a routine @{" BFBGetSampleNames " link bfbplaymaster.guide/bfbgetsamplenames } has to called before accessing this field. ; ** Private fields: Do NOT even think about touching. BYTE mi_paused BYTE mi_align01 APTR mi_tempbufferptr LONG mi_tempbufferlen LONG mi_interrupthandler - These fields don't need to be introduced, since they are private fields. You don't touch these! ; ** For possible future use. Shouldn't be used for anything. STRUCT mi_reserved,5*4 - And of course these has to be some space for future expansion. Don't store anything here! LABEL MI_SIZEOF @endnode @node bmod "BMOD Module format" BMOD ---- This package introduces a brand new module format, BMOD. This is a 100% ProTracker compatible module format that can be used in any application. Comparing to ProTracker, the BMOD is far more friendlier to the system and a lot more faster. With 030/50 the maximum raster time taken is about 1,5 raserlines. Yes, I said maximum. And if you like, the format offers even an opportunity to mutilate the modules so that they are impossible to rip from your application. Please see the "Goodies" subdirectory for a converter program to convert ProTracker modules into BMOD form and use the BFBPlayer to playback the tunes. However, remember that this is only a demoversion of BMOD. Severe bugs may still be there. Contact the author (Tuomas Lukinmaa ) for more details about the project. @endnode