컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 how to use the SCC Blaffer NT replay routine � 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� Date: September 19, 2001 at 21:10 ... Updates since version 1.00: v1.62 - Added CALL Z80 and CALL R800 Basic commands v1.61 - Improved SCC detection routine Basic drive loading bug fixed. v1.60 - Added DOS2 support v1.50 - Added Slot Expander support. v1.41 - Fixed little bug with ML support. v1.40 - Added ML support. v1.30 - Added the DOPSG override system (for sound effects while the music is playing) Added the STOPPSG command to stop the PSG SE (for infinite loops and stuff) v1.25 - Added PMV (PSG Maximum Volume) options v1.20 - Added fading routine ( _bntfade() ) v1.05 - No illegal function calls anymore (e.g. _bntstop while the music is stopped) v1.00 - First build 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Introduction 읕컴컴컴컴컴컴� The SCC-Blaffer NT replay routine (BNTPLAY.BIN) is made to play the music made with the SCC-Blaffer NT editor. The replay routine is written with both BASIC as also ML use in mind. Although ML users should find it slightly more difficult to use as BASIC users, because it takes a few things before the desired result is there. However, BASIC users should have no trouble whatsoever using the replay routine, as it is a call-based replayer... This document is splitted in two parts. The first part is only interesting for BASIC usage... The second part will give detailed information on how to use the replayer in ML. For both BASIC as ML users there's a little example program on how to use the replay routine. The source of the replay routine also is delivered with this package. As we use the TASM cross assembler, also this is delivered with the package, so ML users can compile the replay routine and the example program again. Although the documentation is splitted in 2 parts, ML users should read the BASIC usage part, simply because only in that part will be explained what all functions do... 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� BASIC usage � 컴컴컴컴컴컴켸 Starting the replayer... The replayer has to be loaded into memory (ofcourse). After that the call's have to be initialised... It's easy to do that... BASIC Users only have to type BLOAD "BNTPLAY.BIN",R... After that the replayer will be loaded into memory, and the call's will be initialised... To let everything go how it should you must protect a little bit memory located at $da00... That memory is used by the loading routines, and it will contain some information about the song while it plays. That information can be read by the BASIC user, therefore it will be explained at the end of this document. You can protect the memory by typing CLEAR 200,&hDA00... In this way we avoid BASIC using these addresses... Getting things to work... As the SCC works different then the MSX-AUDIO, MSX-MUSIC and the MoonSound, the replayer has to initialise the SCC... This is simply done by call InitSCC. After that you'll see a message... That message will show you if an SCC is detected, and also in which slot it is detected. If no SCC is detected, the message will show you that no SCC has been detected... Well, after that you have to load a song and an instrument kit to play it... This can be easely done by call SBKLoad ("BLAF_NT.SBK") and call SBMLoad ("SDCHURCH.SBM") (in this example we use one of SCC Blaffer NT delivered example songs)... When you've done that, you're ready to play... But first we'll show you how you're screen can look like... bload "BNTPLAY.BIN",r files (I don't know anyone who has a different prompt!) _InitSCC SCC Initialise successful (slot 2-0)... files _SBKLoad ("BLAF_NT.SBK") files _SBMLoad ("SDCHURCH.SBM") files Now you're ready to play the song... By typing _BNTPlay you'll get the desired result... After that the song plays! Well... This is how the routine works... Neat features: As SCC-Blaffer NT was designed to be a game-engine-tracker, we build in a feature to accomplish the perfect game-engine-tracker. By calling doPSG() you can play a PSG sound manually. The replayer stops playing the PSG sound, and starts playing your PSG sound. When the PSG sound is done, the replayer takes over again. This proves to be very useful for sound effects!! When you play a PSG sound that is trapped in an infinite loop, just call stopPSG and the replayer will take over again playing it's PSG sounds (usually drums). Another neat function is the BNTFade() routine. Call this when a music is playing to fade out the music. Other things: When a disk-error occurs a message + a little help will be shown. The message will contain what error occured. The help show's how to use the disk-routines. (For example if you type _SBMLoad ("123456789.123") the routine will show that the specified name is too long, as a filename may not be longer than 8 characters (excluding the extension which may be 3 characters ofcourse)). The following disk-errors can occur: Disk offline The drive does not contain a diskette. Disk I/O Error The routine cannot read from the disk, because it is broken or something like that... File not found The disk does not contain the file you tried to load... File not loaded The file on the disk is not complete... This ain't no song The header of the file does not contain the SCC Blaffer NT Song header... This ain't no instrument kit The header of the file does not contain the SCC Blaffer NT Instrument kit header... Unknown The disk-error that occurred is not known to SCC Blaffer Nt... Now you might say ok... This is pretty cool, but imagine I have a program, and I do not want to have those irritating messages because it looks strange... Well... We thought of that too... The command _BNTSilent disables all messages, so you can 'silently' use it in your program... And now you might say hey! But when my program loads a song or instrument kit, I would like to know whether it was loaded succesfully, cause else if I type _BNTPlay, you'll hear nothing but crap, and the replayer probably will hang! Well, we also thought of that! (ain't we cool??) When you try to load a song, you can test whether it was loaded successfully... When the file you tried to load is not loaded at all, the replay routine gives an error-code 100 back to BASIC. When it was successful, it will contain 0. So test it like this: ... 120 _BNTSilent 130 _SBMLoad ("TEST1.123") 140 IF ERR = 100 THEN PRINT "Song not loaded successfully!":END 150 _BNTPlay ... Ok... You now say, that's cool, but... I also would like to know whether the SCC was detected successful, and if it's possible in which slot it was detected... Also we thought of that. When no SCC was found an error-code 100 is returned, else an error-code 1 or 2 (depanding in which slot it was detected will be returned...) You can test this the same way as shown above... Well.. I think now you'll know everything what you need to know, so here's a list of all available commands: _SBKLoad ("[D:]FileName.Ext") Loads an instrument kit into memory [] means that it is optional...`" D - Drive name (max. 1 character)`" FileName - File name (max. 8 characters)`" Ext - File extension (max. 3 characters)``" When no drive is specified, the current drive will be used...`" _SBMLoad ("[D:]FileName.Ext") Loads a song into memory (see _SBKLoad for usage) _BNTPlay Starts playing the current loaded song. This option is only available when the music is *NOT* playing! _BNTStop Stops playing the current loaded song. This option is only available when the music is playing! _BNTHalt Pauses the playing song... This option is only available when the music is playing! _BNTCont Continues playing the paused song. This option is only available when the music is paused! _BNTFade () Fade out playing music. is the speed you want the music to be fading out. can be a number from 0 through 255, where 255 is the slowest. This option is only available when the music is playing! _doPSG () Manually override PSG system (for sound effects). is the PSG Instrument to be played. can be a number from 1 through 44. This option is only available when the music is playing! _stopPSG Stop the manual PSG override system and continue the original PSG sounds again. This option is only available when the music is playing! _PlayVer Displays the replayer version, and some info... _BNTSilent Disables all messages. _BNTLoud Enables all messages. _InitSCC Initialises SCC. This option is only available when the music is *NOT* playing! _FORCE () Where is the slot number you want the music to go through... can be a number from 1 through 2... This option is only available when the music is *NOT* playing! _SNGBank () Where is the memory bank you want your song to be stored... Default: 3. This option is only available when the music is *NOT* playing! _KITBank () Where is the memory bank you want your instrument kit to be stored... Default: 4. This option is only available when the music is *NOT* playing! _Z80 Switches CPU mode on MSX turbo R to Z80... _R800 Switches CPU mode on MSX turbo R to R800 DRAM... 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � ML Usage 읕컴컴컴컴� ML users can use all functions which BASIC users can use, but they also can set a few things which is not interesting for BASIC users. Although the usage in ML is more complicated as for BASIC users, it should not be a big problem. As the replay routine is a 'two in one', also the ML users must load the replayer in memory, and also initialize it. In BASIC you just could type bload "BNTPLAY.BIN",r. In ML you have to read the whole file and then execute it at its start-address. The replayer will automaticly store itself in another bank, so the memory that's used to load the replay routine in is available again when the replayer is loaded. First I'll explain some of the equates which can be found in the source file: RomBank : This equate contains the 'default' bank the replayer stores itself. Normally this is 2. (This can't be lower (for BASIC users) because bank 0 is used by the system, and bank 1 is used by the BASIC program (and if it's a large program it will also use a bit of bank 0)... SongBank : This equate contains the 'default' bank the song will be stored in. Normally this is 3. KitBank : This equate contains the 'default' bank the intrument kit will be stored in. Normally this is 4. SilentComp : This equate determines wheter the replayer should be compiled with the _BNTSilent and the _BNTLoud... If this equate equals 0, the replayer will be compiled with these options build in. Else the replayer will not compile these options, and the replayer will always be 'silent'... When using the replay routine in ML, the replayer always will be 'quiet'. So no messages will be shown at all... Even the messages shown in BASIC with the silent mode on now will not be shown. To use the replay routine in ML, you need some equates, which are stored in the file ML_MACNT.ASM. These equates will help you using the replay routine in ML. Also at the end of the file there's a little block of code, which will make a call to the actual replay routine, as the routine is stored in another map. You need this block of code in your own program to call the replayer... Take a look at ML_MACNT.ASM to see which equates I am talking about... After that take a look at ML_BNTPL.ASM for a little example program. This program does the same as the BASIC example program, it plays a song. I'm not going to explain all functions detailed. For the detailed information about them I refer to the info for BASIC users stated earlier in this document. To use the functions you need the file ML_MACNT.ASM as stated before. Then to call the replayer, just use 'BNTReplay()' in your program... The functions then: 旼컴쩡컴컴컴컴컫컴컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 쿙r.� Name � Description 쿔nformation � 쳐컴탠컴컴컴컴컵컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � 0 쿶nitSCC 쿔nitialize SCC 쿐rror code high/low if found, 100 if not � � 1 쿯orceMusic쿑orce Music 쿛arameter:�Slot number � � 2 쿞BMLoad 쿗oad SBM File 쿑ilename: 12 Bytes large block � � 3 쿞BKLoad 쿗oad SBK File 쿑ilename: 12 Bytes large block � � 4 쿍NTPlay 쿛lay Music 쿐rror code 102 if music is already playing � � 5 쿍NTStop 쿞top Music 쿐rror code 102 if music is already stopped � � 6 쿍NTHalt 쿛ause Music 쿐rror code 102 if music is already paused � � 7 쿍NTCont 쿎ontinue Music 쿐rror code 102 if music is not paused � � 8 쿍NTFade 쿑ade out Music 쿛arameter: Fading speed � � 9 쿭oPSG 쿛SG Override 쿛arameter:�Instrument number (valid:�1-44) � �10 퀂topPSG 쿛SG Override Stop쿙one � 읕컴좔컴컴컴컴컨컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 When function 0 is executed correctly, the high nibble of the error code will contain the primary slot number and the low nibble will contain the secondary slot where the SCC was found. If not executed correctly, the replay routine gives an error code 100 back. Function 1, 8 and 9 need a parameter to execute it correctly. This parameter can be filled in by setting the 8-bits parameter into address 'RepCommand'. e.g. You want to force the music through slot 1. To accomplish that do this: ld a,1 ld (RepCommand),a BNTReplay(forceMusic) Functions 2 and 3 are for loading an instrument kit or song. The file which has to be loaded must be stored in a 12 bytes large block which should look like this: Byte 0 : drive (0 - Default, 1 - drive A:, 2 - Drive B:, etc..) Bytes 1-8 : Filename. When necessarry fill up with spaces. Bytes 9-11: Extension. When necessarry fill up with spaces. e.g. If you want have the file "test1.sbm" and you want it to be loaded from drive B: the block needs to be like this: .db 2,"TEST1 SBM" Also this block has to be moved to the FCB that the SCC-Blaffer NT replay routine uses. This is at address 'BNTFcb'. To load the song stated before, do something like this: ld hl,songName ld de,BNTFcb ld bc,12 ldir BNTReplay(SBMLoad) ret songName: .db 0,"TEST1 SBM" This will load the song 'TEST1.SBM' from the 'Default' drive. Pretty easy huh?? Fore the rest just read the info for BASIC users to get detailed info about the functions.. Take a look at the 'ML_BNTPL.ASM' for information on how to handle with error-codes... ML users don't have to use the BNTPLAY.BIN, what they could do is ripping the replayer from the source and then adapt it for own use, but I think this is pretty damn easy... It may look a bit complicated and much, but when you use it for a little while you'll do it without checking any documentation anymore, trust me... Just take a good look at the 'ML_MACNT.ASM' and 'ML_BNTPL.ASM' files and and you'll surely understand all options. Some other things now... The storage of songdata: MusicAddress .equ $8000 ; Address of the music SongName .equ MusicAddress ; Name of the song InsKitName .equ SongName+67 ; Name of the ins. kit LastPos .equ InsKitName+11 ; Last Position LoopPos .equ LastPos+1 ; byte 1: Loop position? ; byte 2: Position to loop Patterns .equ LoopPos+2 ; Patterns to play InitialTempo .equ Patterns+256 ; Initial tempo StartVolumes .equ InitialTempo+1 ; Initial volumes StartInstruments .equ StartVolumes+5 ; Initial instruments DetuneSettings .equ StartInstruments+4 ; Detune Settings VolumeSlideSettings .equ DetuneSettings+5 ; Auto vol. slide settings PatternData .equ MusicAddress+448 ; Pattern data Addresses to read: Name Address Size Description MusicPlay $da26 1 Byte Is music playing? <>0 if so. MusicPeak $da27 1 Byte Is a new row started?? SccSlot $da28 1 Byte Current SCC Slot. (slot * 16) SngBnkPlay $da29 1 Byte Song bank InsBnkPlay $da2a 1 Byte Instrument bank SngPos $da2b 1 Byte Current song position SngRow $da2c 1 Byte Current song row SngTmp $da2d 1 Byte Current song tempo SngFreqs $da2e 10 Bytes Current frequencies SngVolumes $da38 5 Bytes Currnt volumes (All these equates also are in the ML_MACNT.ASM file) Current frequencies is build as follows: 5 * 1 word of frequency data. The first one contains the frequency that is currently playing on channel 1, the second of channel 2, etc. Current volumes is build as follows: The first byte contains the volume of channel 1, the second one of channel 2, etc, etc. Well, that's it!... Good luck, and happy listening! And remember... Bugs, suggestions and/or other ideas: info@teddywarez.cjb.net mzl. d-fader.TeZ (that TeZ is our new compression method.. it really says TeddyWareZ.. Pretty good algorithm eh?? The only problem is we can't decompress it.. Maybe it's because we just delete a couple of bytes in the file..) Blue Crystal: I still can't figure out why I joined these strange fellows.. I mean, DJ. Chaos thinks d-fader is a cow who gives blue milk, d-fader thinks DJ. Chaos comes from Mars, and HeXx.. Well eh... He's ok (I think)... Tring d-fader : Mooh, the doorbell! Chaos : ZipZapZopZipZap... d-fader : Yeah, yeah, I'll open the door, mooh... Triiiiiiing d-fader : Yeah, yeah... relax! krrrg.. d-fader : Mooh! Hey HeXx! HeXx : hey! Guess what I have gone through... d-fader : You finally know smurfs don't exist... HeXx : No, in contrary! HeXx : I saw them! Housing smurfs!! d-fader : Housing Smurfs?? Mooh.. Dj. Chaos : ZapZipZipZapZop.. d-fader : Shut up! HeXx : Anyways, I asked 'Do you guys house all day long??' Smurfs : Yeah, Housuh, Housuh, Housuh! HeXx : Aren't you guys gettin' dead beat??? Smurfs : Ofcourse not, toad-stools enough!!! Blue Crystal: Blue Crystal is (just as Johnny Bravo) as you can see the victim of the zone where normal things don't happen... Very often...