<sect1><tt/serial.h/<label id="serial.h"><p>
-<!--
+The <tt/serial.h/ header file contains definitions for initializing serial
+communication.
+
<itemize>
-<item><ref id="ser_load_driver" name="ser_load_driver">
-<item><ref id="ser_unload" name="ser_unload">
-<item><ref id="ser_install" name="ser_install">
-<item><ref id="ser_uninstall" name="ser_uninstall">
-<item><ref id="ser_open" name="ser_open">
<item><ref id="ser_close" name="ser_close">
<item><ref id="ser_get" name="ser_get">
+<item><ref id="ser_install" name="ser_install">
+<item><ref id="ser_ioctl" name="ser_ioctl">
+<item><ref id="ser_load_driver" name="ser_load_driver">
+<item><ref id="ser_open" name="ser_open">
<item><ref id="ser_put" name="ser_put">
<item><ref id="ser_status" name="ser_status">
-<item><ref id="ser_ioctl" name="ser_ioctl">
+<item><ref id="ser_uninstall" name="ser_uninstall">
+<item><ref id="ser_unload" name="ser_unload">
</itemize>
--->
(incomplete)
<sect1><tt/stdio.h/<label id="stdio.h"><p>
<itemize>
+<item><ref id="_poserror" name="_poserror">
<item><ref id="clearerr" name="clearerr">
<!-- <item><ref id="fclose" name="fclose"> -->
<!-- <item><ref id="fdopen" name="fdopen"> -->
<item><ref id="_heapblocksize" name="_heapblocksize">
<item><ref id="_heapmaxavail" name="_heapmaxavail">
<item><ref id="_heapmemavail" name="_heapmemavail">
-<item><ref id="_poserror" name="_poserror">
<item><ref id="_randomize" name="_randomize">
<item><ref id="_swap" name="_swap">
<item><ref id="abort" name="abort">
<item><ref id="tgi_bar" name="tgi_bar">
<item><ref id="tgi_circle" name="tgi_circle">
<item><ref id="tgi_clear" name="tgi_clear">
+<item><ref id="tgi_done" name="tgi_done">
+<item><ref id="tgi_ellipse" name="tgi_ellipse">
+<item><ref id="tgi_getaspectratio" name="tgi_getaspectratio">
<item><ref id="tgi_getcolor" name="tgi_getcolor">
<item><ref id="tgi_getcolorcount" name="tgi_getcolorcount">
<item><ref id="tgi_getdefpalette" name="tgi_getdefpalette">
-<item><ref id="tgi_done" name="tgi_done">
-<item><ref id="tgi_ellipse" name="tgi_ellipse">
<item><ref id="tgi_geterror" name="tgi_geterror">
<item><ref id="tgi_geterrormsg" name="tgi_geterrormsg">
<item><ref id="tgi_getmaxcolor" name="tgi_getmaxcolor">
<item><ref id="tgi_ioctl" name="tgi_ioctl">
<item><ref id="tgi_line" name="tgi_line">
<item><ref id="tgi_lineto" name="tgi_lineto">
-<item><ref id="tgi_load" name="tgi_load">
<item><ref id="tgi_load_driver" name="tgi_load_driver">
<item><ref id="tgi_outtext" name="tgi_outtext">
<item><ref id="tgi_outtextxy" name="tgi_outtextxy">
+<item><ref id="tgi_setaspectratio" name="tgi_setaspectratio">
<item><ref id="tgi_setcolor" name="tgi_setcolor">
<item><ref id="tgi_setdrawpage" name="tgi_setdrawpage">
<item><ref id="tgi_setpalette" name="tgi_setpalette">
<item><ref id="tgi_setpixel" name="tgi_setpixel">
<item><ref id="tgi_setviewpage" name="tgi_setviewpage">
-<item><ref id="tgi_textheight" name="tgi_textheight">
-<item><ref id="tgi_textstyle" name="tgi_textstyle">
-<item><ref id="tgi_textwidth" name="tgi_textwidth">
+<item><ref id="tgi_gettextheight" name="tgi_gettextheight">
+<item><ref id="tgi_settextstyle" name="tgi_settextstyle">
+<item><ref id="tgi_gettextwidth" name="tgi_gettextwidth">
<item><ref id="tgi_uninstall" name="tgi_uninstall">
<item><ref id="tgi_unload" name="tgi_unload">
</itemize>
<itemize>
<!-- <item><ref id="chdir" name="chdir"> -->
+<item><ref id="exec" name="exec">
<!-- <item><ref id="getcwd" name="getcwd"> -->
+<item><ref id="getopt" name="getopt">
<!-- <item><ref id="lseek" name="lseek"> -->
<!-- <item><ref id="mkdir" name="mkdir"> -->
<!-- <item><ref id="read" name="read"> -->
<quote>
<descrip>
-<tag/Function/Print an error message for the error in <tt/_oserrno/.
+<tag/Function/Print an error message for the error in <tt/_oserror/.
<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/
<tag/Declaration/<tt/void __fastcall__ _poserror (const char* msg);/
<tag/Description/<tt/_poserror/ prints an error message to <tt/stderr/. If
<tt/msg/ is not <tt/NULL/ and not an empty string, it is printed followed by
a colon and a blank. Then the error message for the current contents of
-<tt/_oserrno/ are printed followed by a newline. The message output is the
+<tt/_oserror/ are printed followed by a newline. The message output is the
same as returned by <tt/<ref id="_stroserror" name="_stroserror">/ with an
-argument of <tt/_oserrno/.
+argument of <tt/_oserror/.
<tag/Limits/
<itemize>
<item>Since operating system specific error code are - you guessed it -
operating system specific, the value in <tt/_oserror/ and the message that is
-printed depend on the cc65 target.
+printed depends on the cc65 target.
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
</quote>
+<sect1>exec<label id="exec"><p>
+
+<quote>
+<descrip>
+<tag/Function/Execute a program file.
+<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/
+<tag/Declaration/<tt/int __fastcall__ exec (const char* progname, const char* cmdline);/
+<tag/Description/<tt/exec/ replaces the currently running program by a new one.
+Calling <tt/exec()/ is identical to calling <tt/<ref id="exit" name="exit()">/,
+then loading and starting the program named in the first argument, passing
+the command line specified as second argument. Instead of an empty string,
+a <tt/NULL/ pointer may be passed as second parameter.
+On success, the function does not return. On failure, -1 is returned and
+<tt/errno/ contains an error code.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+<item>On most platforms, the function needs to copy a small stub loader to
+some memory area outside the program space. This may collide with other
+programs. See the platform specific docs on this.
+<item>Because it is necessary to terminate the running program before the
+memory can be reused to load the new one, there is a high chance that the
+function may not be able to return on errors.
+<item>The command line is passed to the new program in the same way as cc65
+programs expect the command line. If the new program is not a cc65 generated
+program, it may not be able to read it.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="exit" name="exit">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>fast<label id="fast"><p>
<quote>
</quote>
+<sect1>getcpu<label id="getcpu"><p>
+
+<quote>
+<descrip>
+<tag/Function/Determine on which CPU the program is running.
+<tag/Header/<tt/<ref id="6502.h" name="6502.h">/
+<tag/Declaration/<tt/unsigned char getcpu (void);/
+<tag/Description/The function checks on which CPU the code is running. It
+returns one of the constants<itemize>
+<item><tt/CPU_6502/
+<item><tt/CPU_65C02/
+<item><tt/CPU_65816/
+</itemize>
+<tag/Limits/<itemize>
+<item>Other, more exotic CPU types are not disinguished.
+</itemize>
+<tag/Availability/cc65
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>getenv<label id="getenv"><p>
<quote>
</quote>
-<sect1>get
cpu<label id="getcpu"><p>
+<sect1>get
opt<label id="getopt"><p>
<quote>
<descrip>
-<tag/Function/Determine on which CPU the program is running.
-<tag/Header/<tt/<ref id="6502.h" name="6502.h">/
-<tag/Declaration/<tt/unsigned char getcpu (void);/
-<tag/Description/The function checks on which CPU the code is running. It
-returns one of the constants<itemize>
-<item><tt/CPU_6502/
-<item><tt/CPU_65C02/
-<item><tt/CPU_65816/
-</itemize>
-<tag/Limits/<itemize>
-<item>Other, more exotic CPU types are not disinguished.
+<tag/Function/Parse command line options.
+<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/
+<tag/Declaration/<tt/int __fastcall__ getopt (int argc, char* const* argv,
+const char* optstring);/
+<tag/Description/The function parses command line arguments, <tt/argc/ and
+<tt/argv/ are the argument count and array passed to <tt/main/. <tt/optstring/
+is a string that contains command line option characters. If a character in
+<tt/optstring/ is followed by a colon, the option requires an argument. An
+option on the command line is recognized if it is one of the option characters
+preceeded by a '-'.
+<tt/getopt/ must be called repeatedly. It will return each option character
+found on the command line and <tt/EOF/ (-1) if there is no other option. An
+option argument is placed in <tt/optarg/, the index of the next element on the
+command line to be processed is placed in <tt/optind/.
+<tag/Limits/<itemize>
+<item>The implementation will not reorder options. A non option on the command
+line will terminate option processing. All remaining arguments are not
+recognized as options, even if the start with a '-' character.
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
</itemize>
-<tag/Availability/cc65
+<tag/Availability/POSIX.2
<tag/Example/None.
</descrip>
</quote>
<tag/Function/Check if a given character is a letter or digit.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isalnum (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a letter or digit. The return value is non zero if the character
-is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a letter or digit. The return value is zero if the character is anything
+else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a letter.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isalpha (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a letter. The return value is non zero if the character is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a letter. The return value is zero if the character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is in the ASCII (0..127) range.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isascii (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is in the range 0..127 (the range of valid ASCII characters) and a non zero
-value if not.
+<tag/Description/The function returns a non zero value if the given argument
+is in the range 0..127 (the range of valid ASCII characters) and zero if not.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a space or tab.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isblank (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a space or tab character. The return value is non zero if the character
-is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a space or tab character. The return value is zero if the character is
+anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a control character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ iscntrl (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a control character. The return value is non zero if the character
-is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a control character. The return value is zero if the character is anything
+else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a digit.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isdigit (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a digit. The return value is non zero if the character is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a digit. The return value is zero if the character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
space).
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isgraph (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a printable character with the exception of space. The return value is non
-zero if the character is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a printable character with the exception of space. The return value is zero
+if the character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a lower case letter.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ islower (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a lower case letter. The return value is non zero if the character is
-anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a lower case letter. The return value is zero if the character is anything
+else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a printable character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isprint (int c);/
-<tag/Description/The function returns a value of zero if the given argument
+<tag/Description/The function returns a non zero value if the given argument
is a printable character (this includes the space character). The return value
-is non zero if the character is anything else.
+is zero if the character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
space or an alphanumeric character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ ispunct (int c);/
-<tag/Description/The function returns a value of zero if the given argument
+<tag/Description/The function returns a non zero value if the given argument
is a printable character, but not a space or anything alphanumeric. The return
-value is non zero if the character is anything else.
+value is zero if the character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a a white-space character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isspace (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a white space character. The return value is non zero if the character is
+<tag/Description/The function returns a non zero value if the given argument
+is a white space character. The return value is zero if the character is
anything else. The standard white space characters are: space, formfeed ('\f'),
newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab
('\v').
<tag/Function/Check if a given character is an upper case letter.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isupper (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is an upper case letter. The return value is non zero if the character is
-anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is an upper case letter. The return value is zero if the character is anything
+else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<tag/Function/Check if a given character is a hexadecimal digit.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isxdigit (int c);/
-<tag/Description/The function returns a value of zero if the given argument
-is a hexadecimal digit (0..9, a..f and A..F). The return value is non zero
-if the character is anything else.
+<tag/Description/The function returns a non zero value if the given argument
+is a hexadecimal digit (0..9, a..f and A..F). The return value is zero if the
+character is anything else.
<tag/Limits/<itemize>
<item>When compiling with <tt/-Os/ the function is actually a macro. The
inline sequence generated by the macro will not work correctly for values
<descrip>
<tag/Function/Resets the break vector to its original value.
<tag/Header/<tt/<ref id="6502.h" name="6502.h">/
-<tag/Declaration/<tt/void __fastcall__ reset_brk (void);/
+<tag/Declaration/<tt/void reset_brk (void);/
<tag/Description/<tt/reset_brk/ resets the break vector to the value it had
before a call to <tt/set_brk/.
<tag/Limits/
</quote>
+<sect1>ser_close<label id="ser_close"><p>
+
+<quote>
+<descrip>
+<tag/Function/Close the port and disable interrupts
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_close (const struct ser_params* params);/
+<tag/Description/Open the port by setting the port parameters and enable interrupts.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+#include <serial.h>
+
+extern char comlynx[];
+
+static void initialize(){
+ struct ser_params params = {
+ SER_BAUD_9600,
+ SER_BITS_8,
+ SER_STOP_1,
+ SER_PAR_MARK,
+ SER_HS_NONE
+ };
+ ser_install(&comlynx); // This will activate the ComLynx
+ CLI();
+ ser_open(&params);
+}
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_get<label id="ser_get"><p>
+
+<quote>
+<descrip>
+<tag/Function/Read a character from serial port.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_get (char* b);/
+<tag/Description/Get a character from the serial port. If no characters are
+available, the function will return SER_ERR_NO_DATA, so this is not a fatal
+error.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+Wait for a character to be available from a serial port.
+<verb>
+char ch;
+while (ser_get(&ch) == SER_ERR_NO_DATA)
+ ;
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_install<label id="ser_install"><p>
+
+<quote>
+<descrip>
+<tag/Function/Install an already loaded driver and return an error code.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_install (void* driver);/
+<tag/Description/The function installs a driver that was already loaded into
+memory (or linked statically to the program). It returns an error code
+(<tt/SER_ERR_OK/ in case of success).
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only be
+used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="ser_load_driver" name="ser_load_driver">,
+<ref id="ser_uninstall" name="ser_uninstall">,
+<ref id="ser_unload" name="ser_unload">
+<tag/Example/<verb>
+extern char lynxser[]; //Include the driver statically instead of loading it.
+
+ser_install(&lynxser);
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_ioctl<label id="ser_ioctl"><p>
+
+<quote>
+<descrip>
+<tag/Function/Platform dependent code extensions.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);/
+<tag/Description/Some platforms have extra serial functions that are not
+supported by standard serial driver functions. You can extend the driver to support
+this extra functionality bt using ser_ioctl functions.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+<item>These functions are not easily portable to other cc65 platforms.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None
+</descrip>
+</quote>
+
+<sect1>ser_load_driver<label id="ser_load_driver"><p>
+
+<quote>
+<descrip>
+<tag/Function/Load and install a serial driver.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_load_driver (const char *name);/
+<tag/Description/Load and install the driver by name.
+Will just load the driver and check if loading was successful.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>ser_open<label id="ser_open"><p>
+
+<quote>
+<descrip>
+<tag/Function/Open the port by setting the port parameters and enable interrupts
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_open (const struct ser_params* params);/
+<tag/Description/Open the port by setting the port parameters and enable interrupts.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+#include <serial.h>
+
+extern char comlynx[];
+
+static void initialize(){
+ struct ser_params params = {
+ SER_BAUD_9600,
+ SER_BITS_8,
+ SER_STOP_1,
+ SER_PAR_MARK,
+ SER_HS_NONE
+ };
+ ser_install(&comlynx); // This will activate the ComLynx
+ CLI();
+ ser_open(&params);
+}
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_put<label id="ser_put"><p>
+
+<quote>
+<descrip>
+<tag/Function/Write a character to a serial port.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (char b);/
+<tag/Description/Send a character via the serial port. There is a transmit
+buffer, but transmitting is not done via interrupt. The function returns
+SER_ERR_OVERFLOW if there is no space left in the transmit buffer.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+ser_put('A');
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_status<label id="ser_status"><p>
+
+<quote>
+<descrip>
+<tag/Function/Return the serial port status.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (unsigned char* status);/
+<tag/Description/Return the serial port status.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None
+</descrip>
+</quote>
+
+
+<sect1>ser_uninstall<label id="ser_uninstall"><p>
+
+<quote>
+<descrip>
+<tag/Function/Uninstall the currently loaded driver but do not unload it.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_uninstall (void);/
+<tag/Description/Uninstall the currently loaded driver but do not unload it.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+<sect1>ser_unload<label id="ser_unload"><p>
+
+<quote>
+<descrip>
+<tag/Function/Uninstall, then unload the currently loaded driver.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_unload (void);/
+<tag/Description/Uninstall, then unload the currently loaded driver.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>set_brk<label id="set_brk"><p>
<quote>
<descrip>
<tag/Function/Clear the drawpage
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_clear (void);/
+<tag/Declaration/<tt/void tgi_clear (void);/
<tag/Description/Clear the drawpage
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
<tag/Function/End graphics mode, switch back to text mode.
Will NOT uninstall or unload the driver!
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_done (void);/
+<tag/Declaration/<tt/void tgi_done (void);/
<tag/Description/End graphics mode, switch back to text mode.
Will NOT uninstall or unload the driver!
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</quote>
+<sect1>tgi_getaspectratio<label id="tgi_getaspectratio"><p>
+
+<quote> <descrip> <tag/Function/Return the pixel aspect ratio.
+<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
+<tag/Declaration/<tt/unsigned tgi_getaspectratio (void);/
+<tag/Description/The function returns the pixel aspect ratio for the current
+driver and display as an 8.8 fixed point value. It may be used to correct
+geometric shapes so they look correct on the display. As an example, a circle
+with a radius of 100 pixels may look elliptic on some driver/display
+combinations if the aspect ratio is not 1.00.
+<tag/Limits/<itemize>
+<item>The aspect ratio is encoded in the TGI driver which assumes a "standard"
+monitor for the given platform. The aspect ratio may be wrong if another
+monitor is used.
+<item>No TGI function will use the aspect ratio. It is up to the programmer to
+make use of it.
+<item>The <ref id="tgi_setaspectratio" name="tgi_setaspectratio"> function can
+be used to change the aspect ratio for a loaded driver. The value is not reset
+by <ref id="tgi_init" name="tgi_init">, so if a driver is linked statically to
+an application, switching into and out of graphics mode will not restore the
+original aspect ratio.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="tgi_setaspectratio" name="tgi_setaspectratio">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>tgi_getcolor<label id="tgi_getcolor"><p>
<quote>
<descrip>
<tag/Function/Return the current drawing color.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getcolor (void);/
+<tag/Declaration/<tt/unsigned char tgi_getcolor (void);/
<tag/Description/The actual color is an index to a palette. During tgi_init
you will get a default palette. The number of colors depend on the platform.
All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some
platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN
and then you change the green of the palette to blue using tgi_setpalette then
after this painting in TGI_COLOR_GREEN will actually be blue.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/<verb>
</descrip>
</quote>
+
<sect1>tgi_getcolorcount<label id="tgi_getcolorcount"><p>
<quote>
<descrip>
<tag/Function/Get the number of available colors.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getcolorcount (void);/
+<tag/Declaration/<tt/unsigned char tgi_getcolorcount (void);/
<tag/Description/Tgi platforms use indexed color palettes. This function
returns the number of entries we can use in the palette.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/<verb>
</descrip>
</quote>
+
<sect1>tgi_getdefpalette<label id="tgi_getdefpalette"><p>
<quote>
<descrip>
<tag/Function/Get the palette installed by default.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/const unsigned char* __fastcall__ tgi_getdefpalette (void);/
+<tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/
<tag/Description/The tgi driver has a default palette that is active at startup.
The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this
palette to work correctly.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_geterror<label id="tgi_geterror"><p>
<quote>
<tag/Function/Return the error code for the last operation.
This will also clear the error.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned char __fastcall__ tgi_geterror (void);/
+<tag/Declaration/<tt/unsigned char tgi_geterror (void);/
<tag/Description/Return the error code for the last operation.
This will also clear the error.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_geterrormsg<label id="tgi_geterrormsg"><p>
<quote>
</descrip>
</quote>
+
<sect1>tgi_getmaxcolor<label id="tgi_getmaxcolor"><p>
<quote>
<descrip>
<tag/Function/Get the highest index of the palette.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getmaxcolor (void);/
+<tag/Declaration/<tt/unsigned char tgi_getmaxcolor (void);/
<tag/Description/Get the highest index of the palette.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_getmaxx<label id="tgi_getmaxx"><p>
<quote>
<descrip>
<tag/Function/Get the maximum x coordinate that can be used on this screen.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_getmaxx (void);/
+<tag/Declaration/<tt/unsigned tgi_getmaxx (void);/
<tag/Description/Get the maximum x coordinate that can be used on this screen.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
-<tag/Availability/cc65
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_getmaxy<label id="tgi_getmaxy"><p>
<quote>
<descrip>
<tag/Function/Get the maximum y coordinate that can be used on this screen.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_getmaxy (void);/
+<tag/Declaration/<tt/unsigned tgi_getmaxy (void);/
<tag/Description/Get the maximum y coordinate that can be used on this screen.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_getpagecount<label id="tgi_getpagecount"><p>
<quote>
<descrip>
<tag/Function/Return the number of screen pages available.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_getpagecount (void);/
+<tag/Declaration/<tt/unsigned tgi_getpagecount (void);/
<tag/Description/Return the number of screen pages available.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="tgi_setdrawpage" name="tgi_setdrawpage">,
</descrip>
</quote>
+
<sect1>tgi_getpalette<label id="tgi_getpalette"><p>
<quote>
<descrip>
<tag/Function/Get the palette installed.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/const unsigned char* __fastcall__ tgi_getpalette (void);/
+<tag/Declaration/<tt/const unsigned char* tgi_getpalette (void);/
<tag/Description/Get the palette installed.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_getpixel<label id="tgi_getpixel"><p>
<quote>
</descrip>
</quote>
+
<sect1>tgi_getxres<label id="tgi_getxres"><p>
<quote>
<descrip>
<tag/Function/Get number of horisontal pixels on the screen.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_getxres (void);/
+<tag/Declaration/<tt/unsigned tgi_getxres (void);/
<tag/Description/Get number of horisontal pixels on the screen.
This is same as tgi_maxx()+1.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_getyres<label id="tgi_getyres"><p>
<quote>
<descrip>
<tag/Function/Get number of vertical pixels on the screen.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_getyres (void);/
+<tag/Declaration/<tt/unsigned tgi_getyres (void);/
<tag/Description/Get number of vertical pixels on the screen.
This is same as tgi_maxy()+1.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/None.
</descrip>
</quote>
+
<sect1>tgi_gotoxy<label id="tgi_gotoxy"><p>
<quote>
</descrip>
</quote>
+
<sect1>tgi_init<label id="tgi_init"><p>
<quote>
<descrip>
<tag/Function/Initialize the already loaded graphics driver.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_init (void);/
+<tag/Declaration/<tt/void tgi_init (void);/
<tag/Description/The tgi_init function will set the default palette to the
-hardware and clear the screen.
+hardware.
<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
+<item><tt/tgi_init/ will not clear the screen. This allows switching between
+text and graphics mode on platforms that have separate memory areas for the
+screens. If you want the screen cleared, call <tt/<ref id="tgi_clear"
+name="tgi_clear">/ after <tt/tgi_init/.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
</descrip>
</quote>
+
<sect1>tgi_install<label id="tgi_install"><p>
<quote>
</quote>
-<sect1>tgi_load<label id="tgi_load"><p>
-
-<quote>
-<descrip>
-<tag/Function/Load and install the matching driver for the given mode.
-<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_load (unsigned char mode);/
-<tag/Description/Load and install the matching driver for the given mode.
-Will just load the driver and check if loading was successul.
-Will not switch to graphics mode.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
-<tag/Availability/cc65
-<tag/See also/Other tgi functions.
-<tag/Example/None.
-</descrip>
-</quote>
-
-
<sect1>tgi_load_driver<label id="tgi_load_driver"><p>
<quote>
<descrip>
-<tag/Function/Load and install the given driver. This function is identical
-to tgi_load with the only difference that the name of the driver is specified
-explicitly.
+<tag/Function/Load and install the given driver.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/void __fastcall__ tgi_load_driver (const char *name);/
<tag/Description/Load and install the driver by name.
-Will just load the driver and check if loading was successul.
+Will just load the driver and check if loading was successful.
Will not switch to graphics mode.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may only
</quote>
+<sect1>tgi_setaspectratio<label id="tgi_setaspectratio"><p>
+
+<quote> <descrip> <tag/Function/Set the pixel aspect ratio.
+<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
+<tag/Declaration/<tt/void __fastcall__ tgi_setaspectratio (unsigned ratio);/
+<tag/Description/The function sets the pixel aspect ratio for the current
+driver and display. The argument is an 8.8 fixed point value. The aspect ratio
+may be used to correct geometric shapes so they look correct on a given
+display. As an example, a circle with a radius of 100 pixels may look elliptic
+on some driver/display combinations if the aspect ratio is not 1.00.
+<tag/Limits/<itemize>
+<item>The aspect ratio is encoded in the TGI driver which assumes a "standard"
+monitor for the given platform. The aspect ratio may be wrong if another
+monitor is used.
+<item>No TGI function will use the aspect ratio. It is up to the programmer to
+make use of it.
+<item>The <tt/tgi_setaspectratio/ function can be used to change the aspect
+ratio for a loaded driver. The value is not reset by <ref id="tgi_init"
+name="tgi_init">, so if a driver is linked statically to an application,
+switching into and out of graphics mode will not restore the original aspect
+ratio.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="tgi_getaspectratio" name="tgi_getaspectratio">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>tgi_setcolor<label id="tgi_setcolor"><p>
<quote>
</descrip>
</quote>
-<sect1>tgi_
textheight<label id="tgi_textheight"><p>
+<sect1>tgi_
gettextheight<label id="tgi_gettextheight"><p>
<quote>
<descrip>
<tag/Function/Calculate the height of the text in pixels according to
the current text style.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_textheight (const char* s);/
+<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextheight (const char* s);/
<tag/Description/Calculate the height of the text in pixels according to
the current text style.
<tag/Limits/<itemize>
</descrip>
</quote>
-<sect1>tgi_
textstyle<label id="tgi_textstyle"><p>
+<sect1>tgi_
settextstyle<label id="tgi_settextstyle"><p>
<quote>
<descrip>
<tag/Function/Set the style for text output.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_textstyle (unsigned char magx, unsigned char magy, unsigned char dir);/
+<tag/Declaration/<tt/void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir);/
<tag/Description/Set the style for text output.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may only
</descrip>
</quote>
-<sect1>tgi_
textwidth<label id="tgi_textwidth"><p>
+<sect1>tgi_
gettextwidth<label id="tgi_gettextwidth"><p>
<quote>
<descrip>
<tag/Function/Calculate the width of the text in pixels according to the current text style.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/unsigned __fastcall__ tgi_textwidth (const char* s);/
+<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextwidth (const char* s);/
<tag/Function/Calculate the width of the text in pixels according to the current text style.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Description/Calculate the width of the text in pixels according to the current text style.
<tag/Function/Uninstall the currently loaded driver but do not unload it.
Will call tgi_done if necessary.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_uninstall (void);/
+<tag/Declaration/<tt/void tgi_uninstall (void);/
<tag/Description/Uninstall the currently loaded driver but do not unload it.
Will call tgi_done if necessary.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/None.
<tag/Function/Uninstall, then unload the currently loaded driver.
Will call tgi_done if necessary.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_unload (void);/
+<tag/Declaration/<tt/void tgi_unload (void);/
<tag/Description/Uninstall, then unload the currently loaded driver.
Will call tgi_done if necessary.
-<tag/Limits/<itemize>
-<item>The function is only available as fastcall function, so it may only
-be used in presence of a prototype.
-</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/None.
projects / cc65 / blobdiff