GFABASIC tutorial by Simon Sunnyboy / Paradize

de **simonsunnyboy** » Sam 6 Juin 2009 07:54

GFABASIC tutorial by Simon Sunnyboy / Paradize

Welcome
Welcome to my little GFABASIC tutorial for the Atari ST range of computers.

I wrote this years ago and it's old location was http://home.tu-clausthal.de/~ifmar/gfabasic/
However that site is dead for years and instead of loosing the onlineversion of this tutorial, I decided to put it here.

This tutorial will introduce you how to use GFABASIC, how to code a GFABASIC program, how to run and debug it. Some additional knowledge about the Atari ST hardware will be included as well.
The main focus will be GFABASIC and its constructs, not how to program a game or demo with GFABASIC. However after studying this tutorial, you should be able to use this knowledge and to be able to apply it for a game or demo project.
I hope you have as much fun using the knowledge as I had acquiring it over the years.
This tutorial is incomplete as it is and I give no warranty. I cannot guarantee it will be ever finished.

de **simonsunnyboy** » Sam 6 Juin 2009 07:59

Documents and Downloads
Here you can download some interesting documents and stuff for GFABASIC.

de **simonsunnyboy** » Sam 6 Juin 2009 08:02

Introduction
So you have decided to read this tutorial?
Ok, so I either assume you already know about GFABASIC or not. Read on if not.

"What is this GFABASIC this guy is talking about?" you may ask yourself?
The programming language BASIC has been around since the 1960s. BASIC is an acronym and it stands for Beginners All Purpose Symbolic Instruction Code. A programming language that is easy to use for a wide range of projects by anyone to bring it to the point.

GFABASIC is a dialect of this but it is not a BASIC in its original form. It is more a mix of classic BASIC with structured languages like PASCAL and Modula-2.
But wait a minute - before GFABASIC there was more. Let me go back into 1985. The then famous computer company Atari launched its best coup ever in 1985, the Atari 520ST. A miraculous computer in its time, offering a wealth of graphic abilities, floppy disks, harddrives and a price that was unbeatable. Called the Jackintosh because the ST clearly was intended to be an answer to Apple's Macintosh, the ST had it all. Its sound seemed poor in the view back but the computer was intended as an office machine like the Macintosh or the then poor PCs. Coming with a graphical environment in ROM, it surely was a dream machine in 1985.

Entering BASIC, the ST came from the start with a very poor implementation of the original BASIC language called ST-BASIC. This implementation used the graphic environment GEM of the ST but it suffered from a poor editor, old fashioned code with linenumbers, very slow execution of its BASIC programs and buggy implementation. In 1985 there was nothing else so the few ST users had to use it. Frank Ostrowski from Germany had already written a better BASIC implementation for the 8-bit range of computers by Atari. He moved on to the ST and decided to do a better ST-BASIC. This started the GFABASIC project.
GFABASIC saw the day of light in 1986, roughly a year since the ST hit the market. The ST was already highly popular in Europe, especially in Germany, mainly because of its price and wealth of features. So the better ST-BASIC had a good start. It sold well and people would use it. But not only the fact it was the second and better BASIC, a main factor for the ongoing popularity of GFABASIC is its qualtity. From the start GFABASIC came with a rather bugfree interpreter, a wealth of commands, options and very good execution speed of its programs. Especially the ability to fully use and hook into the Atari ST's OS, TOS with its graphical components GEM and VDI, hit the street and quickly lots of decent software titles appeared in the public domain and as typeins that showed what GFABASIC could do. Time would show that even fast action games and demos are entirely possible in this dialect of a language that was already considered slow and clumsy in its time. Try the game Roger or the GFA demos by The Overlanders to see what I mean.

In short, it is still worth the effort to learn and use GFABASIC if you are into Atari ST computers, either via emulation or with a real machine.

GFABASIC features
GFABASIC has a lot of interesting features which help in developing a program.

Interpreter vs Compiler
GFABASIC is interpreted by default. This means the socalled interpreter takes each line of your code and looks what to do with it. The other way is the compiler which will take your code once, translate into directly executable machine code (for the Motorola 68000 microprocessor in the GFABASIC case) resulting in a more speedy program execution as the step for command lookup does not appear anymore. The compiled program just can be executed outofthe box.

The advantage of an interpreter is that you can directly test and run your program without running a compiler first. In GFABASIC you just type your code into the builtin editor and then click RUN to execute your program. This is extremely helpful while developing but ofcourse a compiler is available as well allowing you to produce rather fast machine code from your GFABASIC program.

Versioning
Either you are convinced by now or not. If so, you should take care of the different versions of GFABASIC. Although compatible in general, a few things should be mentioned. First of all avoid GFABASIC v1.x as that one has no compiler available and lots of useful commands are missing. V2.x can be considered but still commands are missing in particular to access the OS and a few faster graphic routines.

If at all possible, use a v3.0 minimum. I personally use v3.6TT and this tutorial is based upon that version of GFABASIC. If a particular command does not work, it is a safe bet to upgrade your version of GFABASIC first.

