• Utility functions

Utility Functions

Timing

• inline void pause(uint16_t n_clocks) - accurate below 10 clocks
• inline void pause_usec(uint16_t n_usec) - accurate below 10us
• inline void pause_msec(uint16_t n_msec) - accurate to within 10us
• inline void pause_sec(uint16_t n_sec) - accurate to within 10us

Drawing

Notes:

• All screen positions are 0-indexed, x=0..719 and y=0..359.
• All measures of distance (widths, heights, etc.) are 1-indexed
• Black and white are denoted logically from a programmer's perspective (0=black, 1=white)
  • Any flipping necessary to make this visibly the case is done within each function
  • Note in the Lisa framebuffer in memory, 0=white, 1=black!
• No bounds checking on arguments is performed

Fills

• inline void fill_screen8(uint8_t bitval)
  • fills the screen with this repeating 8bit pattern
• inline void fill_screen16(uint16_t bitval)
  • fills the screen with this repeating 16bit pattern
• inline void fill_screen_black(void) { fill_screen16(0); }
• inline void fill_screen_white(void) { fill_screen16(0xFFFF); }
• inline void fill_region8(uint16_t topleftx, uint16_t toplefty, uint16_t width, uint16_t height, uint8_t bitval)
  • topleftx and width may be any (possibly unaligned/unaligning) value
• inline void fill_region16(uint16_t topleftx, uint16_t toplefty, uint16_t width, uint16_t height, uint16_t bitval)
  • topleftx and width may be any (possibly unaligned/unaligning) value
• inline void fill_region_black(uint16_t topleftx, uint16_t toplefty, uint16_t width, uint16_t height) { fill_region16(topleftx, toplefty, width, height, 0); }
  • topleftx and width may be any (possibly unaligned/unaligning) value
• inline void fill_region_white(uint16_t topleftx, uint16_t toplefty, uint16_t width, uint16_t height) { fill_region16(topleftx, toplefty, width, height, 0xFFFF); }
  • topleftx and width may be any (possibly unaligned/unaligning) value

Blitting

• draw_simple_bitmap(uint16_t topleftx, uint16_t toplefty, ptr_t bitmap, uint16_t width, uint16_t height);
  • topleftx and width must be a multiple of 8
  • each bit of bitmap is a pixel
  • bitmaps will be precomputed so that the bytes may be blitted literally for speed
    • (1 = black, 0 = white)

• Status: C version completed

• rle_bitmap.h:
• void draw_rle_bitmap(uint16_t topleftx, uint16_t toplefty, rle_bitmap_pixel_t *bitmap)
  • small size, slow draw
  • topleftx must be a multiple of 8
  • width of bitmap must be a multiple of 4
  • see rle_bitmap.h for definition of rle_bitmap_pixel_t
    • 1 byte/run, 15 repeats of a 4 bit pattern
• void draw_rle8_bitmap(uint16_t topleftx, uint16_t toplefty, rle8_bitmap_pixel_t *bitmap)
  • large size, fast draw
  • topleftx and width of bitmap must be a multiple of 8
  • see rle_bitmap.h for definition of rle8_bitmap_pixel_t
    • 2 bytes/run, 255 repeats of an 8 bit pattern

• Status: C version forthcoming, assembly version shouldn't be required

• ordered_pixel_bitmap.h:
• draw_ordered_pixel_bitmap(uint16_t topleftx, uint16_t toplefty, const ordered_pixel_bitmap_t *bitmap, uint16_t width, uint16_t height, uint8_t bitval, uint16_t usec_per_pixel)
  • topleftx and width may be any (possibly unaligned/unaligning) value
  • ordered pixel bitmap is a struct with a series of uint16_t values and the number of values
    • each value is the 0-indexed row-major order number of the pixel to set
    • image row = (int)val/width
    • image col = val%width

    • yes, this means bitmap width*height <= 65536

  • if bitval = 0, pixels should be set black; if !!bitval, pixels should be set white
    • the image region is assumed to already be filled with the background color
  • each pixel should take usec_per_pixel to draw

    • the amount of time taken to draw a pixel should be known, rounded to the nearest microsecond, hardcoded, and a sleep for MAX(0,usec_per_pixel-<that>) inserted after each pixel

  • this function is intended for relatively slow animations, so slow divisions and modular arithmetic are ok!
• void draw_ordered_pixel_anim(uint16_t topleftx, uint16_t toplefty, const ordered_pixel_anim_t *anim, uint16_t width, uint16_t height, uint8_t bitval)
  • topleftx and width may be any (possibly unaligned/unaligning) value
  • iterates through an array of anim structs pointed to by anim and calls draw_ordered_pixel_bitmap on each until a zero-length termination bitmap is found
  • times to wait between animation segments and speeds for each are provided by the anim structs
• draw_vertically_convex_solid_bitmap(uint16_t toplefty, ptr_t bitmap, uint16_t height, uint8_t bitval)

  • vertically convex solid bitmap is a series of <height> pairs of uint8_t values

    • each pair corresponds to a row/scanline of the image, top to bottom
    • the first byte is the column to start filling and is the first column filled

    • the second byte is the column to stop filling and is the last column filled (stop col >= start col guaranteed)

    • these indices need not be a multiple of 8
  • if bitval = 0, pixels should be set black; if !!bitval, pixels should be set white
    • the image region is assumed to already be filled with the background color

Compression

(Note: the executable will be compressed with UCL and automatically decompressed on load)

• void decompress(void *dest, void *src)