Introduction
Welcome to the STORM Developments/GBP Software STOS basic and compiler extensions. Many thanks for your interest in this program, and thanks also for your registration fee. Your details have been placed in our registration database, allowing us to keep track of registered users and also send free program updates to those who want them.
We are sure that you will enjoy using the compiler version of the extension, and also hope that your programs will now be enhanced because of the use of GBP.
We would like to hear from you in the future to keep in touch with how you are getting on, solve any problems that you might have, or listen to any ideas that you may have about future extensions. Please do not hesitate to get in contact with any of the GBP team.
Thanks
Before we begin, I and the rest of the GBP team would like to thank a couple of people and publishers who were a great help during the writing of this extension.
Billy Allen: Thanks for Misty & The Missing Link, it really inspired us to get GBP finished. Many thanks for the letters, and I hope that I shall hear from you quite soon.
Steve Jarrett: Thanks for all the comments about the extension.
Rick Dunlop: Again, thanks for taking the extension in, and I hope you didn’t mind me sending you a new version every week. How are you going with the PC? What’s up?? Are your routines not fast enough to work on an ST????? (joke.. I think!)
Stephen Hill: Thanks for creating such a wonderful book called “The Game Maker’s Manual”. It was really useful while I was originally coding and finally debugging the extension. I hope you write a follow-up.
Sigma Press: Thanks for publishing Stephen’s book!
Abacus Software: Thanks for publishing the “Atari ST Internals” book. It should play a major part in any assembler or ST programmers book collection!
Disclaimer
Although this extension has been tested to it’s full abilities, GBP Software or any member of GBP Software cannot be held responsible for anything that may happen to computer equipment of any kind during the use of the extension. Basically, you’re on your own if it does go wrong!
Copyright
These extensions and accompanying documentation are the SOLE copyrights of GBP Software, and may not be ripped off, copied, sold without our prior knowledge, or be changed in any way, including the documentation. It is an offense to copy the compiler extension without written permission from GBP Software. The BASIC extension and the DOCUMENTATION are shareware and can be copied freely. The Shareware release may be used for a 30-day period before registration becomes necessary.
Remember, copying copyrighted material is a criminal offense. Please register this product to make sure that GBP Software will continue to produce great-quality STOS extensions in the future.
Thank you for your attention.
Neil Halliday.
The Commands
Well, here’s the bit you have all been waiting for: the commands! I must apologise at this point, as all the commands are not in any sort of logical order, but I will try to keep them together. I will also try to include demo programs where applicable.
NOTE: All addresses that are mentioned in this extension must be passed as actual addresses, as the routine will not work by simply passing the bank number. i.e., the extension will bugger up if you use…
Eplay 10,length(10),0,0,1As the routine will play from memory address 10 instead of bank 10. So you will have to call it like this…
Eplay start(10),length(10),0,0,1Ok??? For more information about that, consult your STOS manual.
MISCELLANEOUS COMMANDS
LIGHTS ON
Syntax: Lights On
Description: This is a very nice command that will turn on the drive lights for disk drives A & B. This command will allow you to produce effects that have been seen in demo screens where the drive lights pulse to a piece of music and has also been seen recently at the beginning of Crack Art.
LIGHTS OFF
Syntax: LIGHTS OFF
Description: The opposite of the last command. You have read the last command, haven’t you? As mentioned about pulsing the drive lights to music, here is the routine:
10 dreg(0)=1 : call 10 : rem * Call music Init
20 loke $4d2,start(10)+8 : rem * Install on VBL
30 if psg(8)>12 then lights on : else lights off
40 wait vbl : goto 30
50 :
60 loke $4d2,0 : bell : rem * Turn music offThe above routine will work with a MAD MAX music file loaded into bank 10, but if you don’t have any MAD MAX music you can use the normal STOS music (VERY CRAP!) by making these amendments:
10 rem * Routine to flash lights to CRAP MUSIC!
20 music 1For more information about the PSG command, turn to your manual pages 265 & 266 (Ha! That will fool all you people who are using a copy of STOS!!! Buy the original, you SAD people!).
PREADY
Syntax: X=PREADY
Description: This function tells you if the printer connected to the Parallel port is online or not. The variable X will contain the status of the printer, and can only take 2 forms.. TRUE (-1) if the printer is on line and ready to receive data, or FALSE (0) if the printer is set to anything else. Try the following small program to test this out:
10 X=pready
20 if X then bell
30 goto 10This program will test the printer, and if it is online, it will sound the STOS bell repeatedly; otherwise, if your printer is offline, nothing will be heard. For more information about true and false statements, consult your STOS manual, page 227.
EVEN
Syntax: X=EVEN(NUM)
Description: The even command will return if the input value is even or odd. The output variable X will contain true if NUM was even or FALSE if NUM was odd:
10 input A
20 if even(A) then bell : else boomSETPRT
Syntax: X=SETPRT(VAR)
Description: This function allows the printer configuration to be set. The variable VAR is a bit vector with the following meaning:
| Bitnumber | Off (0) | On (1) |
|---|---|---|
| 0 | Dot Matrix | Daisy Wheel |
| 1 | Monochrome | Colour |
| 2 | Atari Printer | Epson or Compatible |
| 3 | Test Mode (DRAFT) | Print Mode (NLQ/LQ) |
| 4 | Centronics Port | RS-232 Port |
| 5 | Continuous Sheet | Single Sheet |
| 6-14 | Reserved | Reserved |
| 15 | Always 0 | Always 0 |
As an example, the following statement would set the printer to:
- Dot Matrix Type
- Monochrome
- Epson or Compatible
- Test Mode (DRAFT)
- Centronics Port
- Continuous Sheet
X=setprt(%000100)The bit number, as you will have noticed, is binary, with bit 1 being on the far right. This binary number can be substituted for the decimal equivalent, so the command:
X=setprt(4)Is equivalent to:
X=setprt(%000100)The printer’s parameters can be read by passing -1 as the input variable. The value will be returned as X.
SPECIAL KEY
Syntax: X=SPECIAL KEY(I)
Description: The special key command sets or returns the current status of the special keys (i.e., Shift(s), Alt, Ctrl, and Caps). The status can be set by passing variable I as a positive integer, and by passing I as -1, the status can be read.
10 print "Current Status :"; special key(-1)The value returned by special key is an 8 bit value that is read in the following way:
| Bit | Meaning |
|---|---|
| 0 | Right Shift Key |
| 1 | Left Shift Key |
| 2 | Control (CTRL) Key |
| 3 | Alternate (ALT) Key |
| 4 | Caps lock |
| 5 | Right Mouse Button (CLR/HOME) |
| 6 | Left Mouse Button (INSERT) |
| 7 | unused |
If the bit is set, then the button is active.
HCOPY
Syntax: HCOPY X
Description: The annoying thing about STOS is the fact that no matter how good your games, demos etc.. are, they can always be interrupted by the system HARDCOPY command (ALT & HELP). Well, that is no longer the case. This command will turn off and turn on the system Hardcopy! By passing X as 1, we turn ALT & HELP on, and by passing X as 0, we turn ALT & HELP off!
10 hcopy 0 : rem Turn HARDCOPY off
20 wait key
30 hcopy 1 : rem Turn HARDCOPY onFile Commands
D CRUNCH
Syntax: D CRUNCH ADDR
Description: The D CRUNCH command allows you to unpack files compacted with the most popular packers around (up to now). By passing ADDR as the address of your compressed data, it will be decompressed by the recognised file format. The extension can unpack several different formats, which will be shown in a little while, but before we do, a little word of warning! The de-pack routines are a0 -> a0 routines, which means that any compressed data will be overwritten during decompression. It also means that memory banks will have to be reserved for the original file length of the data; otherwise, you face overwriting some data that you may need and, in some cases, even crashing your ST.
PAKTYPE
Syntax: X=PAKTYPE(ADDR)
Description: All recognised packer formats have a special header to tell them from one another.. This command will return in variable X, what packer the data at address ADDR was compressed with. If the packer type is not recognised then the return value will be 0. Otherwise the value stands for:
| Value | Packer |
|---|---|
| 1 | Speed Packer 2 |
| 2 | Atomik v2.5 |
| 3 | Ice v2.11 |
| 4 | Automation v5 |
| 5 | Ice v2.40 |
| 6 | Fire v2.0 |
| 7 | Speed Packer 3 |
PAKSIZE
Syntax: X=PAKSIZE(ADDR)
Description: This command returns the uncompressed size of the packed file located at address ADDR.
FSTART
Syntax: X=FSTART(N,ADDR)
Description: This command is used in conjunction with a GBP file bank, and returns the position in memory of file N, located in the GBP filebank that can be found at address ADDR. A GBP bank allows many files to be stored in just one memory bank, which programmers will understand that means loads of data loaded, and still loads of banks left.
FLENGTH
Syntax: X=FLENGTH(N,ADDR)
Description: This command will return the length of file N, found in the GBP bank located at address ADDR.
FOFFSET
Syntax: X=FOFFSET(N,ADDR)
Description: This command returns the offset of the file N, compared with the start of the GBP file bank. i.e file two may by 1024 bytes from the start of the bank. NOTE: The GBP bank builder accessory can be found along with the extension files.
Graphics Commands
FASTWIPE
Syntax: FASTWIPE ADDR
Description: This is a very fast version of the STOS cls command. It will clear 32000 bytes from the address specified by ADDR. It can be used to clear memory banks or screen addresses (eg. physic). However if you are clearing a memory bank you must pass the parameter as the start of the bank. e.g..
10 fastwipe start(BNK)Where bank BNK is a reserved screen bank, if you just want to clear a screen address then substitute start(BNK) for the address of the screen. e.g..
10 fastwipe physicYou may have seen the wipe command in the The Missing Link extension? Well, no we haven’t ripped/stolen the routine, it was mine in the first place and I sent it to the chaps, I never got credited for it (snarl), anyway.. This new version is even faster (Shove that up your jumper Top-Notch! haw haw!).
ELITE UNPACK
Syntax: ELITE UNPACK ADDR1,ADDR2
Description: This command will allow you to unpack a Degas Elite compressed PC? pictures. You must set up a normal STOS screen bank to hold the resulting unpacked picture.This routine SHOULD work in all three resolutions, but I haven’t tested it yet. Try this small routine:
10 key off : curs off : mode 0 : hide
20 reserve as screen 10
30 reserve as work 11,(length of PC? file)
40 bload "FILENAME.PC?",11
50 elite unpack start(11),start(10)
60 screen copy 10 to physic
70 get palette(10)This will unpack the picture from bank 11 to bank 10, and then display it on the screen. Once the picture has been unpacked, the palette can then be grabbed in the normal way. Screens can also be unpacked directly to the screen, i.e.
elite unpack start(11),physicThe palette for the picture can then be installed by using the command:
get palette(physic)TINY UNPACK
Syntax: TINY UNPACK ADDR,ADDR2
Description: This command does exactly the same as the ELITE UNPACK command, except that it will unpack a TINY compressed image.
CA UNPACK
Syntax: CA UNPACK ADDR,ADDR2
Description: Again this command is the same as ELITE UNPACK & TINY UNPACK, although this routine will packed an image file saved in the Crack Art format (CA?).
CA PACK
Syntax: X=CA PACK ADDR,ADDR2,PAL,MODE
Description: This command is to be used in conjunction with the CA UNPACK command, and will actually create a compressed Crack Art image file from a standard STOS screen bank. ADDR is the source image, ADDR2 is the destination for the compressed image, PAL is the address of the palette data to be used, which will usually be ADDR+32000, and MODE is the pictures screen resolution (0=Low, 1=Medium, 2=High). The value returned is the length of the compressed picture file. This routine should help you sort this out:
10 reserve as screen 10
20 L=ca pack physic,start(10),physic+32000,0
30 bsave "picture.ca1",start(10) to start(10)+LThis routine will compress the current physical screen into bank 10, and then save it. The variable L contains the compressed length of the image file.
SETPAL
Syntax: SETPAL ADDR
Description: The SETPAL command will install a new palette that is located at address ADDR. It is useful for storing large palette changes in a memory bank, and then setting them when every they are needed. The format for the data is just the standard degas format, in that it is 16 words, each word representing the colour 0 – 15.
10 reserve as work 10,32 : mem=start(10)
20 restore 80 : for lp=0 to 15 : read(x)
30 doke mem,x : mem=mem+2
40 next lp
50 :
60 setpal start(10) : wait vbl : end
70 :
80 data $000,$111,$222,$333,$444,$555,$666,$777
90 data $000,$111,$222,$333,$444,$555,$666,$777This routine will copy some values into memory bank 10, and the set the palette from it.
BCLS
Syntax: BCLS ADDR,SCAN
Description: The BCLS command, will erase a set amount of scanlines on any desired bit plane of the screen. The address of the screen is passed in ADDR, and the number of scanlines to erase is passed in the variable ADDR:
10 bcls physic,10This will clear 10 scanlines on plane 1 of the physical screen. The other planes of the screen can be selected by increasing the screen address by 2.
+0 = Plane 1
+2 = Plane 2
+4 = Plane 3
+6 = Plane 4
MIRROR
Syntax: MIRROR OPT,ADDR,SYPOS,ADDR2,DYPOS,NUM
Description: The mirror command is quite powerful, in that it can mirror parts of the screen, in three ways.. Normal, Halved or Doubled. The mirror option is passed in the OPT variable, and can take the form:
1 = Normal
2 = Half Copy
3 = Double Copy
Variable ADDR is the source address of the image, and SYPOS is the source Y pixel offset. ADDR2 is the destination screen address, and DYPOS is the destination Y pixel offset. NUM is the number of lines to mirror. i.e.
10 mirror 1,physic,0,physic,100,32This will mirror the STOS key box to the middle of the screen… Try putting it into a loop, and see what happens when you move the mouse over it!
STE Commands
DAC VOLUME
Syntax: DAC VOLUME VOL
Description: This command will set the main volume of the STE sound output to VOL. The input value can take the form 0 – 40 (40 being the loudest).
10 rem ** STE fade out
20 for LP=40 to 0 step -1
30 for LP2=0 to 15 : wait vbl : next LP2
40 dac volume LP : next LPTREBLE
Syntax: TREBLE TREB
Description: This command sets the amount of treble that is output from the STE sound. TREB can take the form 0 – 12 (0 = -12dB, 6 = 0dB, 12 = +12dB).
BASS
Syntax: BASS BAS
Description: Same as above, but sets the amount of bass instead.
EPLAY
Syntax: EPLAY STRT,LENGTH,SPEED,MODE,PLAYMODE
Description: EPLAY allows hardware sample playing on STE machines, or machines that have the extended sound capability. STRT is the start address of the sample, and LENGTH is the length of the sample. SPEED variable sets the replay speed of the sample, which can be:
0 = 6.258 kHz
1 = 12.517 kHz
2 = 25.033 kHz
3 = 50.066 kHz
The MODE variable sets mono/stereo playback of the sample.. 0 = stereo, 1 = mono. And finally, PLAYMODE can be.. 0 = stop, 1 = play once, 3 = loop forever.
Although the sample replay can be stopped using the EPLAY command, I have also added an ESTOP command, that can also be used to stop the sample.
ESTOP
Syntax: ESTOP
Description: This will stop the hardware sample replay interrupt, and stop ANY sample that is playing under STE hardware.
EPLACE
Syntax: X=EPLACE
Description: This command does the same as the SAM PLACE command that already exists in STOS, however, it returns the address in memory that is currently being played by the STE hardware. It can be used for doing all sorts of nice effects including frequency meters or oscilloscopes:
10 rem ** Oscilloscope routine
20 key off : curs off : hide : mode 1
30 :
40 eplay start(10),102400,1,0,3 : rem ** Play sample, looping
50 :
60 repeat : fastwipe physic
70 for LP=0 to 50 : X=peek(eplace)
80 if X>128 then X=X-255
90 X=X/8 : plot LP,100+X,1 : rem ** Plot sample byte
100 next LP
110 wait vbl : until falseJAR
Syntax: X=JAR
Description: This command will return if a “Cookie Jar” exists on the computer. If a “Cookie Jar” does exist then true (-1) will be return, else 0. This command is to be used in conjunction with the following command:
COOKIE
Syntax: X=COOKIE(STR$)
Description: This command will read the information on the cookie STR$. STR$ must be passed as one of the official Atari Cookies, otherwise no value will be return. A list of all the Cookies and return values follow:
| Name | Value |
|---|---|
| _CPU | The number here is the decimal value of the last two digits of the processor present in the machine, indicating which CPU of the 68000 family it is: 00,10,20,30. For instance the value 30 represents 68030 processor |
| _VDO | The high word of this cookie contains a number from 0 to 2 which indicates what type of video shifter is fitted: 0 = Standard ST video shifter 1 = STE video shifter 2 = TT Graphic chip |
| _SND | Here it is the bits which tell us about the sound hardware. Bit 0 set indicates the presence of the Yamaha sound chip, bit 1 of the DMA sound chip. |
| _MCH | This cookie also uses the high word, so that the low word can be used for version changes, and the value describes the overall machine: 0 = Standard ST 1= STE 2 = Mega ST 3 = TT |
| _SWI | This cookie is used to indicate the positions of the configuration switches on Mega STE’s and TT’s. At present these switches are unused. |
| _FRB | This longword value will be the address of the FASTRAM buffer, or 0 if no FASTRAM buffers are fitted. This cookie is not found on normal ST & STE machines. |
10 if jar then X=cookie("_CPU")
20 print "You have a 680";using "##";x;" Processor"XPEN
Syntax: X=XPEN
Description: This command returns the x screen position of the STE light pen/gun.
YPEN
Syntax: Y=YPEN
Description: This command returns the y screen position of the STE light pen/gun.
10 repeat
20 if fire then plot xpen,ypen : shoot
30 until falseThat’s All Folks!
Yes, that’s all the commands in this great extension.. So go away and have some fun using them.
Bonus!
You may have noticed that there is an extra basic extension on the disk. Well it’s the follow up extension.. GBP II, and this time it’s going to be deadly. The extension is very much like the blitter extension, being in a very early stage. There is no documentation as of yet (it is currently being written). I will however go over a few of the command within this text file so that you can get the feel of the extension and get to use it a little bit.
The extension itself is primarily for use on STE machines, as most of the command are based around the specific hardware. Although some commands will actually work on older ST machines, but it is not really worth running. The commands themselves range from accessing an Atari powerpad/Jaguar controller (both ports!). Centronics/Parallel joystick routines, screen savers, and hardware scrolling.
Credits
Coding and Research : Neil Halliday
Some Commands : Bruno Azzara
Ideas and Design : Neil Halliday, Bruno Azzara & Geoff Harrison
Documentation: Neil Halliday
Demo Programs : Neil Halliday
Other GBP Products
Look out for these other exciting products from GBP, available now from all good public domain libraries.
Slider – a brilliant PD sliding puzzle game with 3 levels.
Rubik’s Magic Strategy – A PD conversion of the brilliant Rubik’s Magic Strategy
Go Moku – A great conversion of the ancient Japanese board game. This program is licenseware, and is only available through Budgie UK.
Playmate II – an interrupt GEM music player that can recognise up to 28 different music formats, and allows you to play music while you work.
Contact Addresses
FOR OBVIOUS REASONS, THIS SECTION HAS NOW BEEN REMOVED FROM THE MANUAL
Neil can also be contacted through the Ad.Lib BBS.. Tel 0191-370-2659. The board is open 24 hours a day, and goes 2400-14400 baud.
Thanks for your interest in this program, and I hope you have lot’s of fun using and exploring the possibilities of STOS basic and GBP.
Neil Halliday and the rest of GBP Software team 1994/1995.
GBP EXTENSION (C)GBP SOFTWARE 1992-1995.
THE END ! ! ! !