GFABASIC saves its programs in a special tokenized form that cannot be read with a normal texteditor. It is not compatible with other versions of GFABASIC as well. There are GFABASIC files with .BAS and .GFA extender. The .BAS variant is used by v1.x and v2.x, .GFA by v3.x. But a GFABASIC file with .GFA extender cannot be necessarily read by say v3.5 if it has been saved with v3.03. Therefor to exchange GFABASIC code, save your GFABASIC programs with .LST extender with the SAVE,A option as plain ASCII text. For local use on your floppies or harddisc saving as .GFA is ofcourse valid. Just don't mail or attach a .GFA file but go for a .LST instead.
.LST files saved from GFABASIC v1.x can be fully run from v3.6 as GFABASIC is downward compatible to itself. However a .LST saved from v3.5 will not necessarily work in v1.0.

de **simonsunnyboy** » Sam 6 Juin 2009 08:06

The Environment
Before you start coding, you should familiarize yourself with the GFABASIC system itself. Don't worry, at the end of this chapter you will write your first GFABASIC program. So let's start with simple things.
From now on I assume basic knowledge of the Atari ST computer, how to handle the mouse, how to navigate menus and dialog boxes and howto run programs from the desktop.

Getting into GFABASIC
Before coding you need to get into GFABASIC for obvious reasons. Simply doubleclick GFABASIC.PRG and the ST should load the interpreter. You should get a picture like this one after loading GFABASIC:

gfaeditor.png

This is your main working environment, the GFABASIC editor. Here you are going to write your programs, save them to disk and finally run them.

You can run the interpreter from any screen resolution but keep in mind that without special measures your program will run in the initial one. The editor however will switch into ST-MED if run from ST-LOW. Above I've started GFABASIC from ST-LOW. In the editor you won't see that but in the direct mode or while running your program you will see the desktop resolution.

Now relax - you will discover that you can use the mouse as normal. The green (or in ST-HIGH black) cursor awaits you to type commands. If you are used to other BASIC dialects like STOS note that you do not need to precede your commands with line numbers. Infact the GFABASIC editor will complain if you try to.

The button bar
As you can see the top of the screen is claimed by a button bar in 2 rows. Don't worry - it will not be visible when you run your programs.

The main actions are accessible from there. Simply click an action with your mouse to activate it. But much more easy is the use of the function keys. If you count the actions, you see 20 different actions in this button bar. Press F1 to F10 to activate them. Each column on the bar stands for one F key.
You wonder how that will work? 10 F keys and 20 options? Piece of cake - if you press an F key alone, it will activate the function of the lower bar.

Press F1 to activate LOAD for example. To access the functions of the upper bar hold the SHIFT key and press then the according F key. Shift+F3 will quit the interpreter to the desktop for example. Click on the clock to set the time. The number below the clock shows you the current line number in your program.
For full documentation of the various options see a GFABASIC manual. I'll only cover options as needed by this tutorial here.

Basic editor usage
Move around the editor with the cursor keys. Most other editor keys like Clr/Home will act as you thought so basic editing is easy and straight forward. Click on INSERT or press F8 to toggle between insert and overwrite mode. Pressing Insert is special as it will insert a blank line to add code instead of toggling insert mode.

Having typed some code you surely will save it to disk for later use. To save your current program, click SAVE or press Shift+F1. A fileselector will appear. Give a name for your program and click on Ok to save. The extension .GFA will automatically be added. If you have already saved your program under this name, GFABASIC will automatically backup your old file, giving it the extension .BAK, before overwriting with the new version.

If something went terribly wrong, you'll always have a .BAK to recover your source from.
To load your program again, click on LOAD or press F1. The fileselector will appear. Select the program you want to load and click Ok. Loading a program will erase the old one in memory so make sure to save your other program first.

A free quote by Roberta Williams of Sierra fame: "Save early, save often!" It is a wise step to save your work before running. If the ST crashes, you'll still have a copy on disk to recover your work. There is nothing more ugly than loosing the work of hours by forgetting to save it first.

If you want to save your work to share it on the internet, click on SAVE,A instead or press Shift+F2. This will save your whole program as ASCII text that you can easily mail or post on the net. GFABASIC will give a .LST extender to plain ASCII files and will not make a .BAK copy of old .LST files.

To load a .LST file, click MERGE or press F2. Select the .LST you want to load and of you go. MERGE is special in the way as it really merges. This means it does not erase the program in memory but it inserts the contents of the .LST file at the current cursor position. This allows you to build libraries and merge them when you need them. If you want to load a .LST that contains a complete program, make sure to do a NEW first to erase the old one in memory.

To erase the current program in memory, click on NEW or alternatively press Shift+F4. Click LLIST or press F3 to print your current code on the printer.
Click QUIT or press Shift+F3 to leave the interpreter. It will drop you to the desktop or the calling shell in some instances.

Your first GFABASIC program
Of course this tutorial uses the famous "Hello World" as the first program here. Type the following line of code into the editor. GFABASIC should not complain. If it does, check carefully for typing mistakes.

Code: Tout sélectionner: PRINT "Hello GFABASIC!"

Whew, that was easy. Your first GFABASIC program and now you are going to run it. Save it first. Then click RUN or press Shift+F10 to finally execute your program. This will make GFABASIC leave editor mode and execute your program. Having done this, the screen should look like this one:

firstprogram.png

Neat, huh? The box in the middle of the screen always appears when your program terminates as long you don't tell GFABASIC to return directly to the editor again. You will learn about that later on. Check the dialog and GFABASIC will drop you back into the editor.

While developing your program you can always run an even unfinished program. Make sure no logical errors or missing statements are in and you are safe to try out. This makes GFABASIC so nice to use. GFABASIC will detect errors while running and it will ofcourse complain to you.
This concludes your first lesson in GFABASIC. By now you should have learned how to type a program into GFABASIC, how to save and load it again and how to finally run it.

