Add some library documentation

include/c64/asm6502.h

@@ -3,6 +3,8 @@
 
 #include "types.h"
 
+// Base form for the 6502 instructions
+
 enum AsmIns
 {
 	// Implied
@@ -82,30 +84,46 @@ enum AsmIns
 	ASM_JSR = 0x2c
 };
 
+// the asm_ instructions emit a machine instruction at the given
+// location and return the size.
+
+// implied
 inline byte asm_np(byte * ip, AsmIns ins);
 
+// accu (e.g. rol/ror)
 inline byte asm_ac(byte * ip, AsmIns ins);
 
+// zero page
 inline byte asm_zp(byte * ip, AsmIns ins, byte addr);
 
+// relative branch
 inline byte asm_rl(byte * ip, AsmIns ins, byte addr);
 
+// immediate
 inline byte asm_im(byte * ip, AsmIns ins, byte value);
 
+// zero page indexed by x
 inline byte asm_zx(byte * ip, AsmIns ins, byte addr);
 
+// zero page indexed by y
 inline byte asm_zy(byte * ip, AsmIns ins, byte addr);
 
+// absolute
 inline byte asm_ab(byte * ip, AsmIns ins, unsigned addr);
 
+// indirect (jmp)
 inline byte asm_in(byte * ip, AsmIns ins, unsigned addr);
 
+// absolute indexed by x
 inline byte asm_ax(byte * ip, AsmIns ins, unsigned addr);
 
+// absolute indexed by y
 inline byte asm_ay(byte * ip, AsmIns ins, unsigned addr);
 
+// zero page indirect indexed by x
 inline byte asm_ix(byte * ip, AsmIns ins, byte addr);
 
+// zero page indirect indexed by y
 inline byte asm_iy(byte * ip, AsmIns ins, byte addr);
 
 #pragma compile("asm6502.c")

include/c64/joystick.h

@@ -4,6 +4,10 @@
 extern signed char	joyx[2], joyy[2];
 extern bool			joyb[2];
 
+// poll joystick input for joystick 0 or 1 and place
+// the x/y direction and the button status into the joyx/y/b
+// arrays for
+
 void joy_poll(char n);
 
 #pragma compile("joystick.c")

include/c64/kernalio.h

@@ -1,6 +1,7 @@
 #ifndef C64_KERNALIO_H
 #ifndef C64_KERNALIO_H
 
+// Error and status codes returned by krnio_status
 
 enum krnioerr
 {
@@ -15,36 +16,70 @@ enum krnioerr
 	KRNIO_NODEVICE = 0x80
 };
 
+// Set filename for next krnio_open operation, make sure
+// that the string is still valid when calling krnio_open
+
 void krnio_setnam(const char * name);
 
+// open a kernal file/stream/io channel, returns true on success
+
 bool krnio_open(char fnum, char device, char channel);
 
+// close a kernal file/stream/io channel
+
 void krnio_close(char fnum);
 
+// get the error / status of the last io operation
+
 krnioerr krnio_status(void);
 
+// select the given file for stream output
 
 bool krnio_chkout(char fnum);
 
+// select the given file for stream input
+
 bool krnio_chkin(char fnum);
 
+// clear input and output file selection
+
 void krnio_clrchn(void);
 
+// write a single byte to the current output channel
+
 bool krnio_chrout(char ch);
 
+// read a single byte from the current input channel
+
 int krnio_chrin(void);
 
+// read a single byte from the given file/channel, returns
+// a negative result on failure.  If this was the last byte
+// the bit #8 (0x0100) will be set in the return value
+
 int krnio_getch(char fnum);
 
+// write a single byte to the given file/channel, returns
+// a negative value on failure.
+
 int krnio_putch(char fnum, char ch);
 
+// write an array of bytes to the given file/channel
 
 int krnio_write(char fnum, const char * data, int num);
 
+// write a zero terminated string to the given file/channel
+
 int krnio_puts(char fnum, const char * data);
 
+// read an array of bytes from the given file, returns the number
+// of bytes read, or a negative number on failure
+
 int krnio_read(char fnum, char * data, int num);
 
