From 0ad8115dabc03f80aef012ca785d0b62c155d381 Mon Sep 17 00:00:00 2001 From: Curtis F Kaylor Date: Sat, 4 Dec 2021 19:16:52 -0500 Subject: [PATCH] Added docs for modules color, direct, dirent, fileio, mouse, stringl, and util --- doc/color.txt | 51 ++++++++++++++++++ doc/direct.txt | 70 ++++++++++++++++++++++++ doc/dirent.txt | 50 +++++++++++++++++ doc/fileio.txt | 139 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/mouse.txt | 109 +++++++++++++++++++++++++++++++++++++ doc/stringl.txt | 72 +++++++++++++++++++++++++ doc/util.txt | 44 +++++++++++++++ 7 files changed, 535 insertions(+) create mode 100644 doc/color.txt create mode 100644 doc/direct.txt create mode 100644 doc/dirent.txt create mode 100644 doc/fileio.txt create mode 100644 doc/mouse.txt create mode 100644 doc/stringl.txt create mode 100644 doc/util.txt diff --git a/doc/color.txt b/doc/color.txt new file mode 100644 index 0000000..4f67ce8 --- /dev/null +++ b/doc/color.txt @@ -0,0 +1,51 @@ +//C02 Color Functions +//Prototype - Subject to Change + + txtclr(c); Sets text color to system color c. + + Note: May call system routine or may print color change + sequence. + + bkgclr(c); Sets background color to system color c. + + Note: May call system routine or may print color change + sequence. + + +Assembly Constants (Defined in System Header file) + + BLACK Code for color Black + BLUE Code for color Blue + GREEN Code for color Green + CYAN Code for color Cyan + RED Code for color Red + MAGNTA Code for color Magenta + YELLOW Code for color Yellow + WHITE Code for color White + + BREAK ASCII code for Break/Stop Key + BCKSPC ASCII code for Backspace key + CLEAR ASCII code for Clear Key + DELETE ASCII code for Delete key + DOWN ASCII code for Cursor Down Key + ENTER ASCII code for Return/Enter key (usually CR) + ESCAPE ASCII code for Escape/Abort key (usually ESC) + FNx ASCII code for Function Key x + HOME ASCII code for Home Key + INSERT ASCII code for Insert Key + LEFT ASCII code for Cursor Left Key + RIGHT ASCII code for Cursor Left Key + TAB ASCII code for Tab Key + UP ASCII code for Cursor Up Key + + BTMLFT ASCII code for Box Drawing Bottom Left Corner + BTMRGT ASCII code for Box Drawing Bottom Right Corner + BTMTEE ASCII code for Box Drawing Bottom to Cetter Tee + CTRCRS ASCII code for Box Drawing Center Cross + HRZLIN ASCII code for Box Drawing Horizontal Line + LFTTEE ASCII code for Box Drawing Left To Center T + RGHTEE ASCII code for Box Drawing Right To Center T + TOPLFT ASCII code for Box Drawing Top Left Corner + TOPRGT ASCII code for Box Drawing Top Right Corner + TOPTEE ASCII code for Box Drawing Top to Center T + VRTLIN ASCII code for Box Drawing Verical Line diff --git a/doc/direct.txt b/doc/direct.txt new file mode 100644 index 0000000..8069862 --- /dev/null +++ b/doc/direct.txt @@ -0,0 +1,70 @@ +This module provides functions for manipulating the current directory on +disks, and disk like devices. It is based on the Windows direct.h header. + +At the beginning of the program use the directives + + #include + #include + +The following functions are defined: + + n,e = getcwd(d,&s); Read the current directory on device d into + string s, returning the length of the directory + name in n and error code e. + + The device specifier d consists of the drive number + and disk number combined by the | operator. + + If the length of the name is 0, there is no current + directory or there was an error. + + r,e = chdir(d,&n); Change the current directory on device d to the + directory name n, returning result code r and + error code e. + + The device specifier d consists of the drive number + and disk number combined by the | operator. + + A result code of 0 indicates success, while any + other value indicates failure. + + r,e = mkdir(d,&n); Create directory with name n on device d, returning + result code r and error code e. + + The device specifier d consists of the drive number + and disk number combined by the | operator. + + A result code of 0 indicates success, while any + other value indicates failure. + + r,e = rmdir(d,&n); Remove directory with name n from device d, + returning result code r and error code e. + + The device specifier d consists of the drive number + and disk number combined by the | operator. + + A result code of 0 indicates success, while any + other value indicates failure. + + d,e = getdrv(); Returns the current drive/disk identifier in d + error code e. + + The disk/drive identifier d consists of the drive + number and disk number combined by the | operator. + + If the returned identifier is 0, an error occured. + + r,e = chgdrv(d); Returns the current drive/disk to d, returning + result code r and error code e. + + The disk/drive identifier d consists of the drive + number and disk number combined by the | operator. + + A result code of 0 indicates success, while any + other value indicates failure. + + n,e = drvnam(d); Return single character drive name r for disk/drive + identifier d and error code e. + + The disk/drive identifier d consists of the drive + number and disk number combined by the | operator. diff --git a/doc/dirent.txt b/doc/dirent.txt new file mode 100644 index 0000000..353f096 --- /dev/null +++ b/doc/dirent.txt @@ -0,0 +1,50 @@ +This module provides functions for reading file directories from +disks, disk like devices, and possihly tapes. + +At the beginning of the program use the directives + + #include + #include + +The following structures are defined: + + struct dirhdr dh; Directory Header. At a minumum this will contain + the member name[128], which is the directory + name or disk label. + + struct dirent de; Directory Entry. At a minumum this will contain + the member name[128], which is the filename. + +The following functions are defined: + + f,e = opndir(d,&n); Open directory named n with options d, returning + channel number f and error code e. + + The options byte d consists of the device number + and drive numbet combined ny the | operator. + + If the return channel number is 0, the directory + was not opened. + + e = clsdir(f); Close directory opened on channel f, returning + error code e. + + n,e = rdhdr(f,&dh); Read directory header into dirhdr structure dh, + returning the length of the header in n and error + code in e. If the header length is 0, then the + directory does not have a header, or there was + and error during the read. + + This should be called after opndir() and before + the first rddir() + + n,e = rddir(f,&de); Read directory entry into dirent structure de, + returning the length of the entry in n and error + code in e. If the entry length is 0, then the + end of the directory was reached or there was + an error during the read. + +Note: This library expects the following functions to be defined: + + fsaddr(); Set File Address + fsname(); Set Filename diff --git a/doc/fileio.txt b/doc/fileio.txt new file mode 100644 index 0000000..6615278 --- /dev/null +++ b/doc/fileio.txt @@ -0,0 +1,139 @@ +File I/O functions for C02 + +This module provides functions for creating, accessing, reading from, +and writing to data files. Depending on the system, the files may +reside cassette tape, floppy disk, or both. + +At the beginning of the program use the directives + + #include + +The following constants are defined: + + DRIVES Number of Disk Drives + DRIVE# Drive Identifier, where # is 0 through DRIVES-1 + + DISKS Number of Disks per Drive + DISK# Disk Identifier, where # is 0 through DISKS-1 + + MABSLT Load Absolute (Use File Header Address) + MRELCT Load Relocate (Use Specified Address) + + MREAD Open File for Reading + MWRITE Open File for Writing + MAPPND Open File for Append + + MBINRY Treat File as Binary instead of Text + +The following functions are defined: + + fsinit(); Initialize file system. This should be called + before any other file functions. + + fsname(&n); Set filename to n. + + Call this before fload() or fsave() to set the + filename. + + fsaddr(&a); Set load, save, read, or write address to a. + + Call this before fload() or fsave() to set the + load or start address, and before fread() or + fwrite() to set the array address. + + e,i = fload(d); Load file into memory using options d, returning + error code e, and ending address i. + + Use fsname(&name) and fsaddr(addr) to set the + filename and load address before calling. + + The options byte d consists of the device number, + drive numbet, and mode combined ny the | operator. + + Mode MABSLT loads the data from the file + into memory starting at the address contained + in the file header. + + Mode MRELCT ignores the starting address in the + file and loads the data into memory starting + at an address specified using setdst() . + + e,i = fsave(d,a); Save memory into file using options and ending + address a. + + Use fsname(&name) and fsaddr(addr) to set the + filename and start address before calling. + + The options byte d consists of the device number + combined with option and/or mode values by use of + the | operator. + + f,e = fopen(d,&n); Open file with name n using options d, returning + channel number f and error code e. + + The options byte d consists of the device number, + drive numbet, and mode combined ny the | operator. + + If the return channel number is 0, the file was + not opened. + + e = fclose(f); Close file on channel f, returning error code e. + + e = feof(f); Return End of File condition for file opened on + channel f. + + A return value of 255 means the End of File was + reached, 0 means it was not reached, while any + other value is an error code. + + e = ferror(f); Return last error on channel f in e. + + Note: Not yet implemented. + + e = fflush(f); Flush output buffer for channel f to file, + returning error code e. + + e = fseek(f, i); Move to position i in file f, returning error + code in e. The specified position is always + relative to the beginning of the file and + specifying $FFFF moves to the end of the file. + + e = rewind(f); Move to beginning file to p, returning error + code in e. + + i,e = ftell(f); Return position in file f in i, and error code + in e. + + c,e = fgetc(f); Read character from channel f, returning the + character in c and error code in e. + + + e = fputc(c,f); Write character c to channel f, returning error + code in e. + + n,e = fgets(f,&s); Read line of up to 128 characters from channel f + into string s, returning the number of characters + read in n and error code in e. + + n,e = fputs(f,&s); Write up to 128 characters of string s to channel + f, returning the number of characters written + in n and error code in e. + + n,e = fputln(f,&s); Write up to 128 characters of string s, followed + by a newline, to channel f, returning the number + of characters written in n and error code in e. + + r,e = read(f,n); Read up to n bytes from channel f into an array, + returning the number of bytes read in rn and error + code in e. + + Use fsaddr(&array) to set the address of the + array before calling. + + w,e = read(f,n); Write n bytes of array to channel f, returning + the number of bytes written in w and error code + in e. + + Use fsaddr(&array) to set the address of the + array before calling. + diff --git a/doc/mouse.txt b/doc/mouse.txt new file mode 100644 index 0000000..70e3e0b --- /dev/null +++ b/doc/mouse.txt @@ -0,0 +1,109 @@ +Mouse Functions for C02 Programs + +This module provides functions to control and read the status of the +mouse on systems that support it. + +At the beginning of the program use the directives + + #include + +The following mouse constants are defined: + + #MHIDE Hide mouse + #MSHOW Show mouse with default cursor + #MCSTM Show mouse with custom cursor + + #MBLEFT Bitmask - Left Mouse Button + #MBMIDL Bitmask - Middle Mouse Button + #MBRGHT Bitmask - Right Mouse Button + +along with the following variables: + + int mousex; Mouse X Position + int mousey; Mouse Y Position + char mouseb; Mouse Button Status + + +and the following functions: + + r = mcnfg(m); Configures the mouse to mode m. Valid modes are: + + #MHIDE - Hide the mouse cursor and disable the mouse. + + #MSHOW - Display the mouse cursor, enable the mouse, + and set the cursor to the default image. + + #MCSTM - Display the mouse cursor and enable the mouse, + but do not set the cursor image. This mode is + not supported on all systems. + + Returns 0 if the mouse was successfully enabled, or + $FF if the mode is invalid, the mouse is not connected, + or the system lacks mouse support. + + r = mread(); Reads the mouse and sets the following values: + + mousex - Horizontal position of the mouse, relative + to the screen pixel positions. + + mousey - Vertical position of the mouse, relative + to the screen positions. + + mouseb - Status of the mouse buttons. The status of a + button can be determined using the expression + mouseb & m, where m is the constant #MBLEFT, + #MBRGHT, or #MBMIDL. This will evaluate to m + if the button is pressed, or 0 if it is not. + + Returns 0 if the mouse was successfully read, or $FF if + the mouse dis1abled or the system lacks mouse support. + + If the read is unsuccesful, then the mousex, mousey, and + mouseb variables will contain unpredictable values. + +Note: This module has no external requirements. Implementation varies by +system. + +Commander X16 + + Uses the Kernal functions mouse_config and mouse_get. Two additional + functions are defined. + + r = mcnfgs(m, f); Configures the mouse and sets the screen scale. + + Valid values for f are the additional constants: + #MSNONE - Do not change the scale. + #MSLOW - Set scale to 320x240. + #MSHIGH - Set scale to 640x480. + + Valid values for m and return values are the same as + for mcnfg(). + + The function mcnfg() sets the scale to 320x480, which + is the screen size set by the x16.h02 system module. + + mscan(); Queries the mouse and retrieves the values for a + subsequent mread(). + + This is called by the default interrupt service routine, + so it does not need to be called unless that routine is + entirely replaced. + + The mousex, mousey, and mouseb variables are aliased to the ABI registers + r0, r1, and r2l, respectively. Calling any functions that use the ABI + registers may overwrite these variables. + +Apple II - Not Implemented + + mcnfg() and mread() will use the routines SetMouse and ReadMouse, respectively. + +Vic 20 - Not Implemented + + Since the screen resolution is less than 255x255, the easiest way to handle this + is to assume a mouse that emulates paddles and reuse the paddle code. + +Commodore 64 and 128 - Not Implementated + + A machine language driver program is needed to read a mouse in proportional mode. + This could be either external to the module or included in it. + \ No newline at end of file diff --git a/doc/stringl.txt b/doc/stringl.txt new file mode 100644 index 0000000..cafbce5 --- /dev/null +++ b/doc/stringl.txt @@ -0,0 +1,72 @@ +String List Manipulation Module for C02 + + +A string list is a contiguous set of mixed length zero-terminated +strings followed by a zero byte (empty string). For example: + + char list = {"one","two","three",0}; + +A string list can be any length. but each entry must be no more than +the maximum string length of 128 characters long. + +The string list functions all make use of the zero-page integer +variable lstptr. Multiple lists can be accessed by saving and restoring +it's value. + +Usage: at the beginning of the program use the directives + + #include + #include + +The following functions are defined: + + setlst(t); Sets the list pointer to the beginning of the string + list t. + + This must be called at least once before calling any + of the following functions. + + Note: Stores &t in lstptr. + + w = strlln(r); Returns the number of entries in string list r as + an integer. + + Note: Calls strlen() and addsra() for each entry in + the list, accumulating the count in temp1 and temp2. + + n, p = strget(s); Reads the next entry from a string list set by a + prior setlst() call into string s. + + Returns length of the entry and the new position + in the string list. When the end of the list is + reached, s is set to an empty string and any further + calls to strget() will also return an empty string. + + Note: Calls setdst(), getlst(), and strcpy(). If n + is not not zero, calls addsra() and updates lstptr. + + n, p = strput(s); Writes string s to a string list set by a prior + setlst() call and terminates the string list. + + Returns length of the entry and the new position in + the string list. + + Note: Calls setsrc(), getlst(), setdst() and + strcpy(). If n is not zero, calls addsra() and + updates lstptr. + + +Note: This module expects the following functions to be defined + + addsra(n); Add accumulator to sorce pointer. + getlst(); Get list pointer + setdst(s); Set destination pointer + setlst(); Set list pointrt + setsrc(s); Set source pointer and initialize index + strcpy(s); String copy alternate entry point. + +along with the zero page variable pairs + + dstptr Destination String Pointer + lstprt List Pointer + srcptr Source String Pointer diff --git a/doc/util.txt b/doc/util.txt new file mode 100644 index 0000000..8126776 --- /dev/null +++ b/doc/util.txt @@ -0,0 +1,44 @@ +Utility Functions for C02 Library Functions + +This module contains miscellaneous functions that aren't suited for +inclusion in any of the existing modules. + +The contents of this module are subject to change, as any of the +functions may be deprecated or moved to other modules in the future. + +At the beginning of the program use the directives + + #include + #include + +The following functions are defined: + + addzpw(z,&n); Adds the 16 bit value &n to the zero page word + with address z. + + Note: Stores the zero page address in temp3. + + adddst(&n); Adds the 16 bit value &n to the destination + pointer. + + Note: Calls the addzpw function, passing dstlo + as the first argument. + + addsrc(&n); Adds the 16 bit value &n to the source pointer. + + Note: Calls the addzpw function, passing srclo + as the first argument. + +Note: This library expects the following to be defined: + +the zero page variables + + srclo,srchi: Source pointer + dstlo,dsthi: Destination pointer + +and the transient variables + + temp0 Temporary storage (Accumulator) + temp1 Temporary storage (X-Index/LSB) + temp2 Temporary storage (Y-Index/MSB) + temp3 Temporary storage (Zero Page Address)