de **simonsunnyboy** » Sam 6 Juin 2009 08:10

Variables and data types
Welcome to the second chapter of my little tutorial. Today you'll write a few small programs that will do some simple calculations for you.

First let's learn about variables and how the computer deals with numbers.

Variables
As you probably already know, computers deal with numbers all around. All sort of data is encoded into numbers. Even this text you're reading or any text you enter into GFABASIC consists of all little numbers. To be able to talk to the computer, you must know how to talk with the computer numberwise.

Let's begin with a small example on number usage. No need to worry - all makes sense fast, just keep in mind that anything is a number. Imagine you want your computer to calculate a little equation for you. Let's assume the computer shall calculate the value of 5+5. An easy thing but soon you will want the computer to store such results for later use. And perhaps you will even want the computer not to add 5 and 5, but perhaps other numbers that you want to type in. So you must find a way to tell the computer where it can store results of computations and data in general. At this point socalled variables drop in. Think of a large cupboard with lots of little drawers in. Each drawer holds some data and has a name. Think of variables as if they were one of those little drawers in your cupboard. You can place your data in them and retrieve it by name.

Two problems need to be solved: you want an easy way to access your data and secondly the computer needs to know where to place this data. Luckily GFABASIC takes care of that. You simply give a variable a name and so specify the drawer where to place the value of the variable. You can then refer to it by giving its name in the place you want the value of the variable to be used. GFABASIC will automatically know where to store the data and how to deal with it. It is also important to tell GFABASIC what sort of data you want to store. You can have variables that store only numbers but also variables that deal with a character or a whole string, a line of text for example.

The following valid line of GFABASIC code will create a variable called x for you and assign it the value of 10.

Code: Tout sélectionner: x=10

You learn here 3 important things. First your variable has a name, x in this case, secondly you state that you want to do something with this variable, an assignment with the = sign, the last thing is what you want to do with this variable. You give it the value 10 here. Such an assignment will overwrite any old data that has been stored before in that variable.

As long as you don't assign a value to a variable, it will hold a default value, 0 in most cases.
Data types

Now how you see that this variable x stores a number? How does GFABASIC know that you want to deal with a number? Easy - by the way the name of the variable has been written. To distinguish between different ways of data types GFABASIC appends a special typing sign as a suffix to the variable name to distinguish between several ways to store data in variables. It is important that variables with a special suffix are different from those without.

The main data types you'll use in this tutorial are described in the following table.
basic data types in GFABASIC
variable types
suffix
example
usage

floating point number, short called float , 1,5 for example
none
x
in calculations where the fractional part of a number is important

integer (4 bytes long)
%
y%
everywhere where your numbers are always even or odd, without fractional (e.q. 5 instead of 5,5) Please note that a result from a float operation will be stripped of its fractional if you save it to an integer variable.

string
$
title$
use strings when you want to deal with textual data instead of numbers

boolean, used for truth values with only two values, TRUE and FALSE
!
flag!
to store truth values or results of boolean expressions or to set flags

GFABASIC can distinguish even more types of variables but I'll leave it up to the GFABASIC manual to tell you about them. You can solve 99% of all problems with the types above.

Code: Tout sélectionner: x=10.56 y%=4 stop_execution!=FALSE txt$="a short string"

This short piece of code creates 4 different variables of 4 different types and assigns values to them. As you can see it is fully valid to define a variable without a suffix. This will make it a floating point variable by default. Both types for storing numbers deal with the sign so the following is ofcourse valid in GFABASIC:

Code: Tout sélectionner: x=-15.4 y%=-4

More on strings and boolean variables later.

Variable naming
A short intermediate step is to tell you what names you can use for your variables. You can use all letters and numbers for your variable names. Spaces are not allowed but underscores inside the variable name. In general GFABASIC can distinguish upto 16 characters per name. GFABASIC limits you only in the following ways: a variable may not begin with a number or an underscore, only with letters. Avoid to name your variables like GFABASIC commands. It will work but it can also cause troubles while typing. As a rule, never use a GFABASIC command as a variable name.

Valid variable names look like the following:
x, auto%, lives%, bonus1%, x_1!, city_name$, debit

Invalid variable names look like this and GFABASIC will complain:
_blank, 1x, ?value%, 5s$, :invalid_variable_name

Always remember: begin your variable names with a letter from A-Z and you are on the safe side!

Arithmetics and calculations
Now that you know how you can tell the computer to store numbers in its memory and how to give them a meaningful name, you'll learn how to calculate with them. You remember my introductory example of adding 5 and 5? Well, let GFABASIC do that:

Code: Tout sélectionner: x=5+5 PRINT x

This will take 5 and 5, add both together and store the value in the variable x. The value of the addition will then be written on the screen. Having stored the value you can recall it at any time by using the variable x in a useful context like an expression or calculation.
Ofcourse you could have made this program a bit shorter by writing directly:

Code: Tout sélectionner: PRINT 5+5

But remember the educational value of the first one.

As you probably already guessed, GFABASIC will execute your program beginning with the first line. You will learn later on how to alter the execution flow. As a little exercise, switch both lines around and explain the result to yourself!

Ofcourse you are not limited to add plain numbers together. You can ofcourse use variables as well so try this:

