CIATracker.lib Documentation Previous revisions by: Neil O'Rourke Version 1.01b (27/6/95) Introduction ~~~~~~~~~~~~ The standard soundtracker replay routines supplied with Blitz Basic 2 have many faults, which this library attempts to overcome. Some of the features are: - Plays all NT/PT songs that utilise either the VBLANK timing or the more recent CIA based timings - Plays back correctly on 50/60Hz systems, running either PAL or NTSC - Contains more specialised functions for advanced programmers - Enables the programmer to syncronise graphics with their music Credits: ~~~~~~~~ Original ProTracker playroutine by Amiga Freelancers, converted and enhanced for Blitz by Neil O'Rourke. Naggings from Roy, Jeff and Richard. Newer revisions and further enhancements by Crossbones/Binary Assault. NOTE: ~~~~~ Neil stopped work on the library at version 1.6. Unfortunately, all the source code I've located of this library is only at version 1.3. This means that if you are fimiliar with the last version of his library, a few of the commands might not contain the same sytax or might not even be in this library any more. If you find that you simply can't live without a certain feature, you might try to contact me and coax me into providing the update you need. I say *MIGHT* because there is no guarentee that I'll work on it. Quick Usage: ~~~~~~~~~~~~ Load the module you want with the LoadTrackerModule command, and then StartTrackerModule it. Basic Commands ~~~~~~~~~~~~~~ success=LoadTrackerModule(TrackerModule#,FileName$) Loads the named module into chip ram, ready for playing. This command can only be called in Amiga mode. success is a boolean return code (true). If the load fails for any reason, success returns the AmigaDOS error code. Note that there is an implicit call to FreeTrackerModule for whatever module you are trying to load. However, if you want to load another module, don't try to load it on top of the existing one that is playing. Use another TrackerModule# (you have from 0 to 8). The results are unpredictable, and range from nothing to a system crash. We can't call StopTracker, because this will stop everything. success=StartTracker(TrackerModule#) Starts to play the requested module, stopping any modules already playing, or restarts the current module, and returns true. Returns false if the module couldn't be started for some reason (like it isn't loaded). StopTracker Stops the current module FreeTrackerModule TrackerModule# This frees a module loaded with LoadTrackerModule. You cannot free a module that has been set up with SetTrackerModule (see below), but there is nothing to stop you trying. DecodeModule TrackerModule#,ModuleAddress This sets an arbitary area of memory as a tracker module, useful if you have BLoaded/INCBIN'd a file and want to hear if it is a module. Caution: a non-module may crash the Amiga. trackerlength=GetTrackerSize(TrackerModule#) GetTrackerLocation (TrackerModule#) Both these functions return information about the module that has been loaded with LoadTrackerModule. There should be no need to use this information, and these commands are only included because they served a purpose in debugging a long time ago, and to remove them would cause problems with the Blitz tokens trackerevent=GetTrackerEvent This command is a customised extension to the ProTracker replay routine. A "TrackerEvent" occurs when the replay routine comes across a $8xx command. This command is not defined in the command list, and many demos (eg Jesus on E's) use it to trigger effects. This command gets the most recent TrackerEvent, so any program looking at this will have to compare the current value to the value that triggered the current effect. success=CheckTrackerEvent This routine checks to see if a TrackerEvent has occured since the last time the routine was called, and returns True if it has. Use GetTrackerEvent to determine what data the $8xx command had. WaitTrackerEvent ** V1.6: DO NOT USE THIS COMMAND! ** ** V1.0b: I haven't checked this. ** success=CheckTrackerModuleID(TrackerModule#) This checks the module for the standard Pro/Noise/SoundTracker ID string "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True if one of them is found. This means that you can safely call StartTracker. Note that there is no 100% guarenteed way of determining what is a module and what isn't. Bit Arts, for example, remove the M.K. identifier to make it harder to rip modules, so if you're writing a module ripping program, you have to take this result with a grain of salt. SongPos=GetModulePosition This returns the current pattern that is playing in the song ModulePositionJump(Position#) This command tells the play routine to jump to the pattern requested in Position#. name$=GetModuleName$(TrackerModule#) Returns the name of the module in name$ success=ModuleToChip(TrackerModule#) This command is mainly of use for people using the INCBIN method of adding the module to the compiled program. This command reserves X amount of bytes of chipmem and moves the module (and references) to that memory location. NOTE: This command will free any references to the module in fastmemory. If you free the module from chipmem and need it again, you'll have to decode it again first. PauseModule This command toggles the playing status of the module. If you wish to pause the module, call the command. To unpause it, simply call it again. Notes: ~~~~~~ Quite a number of these commands extract their data from the playroutine in real time; that is, around fifty times a second (depending upon the tempo). Therefore, the value your program receives could well be very different from what is actually happening in the song. How do I contact the person revising this library? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Steve Flock [Crossbones] / Binary Assault Email: sflock@comtch.iea.com Snail: Steve Flock 2421 west LaCrosse Spokane, Washington 99205