6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2024-12-26 08:32:00 +00:00
Code Issues Projects Releases Wiki Activity

documentation updates, grammar and spelling fixes

Browse Source 
git-svn-id: svn://svn.cc65.org/cc65/trunk@774 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
izydorst 2001-07-03 21:42:48 +00:00
parent 823329443f
commit fc51f7f77f
1 changed files with 76 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
doc/geos.sgml
View File

@ -6,7 +6,7 @@
<title>GEOSLib docs
<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl">
<date>v1.1, 26.12.1999, 16.03.2000, 19-22.03.2000, 11,29.07.2000
<date>v1.1, 26.12.1999, 16.03.2000, 19-22.03.2000, 11,29.07.2000, 03.07.2001
<abstract>
This is the documentation of cc65's GEOSLib, but information contained here may be also
useful for writting GEOS applications in general.
@ -27,16 +27,18 @@ is easy to use and program.
Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65
package and my GEOSLib you are able to create GEOS applications in no-time.
<p>
GEOSLib in its current stage doesn't support standard cc65 libraries. It is likely to be changed
in next version. Note that it doesn't mean that it will not work now. I didn't bother myself to
check if it is possible. All I needed for a start was including only <tt/geos.h/ in the source
and nothing else.
GEOSLib supports a subset of standard cc65 libraries. Memory and string functions are included
but you should consider using native versions of these (e.g. <tt/FillRam/ instead of </ttmemset/)
at least in this version. <tt/dio/ - direct disk access is available, but you might have
problems with devices other than 1541, 1571 or 1581. RAM drives emulating these should work.
It is safe to use these includes: <tt/dio.h, errno.h, geos.h, joystick.h, mouse.h, stdlib.h,
string.h/
<p>
I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
available code (well, the best as for machine :). Many of the <tt/void foo (void)/ functions are
just raw calls to Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you
will find many definitions of standard GEOS locations. Access to these addresses is optimized by
cc65 to simple <tt/lda/ and <tt/sta/.
cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use the power of C.
<sect1>Requirements
<p>
@ -70,9 +72,9 @@ Reference Guide and BSW for GEOS.
<p>
GEOSLib is covered by the same license as cc65. You can find the whole text among documentation.
I would really appreciate if you would like to send me your comments, suggestions, questions,
changes, bug reports etc. I feel that GEOSLib may be much better. After all, this is the first
release. I will also appreciate if you will just give me a sign that you are using GEOSLib -
not especially something big and important, mail me even if you are just playing with it.
changes, bug reports etc. I will also appreciate if you will just give me a sign that you are
using GEOSLib - not especially something big and important, mail me even if you are just playing
with it.
<p>
You can send postcards with hellos to:
<p>
@ -88,15 +90,11 @@ This chapter describes some rules you ought to obey, and how to use GEOSLib.
<sect1>General rules
<p>
Ulrich probably won't like it, but I don't want you to use his standard C functions. In fact, the
best way (IMO) of programming GEOS with GEOSLib is to only use GEOS lib. You don't need anything
else. You shouldn't need anything else.
Think twice before you use standard C library function. In current implementation almost always
you will get better code using only <tt/geos.h/. This will change in next releases as standard
functions will become wrappers to native GEOS Kernal.
<p>
If you really, really need to mix standard libraries with GEOSLib be warned that it probably won't
work and lookout for the <tt/errno/ - it points to one place when <tt/errno.h/ is included and
another with <tt/geos.h/.
<p>
Apart from this file which merely describes only standard GEOS library functions you should read
Apart from this file, which merely describes only standard GEOS library functions, you should read
<tt/grc/ (GEOS resource compiler) documentation. There are informations about necessary resource
files (each GEOS application neeeds at least one) and the building process - what should be done
and in which order.
@ -212,8 +210,8 @@ Just as the name says...
<tt/void RecoverRectangle (void)/
<p>
These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/)
backbuffer of the screen. For example GEOS drawing new menus on screen first uses
<tt/ImprintRectangle/ to save the area under menu, and restores it by <tt/RecoverRectangle/ upon
backbuffer of the screen. For example when drawing new menu box GEOS first uses
<tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon
destroying the menu.
<sect2>Line Functions
@ -411,9 +409,9 @@ same as <tt/DoPreviousMenu/.
<p>
Icons are working similar to menus except the fact that there is only one level. Icons are
defined as a screen area filled with a bitmap, but if you would setup icons and erase the
screen they are still working and cliking in the place where formerly an icon was will cause
screen they are still active and clicking in the place where formerly an icon was will cause
an effect. Similary if you would setup icons and then turn them off with <tt/ClearMouseMode/
the bitmap will be still on the screen.
the bitmap will be still on the screen but clicking on it would not cause any action.
There is only one, but powerful icon function.
<sect3>DoIcons
@ -425,7 +423,7 @@ look at <tt/Icons/ chapter in this manual.
<sect1>DialogBoxes
<p>
This chapter covers the most powerful GEOS function - <tt/DoDlgBox/.
This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/.
<sect2>GEOS standard
@ -514,7 +512,7 @@ but they are not cleared from the screen.
<p>
<tt/void MouseOff (void)/
<p>
The fist function turns the mouse pointer on. It will appear on next IRQ. The second one does
The first function turns the mouse pointer on. It will appear on next IRQ. The second one does
the opposite - it turns off the pointer, but its position is still updated by input driver.
<sect3>IsMseInRegion
@ -522,19 +520,19 @@ the opposite - it turns off the pointer, but its position is still updated by in
<tt/char IsMseInRegion (struct window *myWindow)/
<p>
This function tests if mouse pointer is actually in given range of screen. See <tt/gsprite.h/ for
possible return values - they describe the position in detail.
description of bits in return values - they describe the position in detail.
<sect2>Sprites
<p>
You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
pointer and sprite 1 can be overwritten when is used as text prompt.
pointer and sprite 1 can be overwritten when using text prompt.
<sect3>DrawSprite
<p>
<tt/void DrawSprite (char sprite, char *mySprite)/
<p>
This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which
is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Sprite visual registers are
is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are
not initialized and sprite is not yet visible.
<sect3>PosSprite
@ -542,7 +540,7 @@ not initialized and sprite is not yet visible.
<tt/void PosSprite (char sprite, struct pixel *myPixel)/
<p>
This function positions the sprite on the screen. Given coordinates are screen ones - they are
converted to sprite coords by GEOS. Due to this you cannot use this function to position your
converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your
sprite off the left or top to the screen.
<sect3>EnablSprite and DisablSprite
@ -551,8 +549,7 @@ sprite off the left or top to the screen.
<p>
<tt/void DisablSprite (char sprite)/
<p>
These two functions are responsible for the fact if the sprite will or will not appear on the
screen.
These two functions are responsible for making the sprite visible or not.
<sect2>Cursors and Console
@ -569,8 +566,8 @@ range 1-48.
<p>
<tt/void PromptOff (void)/
<p>
The first function places text prompt in given place and enables it so it blinks and generally is
visible. The second function is pretty self-explanatory.
The first function places text prompt in given place and enables its blinking
The second one is pretty self-explanatory.
<sect3>GetNextChar
<p>
@ -587,6 +584,8 @@ you may easily corrupt data on disks. Also remember that contemporary GEOS suppo
devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
dangerous.
<p>
For some purposes you might consider using <tt/dio.h/ interface to disk access. It is native.
<p>
All GEOS disk functions return error code in X register. In some cases this is returned by
GEOSLib function (if its type is <tt/char/), but in all cases last error is saved in <tt/errno/
location. If it is nonzero - an error occured. See <tt/gdisk.h/ for list of errorcodes.
@ -677,15 +676,16 @@ using.
<p>
This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is
set if the sector is free to use. Returned value is always zero if the sector is already allocated.
In fact, this function could be described as e.g. <tt/SectInUse/ and used in following way:
In fact, this function could be used in a following way:
<tscreen><verb>
&num;define BlockInUse FindBAMBit
...
if (!SectInUse(&amp;myTrSe)) &lcub;
... block not allocated ...
&rcub;
</verb></tscreen>
<p>
Anyway, I feel that this function is slightly low-level, maybe too low-level.
Anyway, I feel that this function is too low-level.
<sect3>BlkAlloc and NxtBlkAlloc
<p>
@ -699,9 +699,9 @@ number of track equal to 0 and sector equal to 255. The simpliest way of using t
predefined space in GEOS data space and pass <tt/fileTrScTab/, which is a predefined table.
<p>
The difference between those two is that <tt/NextBlkAlloc/ will start allocating from given sector,
and <tt/BlkAlloc/ starts from first nonused sector.
and <tt/BlkAlloc/ starts from the first nonused sector.
<p>
You need to <tt/PutDirHead/ to save any changes in BAM.
You need to use <tt/PutDirHead/ later to save any changes in BAM.
<sect3>FreeBlock
<p>
@ -713,10 +713,10 @@ Simply deallocates a block in BAM. You need to update BAM with <tt/PutDirHead/.
<p>
<tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/
<p>
This function finds first free sector starting from given track and sector. It might return the
same argument if the given block is not allocated. I wanted this function to be type-clean, but
it made usage a bit tricky. To assign a value to own <tt/struct tr_se/ you have to cast both
variables to <tt/int/. E.g.
This function finds the first free sector starting from given track and sector and allocates it.
It might return the same argument if the given block is not allocated. I wanted it to be type
clean, but it made usage a bit tricky. To assign a value to own <tt/struct tr_se/ you have to
cast both variables to <tt/int/. E.g.
<tscreen><verb>
struct tr_se myTrSe;
...
@ -726,8 +726,6 @@ struct tr_se myTrSe;
In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
<p>
NOTE that you <em/must/ use casting to have correct values.
<p>
<tt/SetNextFree/ only finds next free sector, it doesn't allocate it.
<sect2>Low-level disk IO
<p>
@ -749,8 +747,8 @@ This is useful for sending some DOS commands for drive e.g. for formatting. Note
interaction with Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed.
<tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with
<tt/ExitTurbo/. <tt/PurgeTurbo/ acts different from <tt/ExitTurbo/ - it not only disables TurboDos,
but also removes it from drive RAM (not quite true, but it works like that). After a <tt/PurgeTurbo/,
<tt/EnterTurbo/ will have to reload drive RAM.
but also removes it from drive RAM (not quite true, but it works like that). After using
<tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM.
<sect3>ChangeDiskDevice
<p>
@ -759,9 +757,7 @@ but also removes it from drive RAM (not quite true, but it works like that). Aft
This function changes logical number of current device (in fact drives only) with given one. It is
usable for swapping drives. There's no check if given <tt/newDevice/ already exist, so if you want
to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably
hung on disk access. Use safe, large numbers. Note that safe IEC range is 0-32, but devices with
numbers below 8 shouldn't be used (there is 'DiskDevice' in the name of this function and devices
0-7 are not 'DiskDevices' you know :-).
hang on disk access. Use safe, large numbers. Note that safe IEC range is 8-31.
<sect2>Disk Initialization
<p>
@ -796,16 +792,16 @@ Functions described here are common for SEQ and VLIR structures.
<tt/struct filehandle *GetNxtDirEntry (void)/
<p>
These two functions are best suited for scanning whole directory for particular files. Note that
returned filehandles describe all file slots in directories - even those with deleted files.
returned filehandles describes all file slots in the directory - even those with deleted files.
The return value can be obtained by casting both sides to <tt/int/ - as in <tt/SetNextFree/
function, or read directly after call to those two functions from <tt/r5/. Current sector number
function or read directly after call to those two functions from <tt/r5/. Current sector number
is in <tt/r1/ and sector data itself is in <tt/diskBlkBuf/.
<sect3>FindFile
<p>
<tt/char FindFile (char *fName)/
<p>
This function scans whole directory for given filename. It returns either 0 (success) or 5
This function scans whole directory for the given filename. It returns either 0 (success) or 5
(FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After successful
<tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with file's data and
other registers set as described in <tt/GetNxtDirEntry/.
@ -818,11 +814,11 @@ This function scans directory and fills a table at <tt/buffer/ with <tt/char &ls
<tt/fType/ is GEOS type of searched files and <tt/classTxt/ is a string for Class field in file
header. Class will match if given will be equal or shorter than that found in file's header block.
If you want just to find all files with given GEOS type you should pass empty string or <tt/NULL/ as
<tt/classTxt/. Be warned that for searching NON_GEOS files must pass <tt/NULL/ as <tt/classTxt/.
<tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files must pass <tt/NULL/ as <tt/classTxt/.
<tt/fMaxNum/ is the maximal number of found files, thus the <tt/buffer/ must
provide area of size equal to <tt/17 * fMaxNum/.
This function returns the number of found files, ranging from 0 to number passed as fMaxNum.
Return value from kernal FindFTypes can be restored from <tt/r7H/.
This function returns the number of found files, ranging from 0 to number passed as <tt/fMaxNum/.
Return value can be also restored from <tt/r7H/.
<sect3>DeleteFile
<p>
@ -859,13 +855,15 @@ This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sec
<p>
<tt/char ReadByte (void)/
<p>
This function returns next byte from file. Before first call to this function you must load the
first sector of file, easiest way by using <tt/GetBlock/ and set <tt/r5/ to the offset (you will
want to skip the link, so use the value of 2 here). Then you may call <tt/ReadByte/.
Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/.
This function returns next byte from a file. Before the first call to it you must load <tt/r5/
with <tt/NULL/, <tt/r4/ with sector buffer address and <tt/r1/ with track and sector of the
first block of a file.
Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between
calls to <tt/ReadByte/.
<p>
Returned value is valid only if there wasn't any error. End of file is marked as <tt/BFR_OVERFLOW/
in <tt/errno/, this is set when trying to read one byte after the end of file.
Returned value is valid only if there was no error. End of file is marked as <tt/BFR_OVERFLOW/
in <tt/errno/, this is set when trying to read one byte after the end of file, in this case
returned value is invalid.
<sect3>SaveFile
<p>
@ -990,8 +988,8 @@ are replacement for those like <tt/memset, memcpy, strcpy/ etc. from standard li
However they have slighty different calling convention (order of arguments to be specific), so
please check their syntax here before direct replacing.
Please note that the memory described as <tt/strings/ are up to 255 characters (without
counting the terminating <tt/NULL/), and <tt/regions/ cover whole 64K of memory.
Please note that the memory described as <em/strings/ are up to 255 characters (without
counting the terminating <tt/NULL/), and <em/regions/ cover whole 64K of memory.
<sect2>CopyString
<p>
@ -1065,14 +1063,14 @@ These functions are interface to REU - Ram Expansion Unit. I think that they are
<sect1>Processes and Multitasking
<p>
Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions
called in specified intervals and you can sleep the main program without disturbing other
tasks.
called in specified intervals and you can put the main program to sleep without disturbing other
tasks and making user interface unresponsive.
<sect2>InitProcesses
<p>
<tt/void InitProcesses (char number, struct process *processTab)/
<p>
This is the main initialization routine. After calling this processes are set up, but not
This is the main initialization routine. After calling it processes are set up, but not
enabled. The parameters for <tt/InitProcesses/ are:
<itemize>
<item><tt/number/ - number of processes
@ -1086,7 +1084,7 @@ systems there are 50 jiffies per second, while on NTSC there are 60.
The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
if <tt/processTab/ would be too large it would overwrite existing data in GEOS space.
<p>
There's one important thing - last entry in <tt/processTab/ have to be <tt/NULL,NULL/, so the
There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the
maximum size of <tt/processTab/ is equal to 21.
<p>
See description of <tt/process/ structure for more detailed discussion on this.
@ -1189,7 +1187,7 @@ System is halted after call to <tt/Panic/.
<sect2>CallRoutine
<p>
<tt/void CallRoutine (void &ast; myFunct)/
<tt/void CallRoutine (void &ast;myFunct)/
<p>
This is system caller routine. You need to provide pointer to a function and it will be immediately
called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function -
@ -1211,11 +1209,11 @@ This function returns a random number. It can be also read from <tt/random/ e.g.
a=random;
</verb></tscreen>
but by calling this function you are sure that the results will be always different.
<tt/random/ is updated once a frame (50Hz) and on every call to <tt/GetRandom/
<tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/
<sect2>SetDevice
<p>
<tt/void SetDevice (char)/
<tt/void SetDevice (char device)/
<p>
This function sets current device to given. It might be used together with <tt/InitForIO/,
<tt/DoneWithIO/ and some Kernal routines. Unless new device is a disk drive this only sets
@ -1223,7 +1221,7 @@ new value in <tt/curDevice/, in other case new disk driver is loaded from REU or
<sect>Library Structures
<p>
To simplify using and optimize passing parameters to functions I have declared several structures
To simplify usage and optimize passing parameters to functions I have declared several structures
which describe most common objects. Some of these structures are binded to static addresses in
GEOS data space ($8000-$8fff), so you can use their fields directly in optimized way.
Please see <tt/gsym.h/ and find them. All structures are defined in <tt/gstruct.h/ and you may
@ -1233,12 +1231,12 @@ find also some comments there.
<sect2>pixel
<p>
One simple structure describing point on the screen.
One simple structure describing a point on the screen.
<sect2>fontdesc
<p>
This structure describes font in one pointsize. There is current font - <tt/struct fontdesc/
binded at <tt/curFontDesc/. You can also force GEOS to use your own font by calling
This structure describes a font in one pointsize. There is current font - <tt/struct fontdesc/
binded at <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling
<tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize
somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can
pass a pointer to the load adress of that pointsize to <tt/LoadCharSet/.
@ -1282,13 +1280,14 @@ has following fields:
<p>
This simple structure holds track and sector number of something. Do not expect the track to be
in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K
expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each.
expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each. However assuming that
track number equal to 0 is illegal might be wise.
<sect2>f_date
<p>
This is placeholder for file datestamp. This structure is also present in <tt/struct filehandle/.
GEOS is not Y2K compliant, so if current file in <tt/filehandle.date.year/ value less than 86 you
can safely assume that it is e.g. 2085 - not 2086.
GEOS is not Y2K compliant, so if current file has in <tt/filehandle.date.year/ value less than 86
you can safely assume that it is e.g. 2004 and not 1904.
<sect2>filehandle
<p>
@ -1423,10 +1422,10 @@ default icons and the number of selected icon will be returned from window proce
DB_ICON(OK, DBI_X_0, DBI_Y_0),
...
</verb></tscreen>
Note that position is counted from top left corner of window, not entire screen and that the 'x'
Note that the position is counted from top left corner of window, not entire screen and that the 'x'
position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
<tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), default positions
which will make icons to appear on default window directly in the place where you would expect them.
which will make icons to appear on default window exactly where you would expect them.
<p>
<tt/DB_TXTSTR (x, y, text)/ will cause to show given text in the window.
<p>
@ -1448,8 +1447,7 @@ will cause to appear the word ``foo'' in the window, but you may store the point
previous example and points to place where text is to be stored. Note that the contents of this
place will be shown upon creating window. <tt/length/ is the maximum number of characters to input.
<p>
<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. I'm not sure, what this really
mean.
<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. It is called on every keypress.
<p>
<tt/DB_GRPHSTR(ptr)/ - data for this command is the pointer for <tt/GraphicsString/ commands.
<p>