Code: Tout sélectionner: x=6 y=3 z=x+y PRINT z

As you probably already guessed, this is the key to reuse your calculation results.
The part behind the = in the assignment line is called an expression. It can contain brackets and functions as well. Later on you'll be able to use such expressions as x+y in other contexts as well. A valid expression would be:

Code: Tout sélectionner: result=150/(x-(y*15.5))

Brackets control the order of execution. As GFABASIC does not stricly calculate multiplication before addition, you sometimes need to set explicit brackets that would be unnecessary in an algebra lesson. But always remember: an additional pair of brackets will make your expression more clear. So it is not bad if you have unnecessary brackets in your expressions.

Ofcourse you can use the old value of the same variable in an assignment to calculate its new value. Imagine you have a variable called multiplicator% that holds the value 1 and you want to add 2 to this:

Code: Tout sélectionner: multiplicator%=1 PRINT multiplicator% multiplicator%=multiplicator%+2 PRINT multiplicator%

You see it is rather easy to understand. Now experiment a bit. Let the ST do some calculations for you.

Progress check
As this chapter explained vital things for programming with GFABASIC, you should answer the following questions to yourself. If you still have problems, read the chapter again.

You want to assign the value 5 to a variable called joe. What code do you need to type into GFABASIC?
What's the difference between a variable called x and one called x%? Is there any?
Variable names ending with ! have the data type ... . They store .... .
What number would be contained in the variable x% after execution of the following code ? x%=1.5
Which of the following variable names are valid in GFABASIC? x%, y!, 45x, ublank_$, $$, $_, city$, xdebit, flag!
Write a little program that will add 3 float numbers and divides them through 70. Write the result on the screen.

This closes our second chapter. You have learned by now how to create and name variables in your own program. You should now know what values to store in what type of variable and how to do simple arithmetic with them. The term expression is not unknown to you and you are able to write multiline programs with the GFABASIC editor.

de **simonsunnyboy** » Sam 6 Juin 2009 08:14

Simple I/O
Great you're still there. Today we will learn how to do simple input and output operations on screen. This will allow you to make your programs interactive for the first time.

Printing data to screen
You actually already know a GFABASIC command to write data on screen. This command is PRINT. It is very versatile and you can extend it in various ways.

Syntax is simple, PRINT <data> where <data> is whatever sort of data you want to print on screen. That can be variables, numbers, the result of a calculation, a string or a mix of them all. You can even special commands to your PRINT statement for screen control such as cursor positioning. A few examples for the PRINT command can be found here:

Code: Tout sélectionner: PRINT 10+5 PRINT x% PRINT 10;20;30 PRINT 10,20,30 PRINT "Hello!" PRINT "y= ";y PRINT "x=";x;" y=";y;" z=";z PRINT "Your name is ";nam$ PRINT AT(5,5);"AT() is one of my favorites"

These are the most simple variations of the PRINT command. Try them out on your own to see their effects. Try with defining a few sample variables.

Now why do you write PRINT "y =";y instead of PRINT "y =",y, well that is quite simple. Using ; will add the following data directly behind your text without altering the cursor position while the , will advance the cursor to the next vertical tabular position. You can use that to align your data in tables on screen. In short, if you want to write data directly to some sort of prompt or behind some text, use the ; notation. Put a ; as the last data on your PRINT statement to let the cursor stay on the current line. You can use this to prevent a scrolling on the last line of the screen or if you simply want to split writing of prompt and data into two lines of code. Technically speaking giving the ; last will suppress a carriage return and linefeed.
If you want to write direct text onto screen which is not contained in a string variable, just enclose it in double quotes " like PRINT "Hello!" which will write Hello! on screen.

Screen control
Now that you know how to write your data on screen, you will also want to know how to handle screen output in detail. How do I leave a line of text blank might you ask? Write simply PRINT without any data behind to output a blank line on screen. Try this 3 lines program:

Code: Tout sélectionner: PRINT "Hello!" PRINT PRINT "This is the first example for screen control!"

As you see it prints the greeting and the other line with an empty line between. Quite easy don't you think?
A very important thing is how to clear the screen. For obvious reasons, you'll sometimes prepare a screen layout that requires you not to have other text or old data on screen. You'll simply clear the screen with the following command. Please note that this will also erase any other graphics on screen as the Atari ST does not distinguish between text and pixel graphics.

Code: Tout sélectionner: CLS

A neat thing is to write on screen exactly on a position where you want and not following the listed flow of ordinary PRINT statements. If you did try the first example in this chapter, you have noticed the AT() command. This special addition for PRINT allows you to position the cursor freely on screen so you can write your data where you want. Let's try the following example program:

Code: Tout sélectionner: CLS PRINT AT(1,1);"Top left" PRINT AT(5,13);"Middle line, text indented 5 chars" PRINT AT(20,25);"bottom line"; INPUT "",dummy$

Press the RETURN key to terminate the program. You'll learn soon about the INPUT statement.
Syntax for PRINT AT(); is PRINT AT(column, row);, where row 1 is on top of the screen and column 1 on the left end. Column and row can be variables, expressions or simply a plain number. Valid PRINT AT() commands are:

Code: Tout sélectionner: PRINT AT(1,5);"Hello" PRINT AT(5+x%,10);"x" PRINT AT(4+8,y%);"y = "

