Scream Tracker Music Interface Kit V0.2
S.T.M.I.K.
Copyright (C) 1991 Sami Tammilehto
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Contents:
1. About the STMIK and this documentation
2. License
3. Future Crew demo included
4. Scream Tracker V3.0
5. STMIK module format
6. How to make music for STMIK?
7. Limits of the current STMIK
8. How to use the STMIK
9. Examples
10. How to compile the examples
11. The STMLOAD.OBJ
12. Calling the STMLOAD.OBJ
13. Notes on STMLOAD.OBJ
14. The STMIK020.OBJ
15. Calling the STMIK with Assembler
16. Calling STMIK from C or Pascal
17. Notes on STMIK
18. Bugs?
19. Quick function reference
20. How to contact the author and get Scream Tracker related stuff
21. Silicon Dragon information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. About the STMIK and this documentation
The current release of STMIK is a beta one (as the version
number states). I'm releasing this kit for several reasons
before it's finished. First of all the final kit can't be ready
before Scream Tracker 3.0 is, for they should naturally be
compatible. Because the ST3.0 is late, and MANY have been asking
about a kit such as this I've finally decided to make it
available. Because the STMIK is a beta one, I strongly suggest
(and demand :-) that you will not distribute STMIK modules
(dealt with later). This is because the STMIK uses special
beta-3.0 modules, which differ from both of the current module
format and from the final ST3.0 format. This documentation is
probably far from being error-free and well-arranged for it's
done in a hurry, but you should get along pretty easily though.
You will get a lot of help from the source codes included.
Try making changes and testing your ideas, that's the best
way to learn.
2. License
You are free to use the STMIK in your own programs if, and only if
the following requirements are met:
o The program using STMIK is NOT commercial. Also Shareware is counted
as commercial software.
o It is mentioned in either the program itself or in its documentation
that the program in question uses the "STMIK02"
o STMIK itself is not modified in any way
You are free to use the Future Crew Demo routines in your own programs
if, and only if the following requirements are met:
o The program using the routines is NOT commerical. Also Shareware is counted
as commercial software.
o Credits are given to the Future Crew for the sourcecode used.
o The demo look/feel is NOT duplicated (for example only texts/gfx are
changed)
The STMIK itself has been released into the Public Domain so
feel free to redistribute this package, but DO NOT CHANGE ITS
CONTENTS. All the documentation and files must be in their
original form. You may NOT add or remove any files!
3. Future Crew demo included
The STMIK includes a Future Crew Demo as an example on how to
integrate Scream Tracker music into demos or other graphically
intensive applications which require smooth operation. The
SOURCE CODE for the demo is included in the package! The demo
requires a VGA compatible graphics adapter. You are free to use
the sourcecode in your own programs accoring to the license. You
must not, however, use the demo itself. Practically this means
that routines can be reused, but using the demo itself and
adding/modifying routines to make the demo look/feel slightly
different are prohibited. The FC doesn't want lamers to take
advantage of this source code; it's intended for serious coders.
4. Scream Tracker V3.0
The ST3.0 should be finished during the summer '91, though it
will probably be late as the past has shown. The playing
routines included in the STMIK are from the current ST3.0 and
they are debugged and tested, so they should be ok. (what's
missing from the ST3.0 is proper editing functions and adlib
support plus all kinds of minor niceties). It's not sure yet
how the Scream Tracker V3.0 will be distributed, but all
registered users will get a special update offer.
5. STMIK module format
The STMIK uses a special beta-V3.0 module format. Due to the
module formats beta nature, the current STMIK uses a .STX
extension instead of the normal .STM. I'm not intending to do
a STX->STM converter, so treat STX as the format to be
used in finished programs, NOT as a format to be used in
distributing modules. A program called STM2STX is included,
and it'll convert STM modules to the STX format for usage
in your own programs.
6. How to make music for STMIK?
You can make .STM files with the Scream Tracker, and then
convert them to the .STX format for inclusion in your programs.
See the STREG.DOC for information on how to register the
Scream Tracker. By doing so you'll be able to make your
own custom musics to match your program! If you've never
seen the Scream Tracker, try finding a demo version of
the shareware program. See the end of the file for how
to find ST and related utilities!
7. Limits of the current STMIK
The current STMIK is 'not as good' as the Scream Tracker for it
supports less output devices etc. This due to the new routines
used which aren't yet complete. The player supports ONLY
SoundBlaster, thought support for other cards will be added
in the next STMIK's. The player should be 100% compatible with
all the modules. In fact, the player supports several ProTracker
commands the newest Scream Tracker yet does not. It is also
many times faster than the old ST. There are some incompabilities
though; vibrato is divided like in new Amiga trackers. This
means all vibratoeing will be only half as big as in old ST.
Also some timing/sliding has been fine tuned to match
Amiga exactly, so it differs a A LITTLE from the old ST, though
generally you won't be able to know the difference.
8. How to use the STMIK
There are two object files in the STMIK. One of them is the actual
player (STMIK020.OBJ) and the other one is a stm loader (STMLOAD.OBJ).
Both object files should be linked with your program. The can be
called from either C or Assembly. Take a look at the make batch files
MAKED.BAT and MAKEP.BAT to see how the linking is done. Remark that
ALL routines in the STMIK are in LARGE memory model. Calling them
from other memory models may crash the machine.
9. Examples
There are two examples distributed with the STMIK. The C example
is a player routine PLAY.EXE (which is created from the file
PLAY.C) which can play both .STM and .STX modules. The Assembler
example is the Future Crew demo mentioned earlier. Both of
the programs use STMIK for sound. Feel free to enhance the PLAY.C
and add features to it to suit your needs. Remember give me
credits for the original source code though.
10. How to compile the examples
The Future Crew demo is all in assembler (MAIN.ASM,DEMO.ASM,
GRAP.ASM, INIT.ASM, TEXT.ASM, and MISC.ASM), so you only need
MASM or TASM and either LINK or TLINK. I have used TASM and
LINK. (pretty weird combination?-) Actually only MAIN.ASM is
compiled, the other ASM files are included into it. The ASM
file division is mainly used to divide the routines into
separate categories. Anyway, you can compile the demo by running
the MAKED.BAT NOTE that the Future Crew demo need a data file
MENTAL.FC which contains graphics and sound data. The data file
was created with many different tools, so you cannot modify it
with the STMIK, but then again, you shouldn't either! The
PLAY (PLAY.C) is written with Microsoft C, and I haven't been able
to test it with Turbo C, but it might work. Feel free to experiment.
You can compile the PLAY with a batch file MAKEP.BAT
11. The STMLOAD.OBJ
The STM loader is designed for people who wish to make STM players,
a STM jukebox or something like that. Please not that the STMLOAD.OBJ
is not as good as the STM2STX.EXE which will convert .STM modules to
.STX modules, for it loads the STM directly to memory and converts
it in a fly. As a result to the differencies in the formats, a module
loaded with STMLOAD will take more memory (though not much) than a
module converted and then loaded as an .STX. Also the STMLOAD creates
multiple memory reservations for the module, and the to free the
memory taken by the module, you must call STMLOAD's own routine designed
for it. Thus you can only load one STM at a time. This is of course
a pretty serious limit, but if you are making a player etc. it
shouldn't matter. For your own programs (games etc.) you should use
preconverted STX modules which you can load to the memory as you
wish.
12. Calling the STMLOAD.OBJ
The STM loader has two C functions you can call. The one that
loads a module is: stmik_loadstm(filename) whose parameter is
naturally the filename of the stm you wish to load. The other
routine is stmik_freestm() which frees the memory taken by the
previously loaded stm. Both routines can naturally be called
from assembler with standard C calling convention. See the
PLAY.C source file for examples. If you want to call the
C routines from Assembly take a glance at your Assembler
users guide (you have one, right?). Anyway, I don't think
anyone is going to make a player with pure Assembler, so
I hope you'll be happy with the C routines.
13. Notes on STMLOAD.OBJ
Do not attempt to free the memopy taken by the stmik_loadstm
by normal means. This will corrupt memory. Also loading a
module twice without freeing the first one will create problems.
stmik_loadstm returns NULL if the module loading was failed.
14. The STMIK020.OBJ
This is the main player intended for games, demos etc. software
using music. The player takes aproximately 30K of memory (and
also 30K of space in the EXE file, but most of this space is
pure zero, so using Microsoft EXEPACK or LZEXE or similar packer,
the EXE size can be mad a lot smaller. The STMIK can be called
from either C or Assembly in simple routines. It can probably
also be called from Pascal, if you specify it's routines use
the C calling convention.
15. Calling the STMIK with Assembler
You must define an extern procedure in your Assembler source.
This can be accomplished by placing the followin line in the
beginning of your source file (take a look at the MAIN.ASM):
EXTRN stmik_asm:far
Inside your source code you can simply call STMIK in the
following way:
mov ax,<function number>
[mov function data to other registers]
call stmik_asm
See the Quick Reference chapter in the end for functions
and their parameters.
16. Calling STMIK from C or Pascal
In Pascal you must remember to define the STMIK routines so that
they use the C calling convention. (you can create a pascal
header file by modifying the STMIK.H). In C you can simply
include the STMIK.H to get function prototypes. The actual
calling is done with C functions like stmik_playsong. See
the Quick Reference chapter in the end for function names
and their parameters.
17. Notes on STMIK
The STMIK takes a lot of interrupts to its control and
reprograms the DMA controller. The stmik_stopsong frees
all the resources the STMIK has taken (stmik_playsong
recaptures them). You MUST not use or modify interrupts
while in your program. If you need to have a timer interrupt,
capture it BEFORE you initialize STMIK. Of course you can
cheat the driver :-) (as Future Crew demo does) if you
use the polling mode. In this case you FIRST initialize
STMIK, then set polling mode, and then capture the
ints to yourself, remark though that after you call
stmik_stopsong, the interrupts will reset to the point
they were before the STMIK was initialized. Generally
feel free to experiment on 'illegal' stuff with the
STMIK, but don't count your program will work with the
future STMIK's if you do so.
18. Bugs?
Well, you'll probably find them - after all, this is
a beta version! In a beta-beta-version there was
a pretty serious bug with the IRQ handling (the first
MENTAL SURGERY released by the Future Crew had the
problem, though a new fixed version is now available).
Please report all bugs to the author to get 'em
fixed in the future versions.
19. Quick function reference
***** STMLOAD.OBJ - STM loader - LARGE memory model *****
char *module_loaded=stmik_loadstm(char *filename);
void=stmik_freestm(void);
See the PLAY.C for examples on how this routine
is used.
***** STMIK020.OBJ - STX player - LARGE memory model - *****
(in assembler, BYTE or WORD is returned in AL/AX, POINTER or LONG in DX:AX)
int status(0==ok)=stmik_init(int mode,int ioadd,int irq,int mixspd);
ASSEMBLER: AX=0, BL=[mode], BH=[irq], CX=[ioadd], DX=[mixspd]
[mode] is always 1 (which stands for SoundBlaster)
[ioadd] is SoundBlasters I/O address (default is 0x220)
[irq] is SoundBlasters IRQ number (default is 0x7)
[mixspd] is the speed at which the music is mixed (in Hz).
16000 is good (same as 12Mhz in Scream Tracker), 20000
is maximum and very good while 10000 or so is not so
good. The lower the number, the less processor time
is taken. THIS ROUTINE MUST ONLY BE CALLED ONCE IN THE
BEGINNING OF THE PROGRAM!
int status(0==ok)=stmik_playsong(char far *module);
ASSEMBLER: AX=1, BX=segment to [module]
[module] is a pointer to a .STX loaded into memory
(the STX must be contiquous in memory) or a pointer
passed by stmik_loadstm. THE MODULE MUST BE IN A BEGINNING
OF A SEGMENT; THE OFFSET PART OF THE POINTER MUST BE ZERO!
int status(0==ok)=stmik_stopsong(void);
ASSEMBLER: AX=2
this routine needs no explanations I think
int status(0==ok)=stmik_setpollmix(int flag);
ASSEMBLER: AX=3, BX=[flag]
[flag], when 0 means that the STMIK will take care of playing
automaticly and steal processor time by the aid of the timer.
This is the default. When [flag] is 1, the user must GIVE
stmik processing time. See the next routine.
void stmik_poll(void);
ASSEMBLER: AX=4
When pollmix[flag] is 1, the user must call the stmik_poll
AT LEAST 10 TIMES A SECOND. It's not important how often
the STMIK is called. You can call it when ever convenient,
even at irregular intervals, as long as you call it often
enoug. If you have too long spaces between calls, the sound
seems to repeat like a broken record :-)
int songpos=int stmik_songpos(void);
ASSEMBLER: AX=6
This routine returns the position the song currently is so
that the Order which is being played is (songpos mod 256)
and the Loop (how many times the music has been played) is
(songpos/256). Remark that the songpos returns values a bit
too early; practically the value returned by songpos is about
1/4 seconds before the music actually IS in the spot the songpos
said it would be! (things should never be too ease you know)
char far *pointer=stmik_nequinfo(void);
ASSEMBLER: AX=5
This routine returns a far [pointer] to a note equalizer info
struct. It's a bit complex to explain, so look at the demo
sourcecode to get a hang of it. The bars on the screen
bottom in the Future Crew demo are done with this routine!
20. How to contact the author and get Scream Tracker related stuff
You can either send me a letter, or call the Silicon Dragon BBS,
which is the main source for all ST related stuff! If you call
the Silicon Dragon, leave the messages to the Scream Tracker
Echo area (which is also available in other BBS'es) for I'll
get them from there faster! All comments and ideas are welcome!
Authors contact addresses:
By mail: By modem:
Sami Tammilehto Silicon Dragon, 24h
Korikatu 8 Phone: +358-(9)21-500318
SF-20780 Kaarina Fidonet: 2:222/101
Finland Username: SAMI TAMMILEHTO
21. Silicon Dragon information
You got these brilliant files from:
Silicon Dragon CBCS 24H +358(9)21-500318
Hardware: 386/25MHz
150MB + 113MB HD
Software: VM386 (Great Multi-Tasking soft.)
Maximus 1.02 Enhanced (BBS)
Location: Turku/SF (Finland)
Home of ScreamTracker and other nice softwares!
You can also contact FC from here.
How 2 contact SysOp by network's
FidoNet......: JANI LAAKSO @ 2:222/101 (Or 2:222/152)
6-)NET.......: TRI/JANI LAAKSO
InterNet.....: JANI.LAAKSO@f152.n222.z2.FIDONET.ORG
UUCP (bang)..: ...!fuug!casino!222!152!JANI.LAAKSO
