/* (tabstops=8) °°°°°°°°°°°°°°±±±±±±±±±±±±±²²²²²²²²²²²²²²²²²²²²²²²²±±±±±±±±±±±±±°°°°°°°°°°°°°° þ S3M Player Tutorial by FireLight þ Copyright (c) Brett Paterson 1994-95 þ þ Last updated 20/11/95 þ °°°°°°°°°°°°°°±±±±±±±±±±±±±²²²²²²²²²²²²²²²²²²²²²²²²±±±±±±±±±±±±±°°°°°°°°°°°°°° ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² : SECTION 0: ²±° ³ ³ °±² Index ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Section 1 : INTRODUCTION 1.1 Notes. 1.2 Terminology. 1.3 Contacting FireLight and feedback. Section 2 : THE LOADER 2.1 Notes. 2.2 Verification. 2.3 Load Module Name. 2.4 Rest of the Main Header - default/miscellaneous info. 2.5 Load channel settings 2.5.1 The 32 bytes. 2.5.2 Remapping the channels. 2.6 Load order data. 2.7 Parapointers. 2.8 Default pan positions. 2.8.1 Mono. 2.9 Instruments. 2.10 Loading pattern data. 2.10.1 Now 5 bytes? 2.11 Loading sample data. Section 3 : EXTRA S3M FEATURES 3.1 Volume byte. 3.2 Panning. 3.3 New effects. Section 4 : MORE PERIODS 4.1 Goodbye fine tune!!! - C2SPD. 4.2 9 octaves. Section 5 : MISCELLANEOUS 5.1 The 10 steps in converting a MOD player to an S3M player. 5.2 Creating the ultimate internal format of your own. Section 6 : EFFECTS 6.01 Quick Reference Chart 6.1 Effect Axx (Set speed) 6.2 Effect Bxx (Jump to order) 6.3 Effect Cxx (Break pattern to row) 6.4 Effect Dxx (Volume slide) 6.5 Effect Exx (Portamento Down) 6.6 Effect Fxx (Portamento Up) 6.7 Effect Gxx (Tone portamento) 6.8 Effect Hxy (Vibrato) 6.9 Effect Ixy (Tremor) 6.10 Effect Jxy (Arpeggio) 6.11 Effect Kxy (Vibrato + Volume slide) 6.12 Effect Lxy (Porta + Volume slide) 6.13 Effect Oxy (Set sample offset) 6.14 Effect Qxy (Retrig (+volumeslide) note) 6.15 Effect Rxy (Tremolo) 6.16 Effect Uxy (Fine Vibrato) 6.17 Effect S0x (Set filter) 6.18 Effect S1x (Set glissando control) 6.19 Effect S2x (Set finetune) 6.20 Effect S3x (Set vibrato waveform) 6.21 Effect S4x (Set tremolo waveform) 6.22 Effect S8x (Set channel pan position) 6.23 Effect SAx (Stereo control) 6.24 Effect SBx (Pattern loop) 6.25 Effect SCx (Notecut) 6.26 Effect SDx (Notedelay) 6.27 Effect SEx (Patterndelay) 6.28 Effect SFx (Funkrepeat) 6.29 Effect Txx (Set Tempo) 6.30 Effect Vxx (Set global volume) Section 7 : APPENDIX 7.1 Notes 7.2 ScreamTracker 3 TECH.DOC (edited) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² : SECTION 1: ²±° ³ ³ °±² Introduction ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 1.1 Notes ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Assumptions: ============ Everything that was assumed in FMODDOC.TXT, and that you have actually got a .MOD player working. I borrow from FMODDOC.TXT and even cut and paste some of the parts. Most of the theory and information about writing player code is found in FMODDOC.TXT, this document is more about the actual S3M FILE format. At this point I will just take the opportunity to say that coding a .MOD player is quite beneficial, even though I hear you scoff and say who supports .MOD any more? Well sorry to say but S3M in its playing theory borrows VERY, VERY heavily from protracker, and if you code a .MOD player, it takes VERY LITTLE effort to make that player an S3M player. My .MOD player took about 1 HOUR to convert to an S3M player after the loader, as the principles in playing are very similar. WRITE A MOD PLAYER FIRST THEN DO S3M, YOU WON'T REGRET IT. S3M uses 90% of the .MOD effects, and as S3M has about 90% of .MOD lurking in the background in other areas, I can't emphasize this enough. See section 5 on the 10 simple steps in converting a MOD player to an S3M player to see what I mean. Your player will probably play the effects more accurately too if you get it right under .MOD first, and then .S3M. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 1.2 Terminology ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ TYPE LENGTH Bits RANGE WATCOM/BORLAND/TURBO C ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ byte 1 8 0-255 unsigned char word 2 16 0-65,535 unsigned short dword 4 32 0-4,294,967,295 unsigned long ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Throughout this text I use the terms BYTE,WORD, and DWORD, to make the document more general to all languages. In C you can use typedefs to achieve the use of byte,word,dword terminology, and in Pascal and asm the syntax is already suited to this anyway. ORDERS - orders are how the mod plays from 0 to length of song. PATTERNS - patterns are played in any ORDER, and are the physical information. TICK - I refer to a clock tick for the interrupt handler as a tick, some others use the term FRAME. I will be using the term tick throughout the whole document. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 1.3 Contacting FireLight and feedback ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Contact is encouraged for any reason. After typing literally over 100 printed pages, I might have probably made some small mistakes here and there, but I have proof read this document many many times and spell checked it etc. email : firelght@suburbia.apana.org.au post : Brett Paterson, 48/a Parr st, Leongatha, 3953, Victoria, Australia. IRC : FireLight on #coders (#trax) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² : SECTION 2 : ²±° ³ ³ °±² The Loader ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 2.1 Notes ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ As S3M can be quite difficult to load for the inexperienced, I will explain as much as possible about the quirkiness of this format and how to overcome it. If you have already written a .MOD loader, you will have to change your storage variables around a little bit to compensate for S3M's new features. The main differences are: ========================= 1. 32 channels 2. 9 octaves 3. volume column 4. a few extra effects More about this will be discussed later on in the document, and see SECTION 5.1 on handling these differences. As in FMODDOC.TXT I will split most sections into the following 4 sections, to try and get optimal understanding of the matter. - EXPLANATION (describes what the section is on about, for understanding) - PSEUDOCODE (usually shows HOW to code it, but in English) - STORAGE ISSUE (helps on how to store the information loaded) - SUGGESTION (a helpful hint or suggestion to do after this step) NOTE: Remember to follow this document along side TECH.DOC's map out of an S3M file. (TECH.DOC is kept in the appendix at the end of this document). It will make things easier to visualise. I'm not here to re-write tech.doc but to explain how things work. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 2.2 Verification ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Explanation: ============ Before we attempt to load a the S3M, we should check that it is in fact an S3M. Every S3M has a signature stored inside the file at offset 44 (2Ch), and this should always be checked first. PseudoCode: =========== - Seek to offset 44 (2Ch) in the file - read in 4 bytes - compare them to "SCRM" - if it is a match we have an S3M file (apparently) - otherwise exit and display error message. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 2.3 Load Module Name ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Explanation: ============ This is a trivial part of the loader and just holds the Title or name of the mod. It is the very first 28 bytes of the MOD. PsuedoCode: =========== - Seek back to position 0, the start of the file - read in 28 bytes, store as MODULE_NAME. Storage Issue: ============== If your system originally was set up to hold a 20byte name for a module title, then extend this to 28 bytes. Suggestion: =========== As always this point is a good time to see if it worked by printing out what you read in and seeing if it is correct. Note: ===== From this point on I won't be going into as much detail or length for trivial matters like this, but I will still make sure it is understood with a brief explanation. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ °±² 2.4 Rest of the Main Header - default/miscellaneous information ²±° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Explanation: ============ With a .MOD loader, normally at this stage we would be now getting ready to load in the 31 lots of sample information, but in S3M's case we have a lot of other miscellaneous information we want to know first. These sorts of things are default panning positions, global volume, initial tempo etc, etc. This section covers these miscellaneous parts and explains what to do with them. Breaking away from the usual format I will display this section in more of a map format, with the file offset and bytes to read displayed along with a short de...
Amiga78