How many character positions do I have at my hand you may ask. This depends on the current screen resolution. You have always 25 lines of text regardless of the current screen resolution. You have 40 columns of text in ST-LOW and 80 columns in ST-MED and ST-HIGH. A ST-MED or ST-HIGH screen shows the double amount of text compared to ST-LOW. I recommend running applications that do lots of screen output in these resolutions.

Be careful with line 25. If you don't use a ; last on your PRINT statements in this line, the screen will scroll up. Keep that in mind if you want to use line 25.

There are more commands you can use with PRINT like SPC() and TAB(). Refer to your GFABASIC manual or command reference on them.

Formatting output with PRINT USING
There are built in commands for formatting data on output. I will only explain how to use that for numeric data. Refer to your command reference to learn how to apply it for strings.

Generic syntax is PRINT USING "<format string>",expression. The format string defines how you want your data to be formatted on screen while expression is what you want to write with this format. Expression can be a number, a variable or a full expression.
Build the format string from the following characters.

PRINT USING format string
Character in format string
usage

#
The hash mark will stand for a single digit in your output data.

.
A . will mark the position of the decimal point in your output.

+/-
A + or - will mark the position of the sign. In case you use the +, a positive sign will be printed as well while it is suppressed for positive numbers if you use -.

,
Use a , if you need delimiters for thousands.

See the following examples on how to use them.

Code: Tout sélectionner: PRINT USING "+###.##",150.467 PRINT USING "-#,###.##",-1500 PRINT USING "##.#",x

Experiment a bit with them, it's quite easy. For more options of PRINT USING consult your GFABASIC manual or command reference.

Gathering user input
Finally you can make your program interactive and allow the user to enter data into the computer. To understand this sub chapter, you have to fully understand variables as explained in chapter 2 because all user input is stored in variables.
To enter numbers into the computer, use the INPUT statement in one of the following ways. Your entered data is stored in the named variable. If you give a string variable, you can enter text while you can only enter numeric data if you use a numeric variable. A minus sign and optional decimal point are allowed for numeric input.

Code: Tout sélectionner: INPUT "x= ",x INPUT "What is your name? ",your_name$

This will prompt the user to enter a value for x which will be stored into a float variable. You can then use this variable in your program as normal, doing calculations with it. Your program will stop until the RETURN key has been pressed to terminate the input.

You can read more than one variable with one INPUT statement, just list your variables where you want your input to go to with separating commata.

Code: Tout sélectionner: PRINT "enter 3 values, separated with commata (eq 3,4,5):" INPUT x%,y%,z%

The user has then to enter commata at the appropriate places to tell which input goes to which variable. To the example above the user would respond with 5,6,7. As always you can then reuse the entered values in expressions and calculations.

Code: Tout sélectionner: CLS INPUT "Enter a value for x:",x PRINT "x = ";x INPUT "What is your name?",your_name$ PRINT "Your name is ";your_name$;"." PRINT "Bye, ";your_name$;"!"

While entering strings you may have already noticed that GFABASIC will treat entering a comma again as a delimiter, effectively cutting your string at that comma. Use the command LINE INPUT instead of INPUT to read strings.

Code: Tout sélectionner: LINE INPUT ">",txt$

You can now enter strings with a comma in and it will be saved to the string variable as well. You can read multiple strings with LINE INPUT as well but the user has to press the RETURN key terminating each string to be entered.

An INPUT statement will erase the former contents of a variable in any case and will place the entered values in them.

Progress check
Like in the previous chapter, answer these little questions to verify your advancement in learning GFABASIC.

I want to output a blank line. I use the command: ...
I want to output my data on the third line from top and indented by 10 columns. I use the command: ...
I want to output the value of variable x%. I use the command: ...
I want to prompt the user to enter a float variable and put the input in a variable called z. I use the command: ...
I want to output the value of this variable z with optional sign, 3 digits before the decimal point and 4 digits behind the decimal point. I use the command: ...
Write a program that prompts the user for 2 numbers, adds these numbers and outputs the result nicely formatted on screen.

If you still make mistakes when answering these questions, I suggest to read the chapter again.

de **simonsunnyboy** » Sam 6 Juin 2009 08:19

Flow Control Part 1
This time you'll finally make your programs do things more then once without having to retype your code. The creation of so called loops is essential for making complex programs work.

The concept of looping and simple counting loops
Before going further let me explain you the fundamental idea of looping. The idea is to make your program repeat a section of code for a defined amount of time. You may let GFABASIC count a variable for you and you can then use the value of that variable in an ongoing calculation. Or you can let GFABASIC loop a certain part of code until a special condition has been met. Take a look at the following sample program:

Code: Tout sélectionner: FOR i%=1 TO 5 PRINT i% NEXT i%

This little example program loops 5 times and counts the variable i% from 1 to 5 and prints the current value to the screen. This sort of loop is called a FOR-NEXT-loop. You can use any numerical variable to count. Most often this sort of loop is used to do things a certain amount of time or to iterate over a list. The loop will repeat the code between the FOR and its corresponding NEXT. Each time GFABASIC reaches the NEXT, it will increment the count variable and will stop the loop if the maximum count has been reached.
You can ofcourse have another loop inside the current one. Just make sure not to use the same variable for counting or GFABASIC will do unpredictable things:

Code: Tout sélectionner: FOR i%=1 TO 5 FOR j%=1 TO 10 PRINT i%;" * ";j%;" = ";i%*j% NEXT j% NEXT i%

