· : ¦ . _________ ________ _____________ ž_____ | · __ / : ___________/ _ \ \ __ _ / | \ Ž____: : \_/ -A : \______ \ | \_ _: \_/ \_/ | \ ¦ | ¦ \_ ··D_ / / _/ | / Ž___/ \_ | : : | Ž_______/ `N· _/ \ \_________/ | \________/ ¦ Ž_____ ¦ | : \__________/ \ ¦ \_ : : \__________ \___________/ . · CRaZY GaNG . +--------------------------------+ Eagleplayer 1.51 Documentation ============================== TYPED BY SHARD - N&B 1993 Defect Software Productions ================================ Part Two ======== 6.5 Hints and Tips ------------------ The player should not change the LED condition because Delitracker/ Eagleplayer will handle it. This is a small list that you should match when you create your own player or custom module. [ ] checkroutine exact enough ? [ ] audiochannels allocated/freed correctly ? [ ] all allocated memory freed after playing? [ ] all locks unlocked after playing ? [ ] enforcer and mungwall proof ? [ ] viable error handling path taken for all possible errors ? [ ] player tested under 1.3 and 2.0 ? [ ] does the player work correct in all videomodes ? Problems Symptom possible source elimination crash a5 trashed, other registers not saved, wrong stack usage initialization wrong or too late module too new for the replayroutine better check module sounds audio data not in chipmem wrong wrong initialization module too new for the replayroutine player needs some special values in some registers extra init code wrong videomode no sound Audio-DMA off >68000 player writes directly to processor use OS routines to intvectors and VBR is not 0. set IntVectors no free wrong interrupt handling VBlank-IRQ: CPU-time Z-Flag must be set at the end of the interruptroutine. 6.6 The special informations and news for the Eagleplayer --------------------------------------------------------- The Eagleplayer offers a lot of new possibilities, which are described within the following chapters. The 3 TAGS listed below are usable for custom modules: (the Delitracker ignored them) DTP_PlayerName DTP_Creator DTP_ExtLoad The most important news are the new Eagleplayer-Tags, the ModuleInfo-Function, Analyzersupport and the new Globals 6.6.1 The new Tags ------------------ EP_Get_ModuleInfo (FPTR) This function of the replayer has to return within the register A0 a fully initialized Moduleinfo- taglist or zero for no taglist. see also chapter 6.6.2 Moduleinfo NOTE: it`s possible that this function is called when no module was loaded, think of that !! EP_Free_ModuleInfo (FPTR) This optional function is for example to free previously allocated memory for the Moduleinfo- taglist. No return values expected. EP_Voices (FPTR) using this function the informations about the 4 voices will be given by the Eagleplayer in D0. If the bit for the voice set, the voice is enabled, if the bit was cleared, the voice is disabled Bit 0 = Voice 0;Bit 1 = Voice1;Bit 2= Voice 2; Bit 3 = Voice3 EP_Structinit (FPTR) returns in A0 a pointer to a UPS_USER structure in which the replayer puts the informations for the Analyzerprograms (Userprograms) or ZERO. This structure will then be given to all Userprograms which use the infos of it. EP_StructEnd (FPTR) optional, e.g. to free the memory used for the structure EP_LoadPlConfig (FPTR) calls the routine loading the configuration of this replayer (usually 'ENV:Eagleplayer/xxx.config' ) EP_SavePlConfig (FPTR) calls the routine saving the configuration of this replayer (usually 'ENVARC:Eagleplayer/x.config') (advise of the authors) EP_GetPositionNr (FPTR) returns in D0.l the actual Pattern-number played at this time. This value will be scrolled into the Main window of the Eagleplayer EP_SetSpeed (FPTR) for players with own timer this function gives you the possibility using the speed-propgedget. Therefore in D0 there will you find the actual speed value between -25 and +25. 0 means the standard speed, if the speed should be higher, this value is positive, for lower speed negative EP_Flags (LONG) These flags within "TI_Data" of this tag show which functions the player basically supports and must exist !! This Tag was included because we wrote "self modifying" players which change the module to support Analyzer,Voices, Volume... When the internal replays of this module differ to another then it may happen that the replayer can`t change the module in this way we need it so that one or the other function won`t be available from module to module. Therefore the following flagbits for showing the basic abilities of the replayer in the Player window: EPF_Songend - the replayer supports Songend EPF_Restart - the module is restartable (partially impossible) EPF_Disable - The player is disabled EPF_NextSong - supports next subsong EPF_PrevSong - supports previous subsong EPF_NextPatt - supports jump to next pattern EPF_PrevPatt - supports jump to previous pattern EPF_Volume - volumecontrol possible EPF_Balance - balance possible EPF_Voices - can change the state of the voices EPF_Save - module can be saved EPF_Analyzer - Analyzer-support EPF_ModuleInfo- can tell infos to the current module EPF_SampleInfo- infos to the samples of the current mod EPF_Packable - module may be packed EPF_VolVoices - volume of each voice can be different to the next (EPG_VolVoice1...) EP_KickVersion (WORD) minimal Kickstartversion (37 for Kick 2.0) EP_PlayerVersion (LONG) minimal Eagleplayerversion, if the replayer may only be loaded by the Eagleplayer you must specify "DTP_RequestDTVersion,$7fffffff" additionally EP_EjectPlayer (FPTR) if the replayer allocates any memory, filelocks etc. it can be freed at this point. Then the replayer will be thrown out of the memory. EP_Date (LONG) date of creating this replayer e.g. dc.l EP_Date dc.b 04,11,19,93 -> November the 4th in 1993 EP_Check3 (FPTR) Checkroutine, called after loading the first 1000 bytes of the module. If it was recognized it will be loaded into fastmem. NOTE: Using this check you may not pack the module, so if you wanna also packed modules, use DTP_check2 additionally. 6.6.2 Moduleinfo ---------------- For the moduleinfo-function the Eagleplayer offers some Tags which can give the user almost all informations about the actual module. The taglist will be overtaken by the Eagleplayer it calls the routine specified in the "EP_Moduleinfo" Tag within A0 (see also chapter 6.6.1). Please notice that currently not all informations will be displayed in the scroller of the main window. In a future version there will be a window telling these informations completely. MI_SongName (STRPTR) Name of the module (like in the sound/protracker ones) If you give a ZERO to TI_Data an "unknown" appears as songname. This is a very comfortable method getting the right name of ripped modules. MI_AuthorName (STRPTR) Name of the guy writing this song. If you return a ZERO in TI_Data, the Eagleplayer displays an "unknown". MI_SubSongs (LONG) Number of subsongs in the module MI_Pattern (LONG) Number of patterns in the module MI_MaxPattern (LONG) Max. number of patterns (e.g. Soundtracker: 64) MI_Length (LONG) length of the song (e.g. in Patterns) <- NOT the SIZE MI_MaxLength (LONG) max. length of the songs (e.g. Soundtracker 127) MI_Steps (LONG) number of steps (e.g. BP Soundmon) MI_MaxSteps (LONG) Max. number of steps MI_Samples (LONG) number of used samples MI_MaxSamples (LONG) Max. number of used samples (e.g. Protracker: 31) MI_SynthSamples (LONG) Number of used synthetic samples MI_MaxSynthSamples (LONG) max. number of sysnthetic samples MI_Songsize (LONG) size of the Song in Bytes (without samples !) MI_SamplesSize (LONG) size of the samples in Bytes MI_ChipSize (LONG) used Chip Memory in Bytes MI_OtherSize (LONG) used Fast Memory in Bytes MI_Calcsize (LONG) calculated size of the whole module in bytes MI_SpecialInfo (STRPTR) pointer to special informations as ASCII-String MI_LoadSize (LONG) Overall size of all files loaded (for Soundsystem loading more than one file, e.g. Startrekker,TFMX) MI_Unpacked (LONG) Unpacked size in bytes (e.g. how long would a Noisepacker- module when converting back to protracker) MI_UnPackedSystem (LONG)(STRPTR) tells to what soundsystem this module normally belongs if it was packed (e.g. with Noisepacker,Propacker,Promizer), either an internal number (see below) or a pointer to a string containing the name The following names are internal: MIUS_OldSoundtracker MIUS_Soundtracker MIUS_Noisetracker MIUS_Protracker MI_Prefix (STRPTR) Pointer to the prefix for the name of the module, e.g. 'MOD.' or 'Mdat.'. So is it possible to save the module with the real name and a matching prefix. MI_About (STRPTR) Pointer to a text about the player MI_MaxSubSong (LONG) max. number of subsongs for this sound format MI_Voices (LONG) Number of used voices in this format MI_MaxVoices (LONG) Number of max. possible Voices in this format. 6.6.3 Analyzer control ---------------------- The Analyzercontrol will be done via the UPS_User structure described below. (how to offer the structure- see chapter 6.6.1 "EP_Structinit) The structure looks this way: STRUCTURE UPS_USER,0 APTR UPS_Voice1Adr UWORD UPS_Voice1Len UWORD UPS_Voice1Per UWORD UPS_Voice1Vol UWORD UPS_Voice1Note UWORD UPS_Voice1SampleNr UWORD UPS_Voice1SampleType UWORD UPS_Voice1Repeat LABEL UPS_Modulo APTR UPS_Voice2Adr UWORD UPS_Voice2Len UWORD UPS_Voice2Per UWORD UPS_Voice2Vol UWORD UPS_Voice2Note UWORD UPS_Voice2SampleNr UWORD UPS_Voice2SampleType UWORD UPS_Voice2Repeat APTR UPS_Voice3Adr UWORD UPS_Voice3Len UWORD UPS_Voice3Per UWORD UPS_Voice3Vol UWORD UPS_Voice3Note UWORD UPS_Voice3SampleNr UWORD UPS_Voice3SampleType UWORD UPS_Voice3Repeat APTR UPS_Voice4Adr UWORD UPS_Voice4Len UWORD UPS_Voice4Per UWORD UPS_Voice4Vol UWORD UPS_Voice4Note UWORD UPS_Voice4SampleNr UWORD UPS_Voice4SampleType UWORD UPS_Voice4Repeat UWORD UPS_DMACon UWORD UPS_Flags UWORD UPS_Enabled UWORD UPS_Reserved LABEL UPS_SizeOF These entries have the following meanings: UPS_Voice?Adr Address of the sample played currently on this voice (must stay here as long as the sample is playing !) UPS_Voice?Len size of the sample played on this voice UPS_Voice?Per actual value of the sample period, plays a very important role, if a period value <>0 is set here it means that a new note was played. So the period is the most important thing for the analyzers. If you can`t find out when you play a new Note, please set the period every time you access the audio hardware ($dff0A6/B6/C6/D6), this is also advised for Samplesize and Address UPS_Voice?Vol Volume to be written to the hardware, do not write here the volume you calculate from your own one and the volume currently set in the Eagleplayer, that means when e.g. the volume you will set basically is 64 but the Eagleplayer's volume is only 32 I don`t wanna see 32 but 64, ok ? The other way will be used with another method (Mastervolume !) UPS_Voice?Note not supported yet UPS_Voice?Samplenr tells the actual samplenumber, neither supported yet by a userprogram nor by a playroutine UPS_Voice?Sampletype Sampletype, not supported yet UPS_Voice?Repeat tells if the sample will be played once or with repeat, if this value is 0 that means repeat on, if it is 1 the repeating of the sample is off UPS_DMACon tells which voices are on, which are off, Bit 0 for voice 0, bit 1 for voice 1 and so on, if the bit set the channel is switched on (the name "UPS_DMACON" is a little bit confusing, better was "UPS_Voices", see also at chapter 6.6.1. "EP_Voices) UPS_Flags Flagbits telling which possibilities of the UPS_User structure the replayer supports UPSFL_Adr - Sampleaddress UPSFL_Len - SampleSize UPSFL_Per - Sampleperiod (IMPORTANT!) UPSFL_Vol - Volume UPSFL_Note - Note, not supported yet UPSFL_SNr - Samplenumber UPSFL_STy - Sampletype, not supported yet UPSFL_DMACon - which voices are off/on The rest of the entries is reserved for future versions of the Eagleplayer. --------------------------- Attention ------------------------------------- For the todays Userprograms it is expected that at least UPSF_Adr, UPSF_Len, UPSF_Per, UPSF_Dmacon and UPSF_Vol are set and supported. The other parameters (UPS_Voice?Adr, UPS_Voice?Len, UPS_Voice?Per and UPS_Voice?Vol) have also to be set and UPS_Enabled should always be "0" on leaving the interrupt ! --------------------------------------------------------------------------- 6.6.4 The new Eagleplayer Globals (from Eagleplayer 1.10 on) ------------------------------------------------------------ After trying not to do any changes within the globals it has become nessesary to add some subroutines,pointers and data value cells. Using the new Eagleplayer-globals you don`t have to use registers to deal with arguments but to enter the values into one of the 8 globals argument cells. Into EPG_ArgN you always have to write the number of arguments. A subprogram always must get all the arguments required and so EPG_ArgN must countain always the maximum value telled at "Inputs:" - see below. If the parameters will be given in another way it will be described separately. The Subroutines of the Eagleplayer may called everytime by every replayer but NOT IN THE INTERRUPT ! If not told extra the Userprograms may only access the subroutines only after an USCLASS_LockEP call. Now follow the most important subroutines: ----- EPG_SaveMem ----- A memory range will be saved using the savemode set in the actual preferences or by your own choice. This function will only work in the registered version. If the savemode is -1 the standard one set by the user will be taken. Input: Arg1 = Startaddress Arg2 = Endaddress Arg3 = Stringpointer to full filename including the path Arg4 = SaveMode (-1=Eagleplayer settings 0=not packed 1=PP-Crunched 2=LH-Crunched 3=XPK-Crunched ArgN = 4 Output: Arg1 = Return value (0=no error) ----- EPG_FileRequest ----- A filerequester will opened using the default Filerequester mode. You may differ between a fileselection and a directory selection.. Input: Arg1 = Filerequester Titlename Arg2 = Directory Path Arg3 = Filename Arg4 = Window Arg5 = Filerequestertype (1=Fileselect 0=Dirselect) Arg6 = OutPut-Text for Eagleplayer-Statuswindow ArgN = 6 Output: Arg1 = Return value (0=Cancel or System error, else 1) ----- EPG_TextRequest ----- A textrequester will be opened. You write the Address of an ASCII-text to the EPG_Arg1. The window opened will be adapted to the size of the text. Within the text you may add arguments which are taken from the argument table. You may use as much gadgets as you want and you may use own Images in this window. Under OS2.0 and higher public screens are supported. Note: This routine countains a bug not found yet. It should be used anyway because this error will be fixed in one of the next versions. Input: Arg1 = TextAddress Arg2 = Pointer to Pubscreenname (only OS2.0+, else 0) Arg3 = Position on Screen (x.w & y.w) Arg4 = Pointer to Gadgetnames Arg5 = Poniter to Requestername Arg6 = Pointer to ArgumentList Arg7 = Pointer to ImageDatas ArgN = 7 Arguments in ASCII-String: %s - String %d - Decimal number Output: Arg1 = Return value 0=Error (e.g. Window too big) else number of chosen gadget ----- EPG_LoadExecutable ----- This function loads an executable program. This will be depacked, if possible. Input: Arg1 = FilePath ArgN = 1 OutPut: Arg1 = Jump Adr of the Program d0 = Error (0=ok) ----- EPG_NewLoadFile ----- Like DTG_LoadFile, except that the memory type can be supplied Input: Arg1 = Memory type (like _LVOALLOCMEM - exec library) ArgN = 1 DTG_PathArrayPtr = Path of the file Output: d0 = Return value (0=ok) -- EPG_ScrollText -- Scrolls the supplied text into the main window of the Eagle- player. If the text is ZERO terminated it stops when it was completely scrolled in, if it is 1-terminated it will be scrolled in a loop, if a 2 is at the end of the text it will be scrolled until it reaches the left side if the text is not already there. Input: Arg1 = Textaddress ArgN = 1 ----- EPG_LoadPlConfig ----- Loads the configuration of a player. This function was added for solving the problem to press cancel x-times when the "ENV:" directory could not be found and x players need a config from "ENV:". It will be tested if the config should exist in the ENV-Dir or not. If the directory doesn`t exist the config won`t be loaded. (not built in yet !) Input: Arg1 = ConfigPath+Filename ("ENVARC:eagleplayer/xxx.config" !!!) ArgN = 1 Output Arg1 = Return value ----- EPG_SavePlConfig ----- Saves a PlayerConfig. (not built in yet !) Input: Arg1 = ConfigPath+file ("ENVARC:eagleplayer/xxx.config" !!!) Arg2 = Startaddress Arg3 = Endaddress Arg4 = SaveMode (see also "EPG_SaveMem") Output: Arg1 = Return value (0=ok) ----- EPG_FindTag ----- Seeks a Tagitem within the given TagList. This Function depends not on the kickstart and may also called from userprograms without "USCLASS_LockEP" at any time. Input: a0 = Taglist d0 = Tag Output: d0 = Ti_Data`s value d1 = Tag found (0=no,then d0 also 0, 1=yes) ----- EPG_FindAuthor ----- Seeks the Author of a music file within the supplied range. This routine was written for the Soundtracker and its mutants but may also used for other Soundystems. This routine seeks after "by" and "#" in the samplename. The next string will be taken as the authorname. This name doesn`t have to be copied but it is enough writing this address to the Moduleinfo Tag. Input: Arg1 = Start of the first samplename Arg2 = Offset to the next samplename Arg3 = Size of the samplename Arg4 = number of samples ArgN = 4 Output Arg1 = Pointer to Authorstring or ZERO Arg2 = Size of Authorstring or ZERO ----- EPG_Voice1Vol - EPG_Voice4Vol ----- at these word-orientated addresses you will find the volumes for each of the hardware voices, pre-calculated from Volume, Balance and Voices. So you only need one routine for vol etc. instead of 3 ! to use these values the following example: move.w 20(a0),d0 <- example for the volume of sample for voice 2 mulu EPG_volvoice2(A5),d0 <- calculate the volume depending on settings lsr.w #6,d0 <- final value move.w d0,$dff0a8 <- write to the hardware Out of this the found and used librarybases are saved into the globals. Don`t CHANGE ANYTHING IN THE GLOBALS !! (except EPG_ARG1 - EPG_ArgN) 7.1 Introduction and description of the ARexx-Port -------------------------------------------------- Finally, from Version 1.10 on the Eagleplayer supports ARexx. Therefore the Eagleplayer offers a lot of commands which make the Eagleplayer able to be practically remote controlled. 7.2 The commands ---------------- Following this text you will find all ARexx-commands supported by the Eagle- player. If no error occurs, the result returned by the Eagleplayer to the calling Arexx-Script is the same which would be scrolled into the main window .Of course not if the Eagleplayer expects exact arguments e.g. using the status command. If an error occurs in RX_result the error-text will be returned. The User should of course test if the different possibilities can be used in any case. It won't work e.g. if you wanna save a module but the current re- player doesn`t support saving. If you tested it before, the problem is solved. We offer a lot of status informations, make use of them ! The arguments in such "[]" brackets are optional, in "<>" brackets must be supplied ! If we talk filenames from now on we mean FILE AND PATH ! (if no other case is mentioned) Command Meaning --------------------------------------------------------------------------- LoadModule [Filename] loads the supplied module and plays it if "QUICKSTART" in the prefs (see at STATUS command) is switched on. Else you must call "play" before it starts. If no filename was supplied, a filerequester will appear LoadModule ... puts the given modules into a list which you can see in the Pulldown-menu. The Eagleplayer doesn`t read the whole directory. The filename is given without path ! SaveModule [Filename] The loaded module will be saved under the supplied name. If no argument is given a filerequester appears. (r.V.) About Module returns the scroltext for displaying the moduleinformations EjectModule kills the module out of memory Stop The Player stopps. Calling "play" would play it from the beginning on. ReplaySong Stops playing and then restarts from the beginning of the module Play The Eagleplayer starts playing Pause The playing stops. If you select "play" the module continues at the point where it was paused NextSong the next subsong will be played PrevSong the previous subsong will be played NextModule the next module of the list will be played PrevModule the previous module of the list will be played NextPattern the next pattern will be played PrevPattern the previous pattern will be played PubScreen opens the Eagleplayer on the supplied PublicScreen. Quit The Eagleplayer will be closed and removed from memory. AboutEP Returns a String about the Eagleplayer in RX_Result. ScrollText The supplied text scrolls into the main window. Iconify The Eagleplayer will be iconified or if it already was in iconify mode, it will open its window(s) again. HelpMe Returns the help string for the given function DeleteFile [Filename] Deletes the supplied file. UserPrg Switches the given userprogram on/off LoadConfig Loads a new Eagleplayer-Config. SaveConfig Saves the actual Eagleplayer-Config. Font loads a new font for the main window OpenMainWindow the main window will be opened OpenPlWindow the playerinfo window will be closed CloseMainWindow the main window will be closed ClosePlWindow the playerinfo window will be closed LittleWin switches the iconify mode to "little window" AppItem switches the iconify mode to "AppItem" AppIcon switches the iconify mode to "AppIcon" Volume sets the supplied volume value. Balance sets the supplied balance value. TimeOut