diff --git a/doc/geos.sgml b/doc/geos.sgml index 09bc24ace..7726e7409 100644 --- a/doc/geos.sgml +++ b/doc/geos.sgml @@ -6,7 +6,7 @@ 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> +#define BlockInUse FindBAMBit ... if (!SectInUse(&myTrSe)) { ... block not allocated ... } </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 * myFunct)/ +<tt/void CallRoutine (void *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>