That sample program has one FOR-NEXT-loop inside another and it calculates the product of the both counter variables creating some sort of multiplication table. Some rules and advice to keep in mind with FOR-NEXT-loops:

GFABASIC will check for correct loop termination while entering the code into the editor.
You can terminate the FOR-NEXT-loop with the EXIT IF statement.

That was easy. Now a very fundamental construct for flow control: test for certain conditions and the method for letting your program take an alternative code segment.

Conditions
A very fundamental idea in programming is to create and use conditionals. These will allow you to make decisions when certain conditions are met.

Try to imagine that you count a special variable and want to do something else when the value of your counter is 5:

Code: Tout sélectionner: FOR i%=1 to 10 IF i%=5 THEN PRINT "i% is now 5" ELSE PRINT "i% is not 5" ENDIF NEXT i%

Try to understand this example fully. It is so fundamental that you will never be able to write a real program if you don't understand how to formulate and use conditionals. This program loops 10 times and counts in the variable i%. For each iteration of the loop it checks if i% is 5 in the IF line. If that condition is true, i% is 5, then it executes the program branch until the ELSE and omits the following part. If the condition is not true, GFABASIC will only execute the part behind the ELSE. Make sure to terminate each IF conditional with an ENDIF or GFABASIC will get lost and produce an error message. The THEN behind the conditional is not needed but some other BASIC dialects will require it.
You may leave out the ELSE fork. GFABASIC will then do nothing if the condition is not true.

Code: Tout sélectionner: IF i%=5 THEN PRINT "i% is 5" ENDIF REM the following part is fully identical in function and behavior IF i%=5 PRINT "i% is 5" ENDIF

The REM stands for remark and is a generic comment. Comment your programs and you will be able to understand it later. A ' might be used as well. Anything behind the REM will be ignored by GFABASIC.
You can also write a comment behind any statement or instruction by using the !. GFABASIC will ignore anything behind that single ! as a comment.

You can combine expressions and conditions to check for multiple conditions in one go.

Code: Tout sélectionner: IF (i%=1) AND (j%=2) PRINT "i% is 1 and j% is 2" ! This is also a comment! ENDIF

This example would only execute the PRINT statement if i% is 1 and j% is 2. This is simple boolean logic. The brackets are optional but sometimes you need them or GFABASIC will not evaluate an expression as intended. With the brackets you can control which condition has to be fulfilled first. The following statements are not identical:

Code: Tout sélectionner: IF ((i%=1) AND (j%=2)) OR (x%=1) ... ENDIF IF (i%=1) AND ((j%=2) OR (x%=1)) ... ENDIF

You see brackets are useful. Take care when developing your logic and try to formulate it with the least amount of conditionals possible.

Ofcourse you can check if value are less or more then a certain amount. See the following table:

Condition
does what

i%<j%
will evaluate to TRUE if is i% is less than j%

i%<=5
will evaluate to TRUE if i% is 5 or less

i%=100
will evaluate to TRUE is i% is exactly 100
i%<>j%
the opposite of an equality test - evaluates to TRUE if i% is not equal j%, meaning i% is different from j%

i%>50
will evaluate to TRUE if i% is larger than 50

a%>=50
will evaluate to TRUE if a% is 50 or larger

Ofcourse you do not need to check for single variables. You can evaluate full expressions like the following one:

Code: Tout sélectionner: IF x%+y%>18 ... ENDIF

Usage of brackets is again recommended:

Code: Tout sélectionner: IF (x%+y%)>18 ... ENDIF

You can combine conditionals with boolean expression as shown above. See this table for more information. Make sure to use brackets at the proper places or you code will go crazy:

Boolean connector
does what

condition1 AND condition2
evaluates to true only if both conditions are fulfilled

condition1 OR condition2
gets true when one or both conditions are fulfilled

NOT condition
gets true if the opposite of the condition is true - mean NOT i%<5 will get true when i% is 5 or greater

condition1 XOR condition2
evaluates to true when exactly one of the both conditions is fulfilled

There are a few more conditionals but you create any condition and expression with these.
Now that you have the knowledge about conditional expressions, it is time to introduce you to a few more loop statements.

Conditional and endless loops
Sometimes you don't know how far you need to count for a special operation. Or imagine a game. You don't want to let it run just for 10 frames but until the player sprite did collide or something like that. The first new loop will loop until a condition is fulfilled:

Code: Tout sélectionner: REPEAT ... UNTIL <condition>

This is a so called REPEAT-UNTIL-loop. It loops at least once and checks for the condition after the loop contents have been executed by GFABASIC. Use it for things that need to be done at least once. You can emulate FOR-NEXT-loops with it if you want trickier counting:

Code: Tout sélectionner: i%=1 REPEAT PRINT "i%=";i% i%=i%+1 UNTIL i%>5

This example will emulate a plain FOR-NEXT-loop that counts i% from 1 to 5. In GFABASIC v3 and up you can also write the following which is the same as the REPEAT one above:

Code: Tout sélectionner: DO ... LOOP UNTIL <condition>

Surely you can test the condition before entering a loop. This is useful if you want to loop only when a certain condition is already true:

Code: Tout sélectionner: WHILE <condition> ... WEND

This is the so called WHILE-WEND loop. It checks the condition first and it will not execute the loop body if the condition is not fulfilled.

Sometimes you want to loop endless. GFABASIC has a special loop construct for this purpose although you can create never ending loops easily with the types above if you use a condition that will never get true.

