Next Previous Contents

2. What do you have and what to do with it?

This chapter describes some rules you ought to obey, and how to use GEOSLib.

2.1 Usage

Apart from this file, which merely describes only standard GEOS library functions, you should read the grc65 (GEOS resource compiler) documentation. There is information about necessary resource files (each GEOS application needs at least one) and the build process - what should be done and in what order. Please also read the cc65 documentation on how to compile C, assembler and link everything together.

All in all, you just need to place

#include <geos.h>
at the top of your source.

As a general rule read the sources of the example programs and read the headers. These are the most reliable sources of knowledge ;-). You will also find there many C macros representing various arguments passed to the functions. Please use them. You will find your sources easier to understand, and it will be easier to find bugs.

All types used in GEOSLib are unsigned.

Screen coordinates are given in pixels unless stated differently.

2.2 Notes on style

Contrary to a typical GEOS assembly program which has a main function called after loading that setups the screen, menus, icons etc. exiting from the main function in C is equivalent to calling exit(). These two are the only safe methods of terminating applications. DO NOT USE EnterDeskTop! Your data may be lost as library destructors and functions registered with atexit are not called.

For GEOS GUI applications the recommended program structure is to have everything initialized in the main function and at the end of it a call to the MainLoop() function. WARNING! This function never returns, any code between MainLoop(); and the end of main will not be executed. You have to call exit() explicitly somewhere in your code (e.g. in a menu handler or via DialogBox action).

Whenever possible use definitions from gsym.h. The resulting code is translated by cc65 into series of lda and sta, so you can't do it better :-).

Don't hesitate to use library functions. Everything was written with size and speed in mind. In fact many calls are just redirections to the GEOS Kernal which results in a simple jsr.

The main function receives the standard argc and argv parameters. There are always either 1 or 3 parameters. The DOS application name is always set as argv[0]. If present, argv[1] and argv[2] will be set to the data filename and data diskname (it only works if the user double-clicks on a data file associated with your application). Note that it is up to your application to determine which of the available (up to four) disk drives has the disk with given diskname inside. If this fails your program should ask to insert the proper disk into one of available drives.

You might wonder why I have chosen a sometimes weird order of arguments in functions. I just wanted to avoid unnecessary pushing and popping of arguments from the stack because cc65 can pass a single unsigned int through CPU registers.

Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in ANSI.

It is possible to use dynamically loaded modules, three such modules are provided: A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver. Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special recommendations, read the cc65 documentation about modules and the demo programs source code.


Next Previous Contents