+// read a line from the given file, terminated by a CR or LF character
+// and appends a zero byte.
+
 int krnio_gets(char fnum, char * data, int num);
 
 #pragma compile("kernalio.c")

include/c64/keyboard.h

@@ -23,9 +23,18 @@
 #define KEY_F6			(139)
 #define KEY_F8			(140)
 
+// map of keyboard codes to PETSCII, first 64 without shift
+// second 64 with shift
+
 extern const char keyb_codes[128];
 
-extern byte keyb_matrix[8], keyb_key;
+// current status of key matrix 
+extern byte keyb_matrix[8];
+
+// current key
+extern byte keyb_key;
+
+// poll keyboard matrix
 
 void keyb_poll(void);
 

include/c64/rasterirq.h

@@ -26,28 +26,56 @@ enum RIRQCodeIndex
 	RIRQ_SIZE   = 31
 };
 
+// One raster interrupt operation, handles up to five writes
+// to arbitrary memory location, or one wait and four writes.
 typedef struct RIRQCode
 {	
 	byte		size;
 	byte		code[RIRQ_SIZE];
 } RIRQCode;
 
+// Build one raster IRQ operation of the given size (wait + #ops)
 void rirq_build(RIRQCode * ic, byte size);
 
+// Add a write command to a raster IRQ
 inline void rirq_write(RIRQCode * ic, byte n, void * addr, byte data);
+
+// Change the address of a raster IRQ write command
 inline void rirq_addr(RIRQCode * ic, byte n, void * addr);
+
+// Change the data of a raster IRQ write command
 inline void rirq_data(RIRQCode * ic, byte n, byte data);
+
+// Add a delay of 5 * cycles to a raster IRQ
 inline void rirq_delay(RIRQCode * ic, byte cycles);
 
+// Place a raster IRQ into one of the 16 slots
 inline void rirq_set(byte n, byte row, RIRQCode * write);
+
+// Remove a raster IRQ from one of the 16 slots
 inline void rirq_clear(byte n)
+
+// Change the vertical position of the raster IRQ of one of the slots
 inline void rirq_move(byte n, byte row);
 
 
+// Initialize the raster IRQ system with either the kernal IRQ vector
+// or the hardware IRQ vector if the kernal ROM is turned off (which is
+// the less resource hungry option)
 void rirq_init(bool kernalIRQ);
+
+// Start raster IRQ
 void rirq_start(void);
+
+// Stop raster IRQ
 void rirq_stop(void);
+
+// Sort the raster IRQ, must be performed at the end of the frame after changing 
+// the vertical position of one of the interrupt operatins.
 void rirq_sort(void);
+
+// Wait for the last raster IRQ op to have completed.  Must be called before a
+// sort if the raster IRQ system is active
 void rirq_wait(void);
 
 #pragma compile("rasterirq.c")

include/c64/sprites.h

@@ -3,35 +3,79 @@
 
 #include "vic.h"
 
+// initialize non virtualized sprite system, using only the eight hardware sprites
 
 void spr_init(char * screen);
 
+// set one sprite with the given attributes
+
 void spr_set(char sp, bool show, int xpos, int ypos, char image, char color, bool multi, bool xexpand, bool yexpand);
 
+// show or hide a sprite
+
 inline void spr_show(char sp, bool show);
 
+// move a sprite the
+
 inline void spr_move(char sp, int xpos, int ypos);
 
+// change the image of a sprite
+
 inline void spr_image(char sp, char image);
 
+// change the color of a sprite
+
 inline void spr_color(char sp, char color);
 
+// The virtual sprite system works with the rasterirq library to multiplex
+// 16 virtual sprites onto the actual eight hardware sprites.  It uses the slots
+// 0 to 8 of the rasterirq library to switch the sprites mid screen.  The
+// application has to race the beam and call at least the vspr_update every
+// bottom of the frame to reset the top eight sprites.
+//
+// A usual frame would look like this:
+//
+// - off screen game code
+// vspr_sort();
+// - more game code
+// rirq_wait();
+// vspr_update();
+// - more raster irq stuff
+// rirq_sort();
+//
+
+// initialize the virtual (multiplexed) sprite system, offering 16 sprites
 
 void vspr_init(char * screen);
 
