@database Player50A.guide @node MAIN "The Player 5.0A" ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ ­ The Player ® 5.0A 503.1 / 20.05.93 ­ ­ Official prerelease! ­ ­ © 1992-93 Jarno Paananen ­ ­ Guru / Sahara Surfers ­ ­ A Sahara Surfers Product 1993 ­ ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ 1. @{" Foreword " link FOREWORD} 2. @{" Distribution and copyrights " link DISTRIBUTION} 3. @{" Requirements " link REQUIRES} 4. @{" Features " link FEATURES} 5. @{" The Converter " link CONVERTER} 6. @{" Using The Player in your own programs " link USING} 7. @{" The Usecode-system " link USECODE} 8. @{" Bugs? " link BUGS} 9. @{" Hellos " link HELLOS} 10. @{" Contact address " link CONTACT} @endnode @node FOREWORD "The Player® 5.0A: Foreword" 1. Foreword: ­­­­­­­­­­­­ This little utility was first made just for fun and to my own use. But when I noticed that there weren't a GOOD Protracker-compatible replay available and after I saw a few tries to fix this (ProPacker, Prorunner, etc.) I decided to give other people a chance to play their Protracker-tunes FAST! When designing the moduleformat, I also included packing and this 5.0 packing method is the most efficient I've seen for this purpose. I also made a converter to make it easier to use PT-modules. It uses Reqtools and Powerpacker libraries (both by Nico François) so it can also load Powerpacked modules. The converter is made as easy as possible to the user. @endnode @node DISTRIBUTION "The Player® 5.0A: Distribution and copyrights" 2. Distribution and copyrights: ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ This program and all other stuff coming in this package are FULLY copyrighted by Jarno Paananen / Guru of Sahara Surfers. ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ With the exception of Reqtools and Powerpacker libraries by Nico François (You have made a big favour to all programmers on the Amiga!) BUT!: ­­­­­ You're allowed to make additions or modifications or what so ever to fit the playroutine to your own needs. That's why the sources are here. But, please: credits for the author and a copy to myself, if possible, so I can add your new features to the future releases! A few words about distribution: This program is freeware. You can distribute it as long as _ALL_ files are included and not more than a nominal fee for copying is asked. This program can _NOT_ be used for commercial purposes without written permission from the author (and a few $$$ :). If you have suggestions or remarks about this program, or if you find any bugs, please let me know. @endnode @node REQUIRES "The Player® 5.0A: Requires" 3. Requirements: ­­­­­­­­­­­­­­­­ - An Amiga computer (NO CP-version coming :) - Req.library and Powerpacker.library - about 30 kB of memory for the converter, and if converting, 2 * number of patterns * 1kB + 1084 bytes for buffers - Works on 512kB machines, more memory recommended, at least for converting. - Kickstart 1.2 or greater. - Kickstart 2.0-style colors recommended (looks better) @endnode @node FEATURES "The Player® 5.0A: Features" 4. Features: ­­­­­­­­­­­­ - a very efficient method to pack the pattern data and play it in realtime - cut-down header compared to the original one (4 bytes info, 6 bytes/sample, 8 bytes/pattern, 1 byte/position plus one byte for stopmark) - removes all names, unused patterns, samples, data after loops, empty data after unlooped samples, commands with no use and some smaller things - nearly impossible to rip without finding the call to the init routine, except if the optional @{"`P50A`-sign" link PREFERENCES} is used - works on every Amiga, under KS1.2-3.0, from WB or CLI/Shell, detaches itself from CLI, supports WB icons, etc... Supports modules with 100 patterns (At least in PT2.x from Noxious) IF patterns are packed under 64kB in PASS 1... (pattern pointers are only words...) Commands implemented at the moment: - NoiseTracker 2.0 commands (0-6,A-F) - Tremolo (7), Sample offset (9), Fine slides (E1/E2), Set finetune (E5), Pattern loop (E6), Retrig note (E9), Fine volume slides (EA/EB), Note cut (EC), Note delay (ED), Pattern delay (EE) - of course finetune and now also tempo... NOTE!: Pattern loop was quite hard to be included, due to my packing system, but it should work if used "correctly" ie. only one E60-command per loop. Don't have to be on the same channel. Trying to fix it somehow. Some statistics: ­­­­­­­­­­­­­­­­ Original P50A NP3.0 NP2.02 ProPacker 1.0 Tune: ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ ( alcoholic score ) 121024 90222 93576* 104560* 108028 enigma year bkh-nhp 249550 206306 214148* 227770* 226326 knulla kuk !!! 160218 121924 128940* 138218* 147302 menuloader 23390 16976 17588 18292 20414 scrambled mind 163738 131656 132736 140614 148742 * = lacks some features (finetune, commands etc.) Obvious? @endnode @node CONVERTER "The Player® 5.0A: The Converter" 5. The Converter: ­­­­­­­­­­­­­­­­­ Note!: Do _NOT_ merge hunks in this file, because it uses two SEPERATE code hunks for detaching. If you do, it crashes straight away... Shell usage: P50con [-q][filename] -q Be quiet. The only way to stop playing is to give CTRL-C-signal to the DETACHED piece of code. Use TaskX or similar. filename to play. No checkings made (can't!), so be sure it IS a P50-module! WB usage is normal. Double clicking on a modules icon or click on module, shift and click on P50con to play it. 1. @{" Converting modules " link CONVERT} 2. @{" Playing modules " link PLAY} 3. @{" Preferences " link PREFERENCES} @endnode @node CONVERT "The Player® 5.0A: The Converter, Converting modules" 1. Converting modules: ­­­­­­­­­­­­­­­­­­­­­­ First a normal Reqtools filerequster asks you to select one or more (supports batch-processing) modules. If you select multiple modules, the directory for the modules to be saved is asked. Then loading with the Powerpacker library. If you chose one module, the name and path for the save are asked. As the packing starts, an info requester with some bars and statistics pops up. When the jobs is done, save and some statistics about the efficiency are shown. If you have converted only one module, also the @{"Usecode" link USECODE} is here. @endnode @node PLAY "The Player® 5.0A: The Converter, Playing modules" 2. Playing modules: ­­­­­­­­­­­­­­­­­­­ First the converter asks for a module (only one at the moment, a kind of jukebox is maybe coming as a separate program with also something else) and then loads it using the Powerpacker.library so it can also be packed with the Powerpacker :) After getting the load done, a requester is shown with the name of the file and a stop gadget below. The play routine is the system friendly tempo one, allocates channels with priority 127, a CIA-timer and returns if it couldn't get something. Should work with every system friendly program. To the guys at Triumph: I'd say this IS faster than yours and multitasks at least as well as your IntuiTracker 1.50 (I crashed it about x times...) and works on <2.0 Kickstarts, too. Anyway, this wasn't meant to be a kind of player like yours, but maybe one is coming (depends on effort and requests from outside). But I still prefer MultiPlayer... @endnode @node PREFERENCES "The Player® 5.0A: The Converter, Preferences" 3. Preferences: ­­­­­­­­­­­­­­­ Default loading directory: The directory converter first gives you, when you load Protracker modules. 127 chars. Default saving directory: The directory converter first gives you, when you save ONE P50 module. Default batch directory: The directory converter first gives you, when you save multiple P50 modules. Prefices: These are used to mask files in filerequesters and put to the beginning of the filename, when saving. Can be up to 7 chars long. Two files: If you want samples and rest of the tune to be saved in separate files. P50A sign: If you want the P50A sign to be inserted in the beginning of the module. No samples: If you're converting multiple modules with same samples, this disables the saving of samples. Tempo: Whether the player should use tempo or not. Icon: If you want the icon to be saved with the module. @endnode @node USING "The Player® 5.0A: Using The Player in your own programs" 6. Using The Player in your own programs: ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ NOTE: The instructions for the binaryfile-versions expect you to have loaded the file to a label called "Player" The versions are in the same file and these topics describe the various possible versions to compile the source. Also the binary versions have their instructions here. Completely PC-relative! 1. @{" Normal VBlank-version " link VBLANK} 2. @{" Non-lev6-version " link NONLEV6} (old one, new coming to the final version) 3. @{" CIA-version with tempo " link CIA} 4. @{" 68020-versions " link 68020} (under work, haven't tested yet!) 5. @{" Player.i " link INCLUDE} @endnode @node VBLANK "The Player® 5.0A: Using The Player in your own programs, VBlank" 1. Normal VBlank version: ­­­­­­­­­­­­­­­­­­­­­­­­­ Options: CIA = 0 system = 0 nonlev6 = 0 This should be easy for all you who've used the ugly Protracker routine or one of the millions of others. Call "P50_Init" with the address to the module in A0 and the address to the samples in A1 or if they are in the same file, clear A1 and finally the customchip base ($DFF000) in A6. Uses nearly all registers, so preserve them if you're going to use them afterwards. To play the music, call P50_Music every frame (with NTSCs who want to play the tune in PAL-speed or vice versa, use the @{"CIA" link CIA} version). To end the music and turn the DMAs off, call P50_End. With the binary file, P50_Init is Player+InitOffset, P50_Music is Player+ Music_Offset and P50_End is Player+EndOffset. The source-version can be compiled with at least Asm-One 1.15 by T.F.A. (the Best assembler around!) but it should compile with nearly any assembler. The maximum rastertime taken is under 6 lines on a normal 68000 Amiga. Fast? NOTE: Works perfectly on AGA- and turbomachines, due to the VBR-check. Am I the lonely one to check the VBR before banging the interrupt-vectors? @endnode @node NONLEV6 "The Player® 5.0A: Using The Player in your own programs, Non-lev6" 2. Non-lev6 version: ­­­­­­­­­­­­­­­­­­­­ Options: CIA = 0 system = 0 nonlev6 = 1 This routine is basically the same as the @{"lev6-version" link VBLANK}, but you have to call P50_Setloop about 7 raster lines after P50_Music. This system is done to enable the use of those 7 lines. So if have a routine, which fits to these 7 lines, do it while waiting... This is not too much slower compared to the lev6-version, but I'd still advise you to use it if possible. It makes your life a hell lot easier... @endnode @node CIA "The Player® 5.0A: Using The Player in your own programs, CIA" 3. CIA version with tempo: ­­­­­­­­­­­­­­­­­­­­­­­­­­ Options: CIA = 1 system = 0/1 nonlev6 = 0 The first tempoplayer I know, which uses only the lev6-int and does _NOT_ use those fucking processor loops. As fast as the normal @{"lev6-version" link VBLANK}! Otherwise normal init, but some info for the setting of CIA is needed in D0: 0 - Autodetect, if PAL/NTSC, uses ExecBase->VBlankFrequency. 1 - Force PAL. If you've destroyed the ExecBase, detect the screenmode yourself and use these force modes. 2 - Force NTSC No further actions needed. The player starts playing right away, so do _NOT_ call P50_Music. To end call the normal P50_End. To enable using of tempo, set P50_UseTempo to some non-zero value. If system is set to 1, allocations for timer and channels are included. Use if possible. NOTE: If you want to use this in your own program that needs synchronizing to the beam, use VBlank bit in INTREQR or use Copper to create a copper-interrupt and wait for it. Otherwise this WILL steal some frames from you time to time... @endnode @node 68020 "The Player® 5.0A: Using The Player in your own programs, 68020" 4. 68020-versions: ­­­­­­­­­­­­­­­­­­ Options: opt020 = 1 These are a bit optimized versions for the 020+ machines. The difference to the 000/010-versions is only a slight one and because those versions take only a half of a rasterline on a 25mhz A4000, I think these are nearly useless. But if you really want to make a 020+ program or AGA-only stuff, this is for you... Can be compiled at least with Asm-One 1.15 by T.F.A. The binary-interface is similar to the 000/010-versions. @endnode @node INCLUDE "The Player® 5.0A: Using The Player in your own programs, Player.i" 5. Player.i: ­­­­­­­­­­­­ This is the include file of all the structures needed, if you're going to compile the source. Also if you are making some additions to this player (like quadrascopes, etc. (these kind of things are maybe coming, I already have quite a bunch of 'em linked to this player)) you can look for the information there. First I was going to release this only as a binary version, but after thinking a few more moments, I decided to make this include file and release the source, just to make supporting and developing of this product possible. The module format is a secret, at least for some time, just to make making of a ripper harder. I of course have one myself... A feature to convert P50-modules back to Protracker-modules is MAYBE included sometime, if I get enough response to do so. So keep those letters coming... The routine is already done. @endnode @node USECODE "The Player® 5.0A: The Usecode-system" 7. The Usecode-system: ­­­­­­­­­­­­­­­­­­­­­­ This system was created for fun on a sunny afternoon. I got a crazy idea of putting a code of which features a module needs to the beginning of the source and let conditional compiling take care of the rest. The main idea is to reduce the lenght of this massive player to the real needs of the module. So only the commands the module needs are saved to the player. Also if the module doesn't use finetune, a smaller periodtable is used. And finally if the module doesn't use vibrato or tremolo, the 1kb-long vibratotable is left out. What you have to do is: Take down the Usecode shown in the requester after the converter has packed your module (if only one module is being processed) and put this code to the beginning of the source into the place for it. Compile and you have a customised version for this module only. Usecode -1 leaves all features ie. compiles the full version. for example: use = $9f0f @endnode @node BUGS "The Player® 5.0A: Bugs?" 8. Bugs?: ­­­­­­­­­ Some of you might still remember (in horror...) the previous versions of this marvelous :) player. Those 4.x-versions were all more or less beta-versions and that showed... (previous versions weren't even released, thank god..) This version has gone through quite a hell of beta-testing, by myself, my Good friends Janne Juhola (Simply/Parallax), Steffan Schumacher (Metal/Parallax), Kari-Pekka Koljonen (Moonstone/Hippopotamus Design), WDO/Carillon (never remember your name...Mikko?) and some others. Quite a lot of response (mostly negative...) has come from the 4.x-users like: - Juha Lainema: But you still used it! Any better available? This should be at least n+1 times better... - Jussi Hartzell (correct?): It was full of bugs, hope this isn't... Hope to see your game soon! - Comrade Z :) nice you tested this on your not so expanded Amiga. Mine has 3 megs of memory and a harddisk, so I couldn't figure out those problems with floppy disks and out of memory-errors... @endnode @node HELLOS "The Player® 5.0A: Hellos" 9. Hellos: ­­­­­­­­­­ A bit more hellos than in the converter to: (Some hellos to the beta-testers in @{"Bugs?" link BUGS}) To everyone using some version of this player: Hope to see you all at the Assembly'93 (coming?), the final version of this 5.0A will be released there (promise?). Unless I include some changes to the format, when it will be >5.0A... And hellos especially to: - Janne Oksanen / Stratos of Sahara Surfers - Lotsa thanks for da logo (in the about of the converter). The music disk will be great, if it ever gets ready... Same with the Game... - Kari-Pekka Koljonen / Moonstone of Hippopotamus Design - Great sendings (when coming...). Hope you'll be happy with this final version. Using beta-versions is no pleasure... - WDO of Carillon - Many thanks for the bugreport, even I had fixed them already. - Antti Mikkonen / Heatbeat of Carillon - Not heard from you for a long time. This is a Bit updated version compared to yours. Many thanks for the bugs found, I wouldn't have found them myself... Hope we still can continue our co-operation. - Someone of WDI (Decnite nowadays?) who sent me a disk a long time ago - I'm very sorry, but I lost ya address. Hope this one reaches you. - Stavros Fasoulas - Hi. Am I doing da game? nooo... at least not enough. Maybe when Stratos gets the GFX for your game done... @endnode @node CONTACT "The Player® 5.0A: Contact address" 10. Contact address: ­­­­­­­­­­­­­­­­­­­ I'm improving this utility for my own use (they made me release this!), but send me some $$$ (Finnish marks, please) or two disks with a return envelope WITH stamps and I'll send you the newest version (Mention which version you have, so I won't send the same version!) TO: (NO swapping!) J.Paananen Puskalantie 6 37120 Nokia Finland Or by phone: +358-31-3422147 / Jarno @endnode