The neverending or endless loop is called DO-loop. The 3 loops in the example are all equal in functionality and will loop endless.

Code: Tout sélectionner: DO PRINT "endless" LOOP i%=0 REPEAT PRINT "endless" UNTIL i%=1 ! loops endless because i% never becomes 1 in this loop i%=0 WHILE i%=0 PRINT "endless" WEND

At this point it is important that you know you can terminate at your GFABASIC program at any point and return to the editor. This is useful if your program gets stuck in an endless loop which was not intended. Press the keys ALTERNATE+CONTROL+SHIFT together and GFABASIC will ask you for a program stop.

Sometimes you will want to terminate a running loop at another point than the official loop beginning or loop end. Use the EXIT IF statement in your loop for extra conditions. This will also terminate FOR-NEXT-loops if you wish to and it is the only way to terminate a DO-loop.

Code: Tout sélectionner: i%=1 DO PRINT "i%=";i% EXIT IF i%=5 i%=i%+1 LOOP

Please note that the EXIT IF statement has no ENDIF or the like. It just terminates the loop and continues your program behind the loop end.

Progress Check
Now that you have learned the fundamentals of looping and conditions, check yourself with the progress check. I advise you not to continue with this tutorial until you fully understood the ideas, concepts and constructs of this chapter.

Can you combine multiple conditions in one conditional statement? If yes, give an example: ...
Write a loop that counts from 4 to 10: ....
Implement this loop with all loop types mentioned in this chapter.
Can you count in increments different then 1? How?
Write a program snippet that will print "Hello Atari" on screen if the value of the variable i is less or equal 4.
Which parts of the IF-THEN statement are optional?
Write a program that will print a nicely formatted multiplication table on screen for all numbers from 1*1 to 10*10.
Which statement will terminate any loop on condition? Do you need an ELSE part or terminate it with ENDIF?
Explain the difference between OR and XOR.
Explain the difference between REPEAT..UNTIL <condition> and DO..LOOP. Is there any?
Give 2 methods how you can change the DO...LOOP into a terminating one like the REPEAT..UNTIL one.

de **simonsunnyboy** » Sam 6 Juin 2009 08:22

Introduction to graphics

Thanks to the VDI GFABASIC offers the coder a wealth of commands to draw something on screen. This part of the tutorial aims to help you getting started with graphics from GFABASIC.

First of all you have to understand how a nice picture works on the Atari ST. Everything you see on your screen is made up from tiny little dots. With the various graphics commands you can manipulate all of those dots to display anything on screen.

The amount of dots you can manipulate is dictated by the current screen resolution. The ST offers 3 different resolutions. By default GFABASIC starts your program in the current one so if you did boot GFA from a medium resolution desktop your program will use medium resolution too. (One can change that behaviour but that is not the goal of this part of the tutorial.)

The screen resolutions differ on their size and the amount of colors you can use to draw the picture. Without tricks the ST offers the following video modes:

ST-LOW: 320x200 pixels, 16 colors
ST-MED: 640x200 pixels, 4 colors
ST-HIGH: 640x400 pixels, 2 colors

Pixels are addressed by pairs of cartesian coordinates. However their behaviour is different from what you know fom your math lessons at school. On the ST 0,0 is the upper left corner, but 100,100 is down to the right. Just take an easy example, simply type in the following program and click run. It will draw 3 dots on screen.

Code: Tout sélectionner: CLS COLOR 1 PLOT 10,10 PLOT 75,50 PLOT 150,150 VOID INP(2) EDIT

You now have learned two important commands. COLOR allows you to choose one of the colors you want to use from that on to draw on your screen. Take note it only affects line and dot commands and not filled structures. The other command is PLOT which draws a single dot.

Let's see the following program. It will fill the screen line by line very slowly because drawing single pixels is slow compared to drawing multiple ones in one go. This code also shows you a way to determine the screen resolution your ST is in.

Code: Tout sélectionner: CLS SELECT XBIOS(4) ! which resolution are we in? CASE 0 ! ST-LOW COLOR 4 width%=319 height%=199 CASE 1 ! ST-MED COLOR 2 width%=639 height%=199 CASE 2 ! ST-HIGH COLOR 1 width%=639 height%=399 ENDSELECT ' now we loop through all lines on screen FOR y%=0 to height% ' draw a pixel in all columns of the current line FOR x%=0 to width% PLOT x%,y% ! draw pixel NEXT x% NEXT y%

As you can see the coordinates count up and the screen fills from top down. Users of a color monitor will notice that the screen fills in a different color.

That was awfully slow don't you think? We can improve it!

Drawing lines

Basically the program above does draw lines on screen. But instead of drawing each dot yourself you can let GFABASIC do this tedious task for you. Not very surprisingly this is very easy and a lot faster too. Simply eliminate the inner loop of the program above, the FOR x%=... one including its NEXT x% statement and write the following:
LINE 0,y%,width%,y%

And presto, the whole thing is faster now. LINE does exactly what its name implies, it draws lines. And those lines do not need to be horizontal at all. They can go from any location to another on screen. Just alter the coordinate pairs. Try the following little program:

Code: Tout sélectionner: CLS COLOR 1 FOR x%=0 to 199 STEP 10 LINE x%,0,199-x%,199 NEXT x%