+// set one sprite with the given attribute
 
 void vspr_set(char sp, int xpos, int ypos, char image, char color);
 
+// move a virtual sprite
+
 inline void vspr_move(char sp, int xpos, int ypos);
 
+// change the image of a virtual sprite
+
 inline void vspr_image(char sp, char image);
 
+// change the color of a virtual sprite
+
 inline void vspr_color(char sp, char color);
 
+// hide a virtual sprite, show again by moving it into the visual range
+
 inline void vspr_hide(char sp);
 
+
+// sort the virtual sprites by their y-position
+
 void vspr_sort(void);
 
+// update the virtual sprites.  Must be called every frame before sorting
+// the raster irq list.
+
 void vspr_update(void);
 
 

include/c64/vic.h

@@ -73,6 +73,11 @@ struct VIC
 
 };
 
+// set the 16k Bank for the vic
+// 0 : 0x0000..0x3fff
+// 1 : 0x4000..0x7fff
+// 2 : 0x8000..0xbfff
+// 3 : 0xc000..0xffff
 void vic_setbank(char bank);
 
 enum VicMode
@@ -84,18 +89,27 @@ enum VicMode
 	VICM_HIRES_MC
 };
 
+// set the display mode and base address. This will also
+// adapt the bank.
 void vic_setmode(VicMode mode, char * text, char * font);
 
+// put a sprite at the given x/y location, taking care of the
+// x MSB
 inline void vic_sprxy(byte s, int x, int y);
 
+// wait for the beam to reach the bottom of the visual area
 inline void vic_waitBottom(void);
 
+// wait for the beam to reach the top of the frame
 inline void vic_waitTop(void);
 
+// wait for the top of the frame and then for the bottom of the visual area
 inline void vic_waitFrame(void);
 
-inline void vic_waitLine(int line);
+// wait for a specific raster line
+void vic_waitLine(int line);
 
+// reference to the VIC chip
 #define vic	(*((struct VIC *)0xd000))
 
 #pragma compile("vic.c")

include/gfx/bitmap.h

@@ -50,77 +50,115 @@ enum BlitOp
 
 extern char NineShadesOfGrey[9][8];
 
-
+// Fast unsigned integer square root
 unsigned bm_usqrt(unsigned n);
 
-
+// Initialize a bitmap structure, size is given in char cells (8x8 pixel)
 void bm_init(Bitmap * bm, char * data, char cw, char ch);
 
+// Initialize a bitmap structure with allocated memory, size is given in char cells (8x8 pixel)
 void bm_alloc(Bitmap * bm, char cw, char ch);
 
+// Free the memory of a bitmap
 void bm_free(Bitmap * bm);
 
+// Fill a bitmap with the data byte
 void bm_fill(Bitmap * bm, char data);
 
 
 void bm_scan_fill(int left, int right, char * lp, int x0, int x1, char pat);
 
+// Fill a circle with center x/y and radius r and the 8x8 pattern pat.
 void bm_circle_fill(Bitmap * bm, ClipRect * clip, int x, int y, char r, const char * pat);
 
+// Fill a trapezoid with horizontal top and bottom, top left is in x0, top right in x1
+// dx0 and dx1 are the horizontal delta for each line. Coordinates are in 16.16 fixed point
+// numbers.  y0 and y1 are vertical coordinates in pixel.
 void bm_trapezoid_fill(Bitmap * bm, ClipRect * clip, long x0, long x1, long dx0, long dx1, int y0, int y1, const char * pat)
 
+// Fill a triangle with a pattern, coordinate pairs x0/y0, x1/y1 and x2/y2 are in pixel
 void bm_triangle_fill(Bitmap * bm, ClipRect * clip, int x0, int y0, int x1, int y1, int x2, int y2, const char * pat);
 
+// Fill a quad with a pattern, coordinate pairs are in pixel
 void bm_quad_fill(Bitmap * bm, ClipRect * clip, int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3, const char * pat);
 