As you should have figured out by now the LINE command takes 2 coordinates as inputs. But what if you want to draw more than one line and you want to continue from where your last line ended? No worries, GFABASIC has something for this aswell. Try the following program:

Code: Tout sélectionner: CLS COLOR 1 DRAW 10,10 TO 309,99 TO 10,190 TO 10,10

And now you should see a triangle on screen. You can also do this continous inside of a loop, a sort of using a pen and continuing drawing from time to time:

Code: Tout sélectionner: CLS COLOR 1 DRAW RANDOM(310)+5,RANDOM(190)+5 FOR c%=1 to 19 DRAW TO RANDOM(319),RANDOM(199) NEXT c%

That should draw a continuous line through a set of 20 random points.

There is another command to draw continuous sets of lines, the POLYLINE command. Refer to your GFABASIC manual on that one.

Boxes and other rectangles

You will probably want to draw some boxes as well. With the following knowledge you could something like this:

Code: Tout sélectionner: CLS COLOR 1 LINE 10,10,100,10 LINE 100,10,100,100 LINE 100,100,10,100 LINE 10,100,10,10

That should draw a box on screen but you have to use 4 commands, one for each side of the box. GFABASIC can do this in one go for you. Just use the BOX command. It takes two coordinates as parameters, the upper left corner and the lower right corner of your box. In the case above the following would do the same, and much faster:

Code: Tout sélectionner: BOX 10,10,100,100

Let's use the accumulated knowledge to draw a pattern on screen:

Code: Tout sélectionner: CLS FOR x%=0 to 19 FOR y%=0 to 10 COLOR 1 BOX x%*16,y%*16,x%*16+14,y%*16+14 COLOR 3 LINE x%*16,y%*16+14,x%*16+14,y%*16 NEXT y% NEXT x%

The screen should fill with a pattern of boxes that have a diagonal line inside. Color monitor users will see different colors too

Another variation of drawing rectangles is to give them rounded edges. Simply write RBOX instead of BOX and the corners of your box are now rounded. Try the following:

Code: Tout sélectionner: CLS FOR r%=10 TO 140 STEP 10 RBOX 160-r%,100-r%,160+r%,100+r% NEXT r%

It is quite easy to use.

Round 'nd round

GFABASIC can also draw circles and ellipses for you. To draw circles you use the, surprise surprise, CIRCLE command. It takes 3 parameters, a pair of coordinates and the radius of the circle you want to draw. The coordinate pair describes the center point of the circle you are going to draw onto the screen. The radius is simply measured in pixels as well. Let's try it out:

Code: Tout sélectionner: CLS COLOR 1 FOR r%=10 TO 90 STEP 10 CIRCLE 150,100,r% NEXT r%

If you look quickly, you should see that the diameter of the circle is growing with every iteration of the loop. One can also draw arcs with the CIRCLE command but I leave that up to you GFA manual to find out how.

Let's go on and draw some ellipses. They use the ELLIPSE command and simply take another radius parameter. The first radius describes the horizontal size of the ellipse and the second one the vertical size. So it is quite easy. Try the following slightly different program:

Code: Tout sélectionner: CLS COLOR 1 FOR c%=20 TO 90 STEP 10 ELLIPSE c%,100,c%,c%/2 NEXT c%

It will just draw a pattern consisting of growing ellipses on screen.

Filled structures

Sofar you have only drawn lines and single pixels. How about filling the void with some color and/or pattern? You can select a color and pattern to use for filled objects with the DEFFILL command. Its syntax is as follows:

Code: Tout sélectionner: DEFFILL color.nr%,pattern.set%,pattern%

The parameters are easy to explain. The color number specifies the number of color you want to use for the fill. The pattern set allows you to select between 3 different sets of fill styles but let me tell you right here, the first one is pretty boring. The pattern index itself goes up to 32. Let me show you with a simple program:

Code: Tout sélectionner: CLS FOR s%=1 to 3 FOR c%=0 to 31 DEFFILL 1,s%,c% PBOX c%*8,s%*30,c%*8+7,s%*30+29 NEXT c% NEXT s%

Noted the PBOX command? It does the same as BOX but fills the box right away. That works with the other comamnds as well so you have PCIRCLE, PELLIPSE and PRBOX at your hand as well. But you can also fill a single location on screen. This floodfill will even follow any irregularities in your graphics on screen. Use the FILL command as follows:

Code: Tout sélectionner: FILL x%,y%

x% and y% simply form another coordinate pair just like the PLOT command did. Try it out with the following program:

Code: Tout sélectionner: CLS COLOR 1 FOR x%=0 to 319 STEP 5 FILL 0,0,x%,195 NEXT x% DEFFILL 3,2,4 FILL 0,199

The FILL command is pretty slow as you can see so I recommend to use it only to prepare graphics and store them to disk and/or memory for later use.

That should be sufficient for now. In the next tutorial I'll tell you how to change the colors used in your screen and how to manipulate blocks of graphics.

For the moment enjoy yourself and experiment with the graphical power of GFABASIC!

de **LorenzYM** » Lun 8 Juin 2009 18:27

hi,

thanks a lot for those documents, now i'm learning all the EVNT_MOUSE stuff before i go on with silly question about animation. anyway i would be glad about some more tips on my "monochrome game", so i can beginn with the structure of it.
best regards,

GFABASIC tutorial by Simon Sunnyboy / Paradize

GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Re: GFABASIC tutorial by Simon Sunnyboy / Paradize

Qui est en ligne