+// Fill a convex polygon with a pattern, coordinate pairs x[]/y[] are in pixel
 void bm_polygon_fill(Bitmap * bm, ClipRect * clip, int * x, int * y, char num, const char * pat);
 
+// Fill an arbitrary polygon with a pattern, coordinate pairs x[]/y[] are in pixel, maximum size is
+// sixteen vertices
 void bm_polygon_nc_fill(Bitmap * bm, ClipRect * clip, int * x, int * y, char num, const char * pat);
 
+// Set a single pixel
 inline void bm_set(Bitmap * bm, int x, int y);
+
+// Clear a single pixel
 inline void bm_clr(Bitmap * bm, int x, int y);
+
+// Get the state of a single pixel
 inline bool bm_get(Bitmap * bm, int x, int y);
+
+// Set or clear a single pixel
 inline void bm_put(Bitmap * bm, int x, int y, bool c);
 
-
+// Draw an unclipped line using an eight bit pattern
 void bmu_line(Bitmap * bm, int x0, int y0, int x1, int y1, char pattern);
 
+// Draw a clipped line using an eight bit pattern
 void bm_line(Bitmap * bm, ClipRect * clip, int x0, int y0, int x1, int y1, char pattern);
 
-
+// Unclipped bit blit
 void bmu_bitblit(Bitmap * dbm, int dx, int dy, Bitmap * sbm, int sx, int sy, int w, int h, const char * pattern, BlitOp op);
 
+// Unclipped rectangle fill
 inline void bmu_rect_fill(Bitmap * dbm, int dx, int dy, int w, int h);
 
+// Unclipped rectangle clear
 inline void bmu_rect_clear(Bitmap * dbm, int dx, int dy, int w, int h);
 
+// Unclipped rectangle pattern fill
 inline void bmu_rect_pattern(Bitmap * dbm, int dx, int dy, int w, int h, const char * pattern);
 
+// Unclipped rectangle copy
 inline void bmu_rect_copy(Bitmap * dbm, int dx, int dy, Bitmap * sbm, int sx, int sy, int w, int h);
 
 
+// Clipped bit blit
 void bm_bitblit(Bitmap * dbm, ClipRect * clip, int dx, int dy, Bitmap * sbm, int sx, int sy, int w, int h, const char * pattern, BlitOp op);
 
+// Clipped rectangle fill
 inline void bm_rect_fill(Bitmap * dbm, ClipRect * clip, int dx, int dy, int w, int h);
 
+// Clipped rectangle clear
 inline void bm_rect_clear(Bitmap * dbm, ClipRect * clip, int dx, int dy, int w, int h);
 
+// Clipped rectangle pattern fill
 inline void bm_rect_pattern(Bitmap * dbm, ClipRect * clip, int dx, int dy, int w, int h, const char * pattern);
 
+// Clipped rectangle copy
 inline void bm_rect_copy(Bitmap * dbm, ClipRect * clip, int dx, int dy, Bitmap * sbm, int sx, int sy, int w, int h);
 
+
+// Unclipped text rendering
 int bmu_text(Bitmap * bm, const char * str, char len);
 
+// Calculate size of a char range
 int bmu_text_size(const char * str, char len);
 
+// Unclipped text output to an arbitrary location using a bit blit
 int bmu_put_chars(Bitmap * bm, int x, int y, const char * str, char len, BlitOp op);
 
+// Clipped text output to an arbitrary location using a bit blit
 int bm_put_chars(Bitmap * bm, ClipRect * clip, int x, int y, const char * str, char len, BlitOp op);
 
-int bm_put_string(Bitmap * bm, ClipRect * clip, int x, int y, const char * str, BlitOp op);
+// Clipped text output of a zero terminated string to an arbitrary location using a bit blit
+inline int bm_put_string(Bitmap * bm, ClipRect * clip, int x, int y, const char * str, BlitOp op);
 
+
+// Linear transformation of a source bitmap rectangle to a destination rectangle
 int bm_transform(Bitmap * dbm, ClipRect * clip, int dx, int dy, int w, int h, Bitmap * sbm, int sx, int sy, int dxx, int dxy, int dyx, int dyy);
 
+
 #pragma compile("bitmap.c")
 
 #endif