Libraries
Background
DOGXL.c – DOGXL LCD driver
This module provides the glue between tollosDraw and a DOGXL LCD screen, including a screen buffer.
Measured performance, etc.:
- Time to write all pels using drawSetPelIO: 7.7ms (96 MHz MCU)
- Time to send whole buffer to DOGXL: 5.3 ms (12 MHz SPI)
- Power consumption: 1.04 mA @ 3.3V (160L-7, all pels full on).
This glue assumes the DOGXL is attached to a microcontroller in the 3-wire 9-bit SPI configuration, using the primary SPI port and associated select line (as defined by the spi9 glue functions), and with the SPI clock set to 12 MHz.
This 3-wire 9-bit SPI combination is about 33x faster than 400 kHz I2C and theoretically could write the 4160-byte screen buffer in 3.12 ms, running the bus clock at 12 MHz. In practice, there is some inter-byte overhead and the measured time is 5.3 ms.
At this speed it is unlikely to be valuable to double-buffer the screen in order to only send changes, because the inter-byte overhead is already significant.
The screen buffer for DOGXL is maintained in the order that is is required for sending to the display; this is determined by the UC1610 controller on the display.
Each byte stored covers one pel in each of four rows in a column of four pels (4 rows together are called a ‘page’ in the UC1610 datasheet). The byte in which a given pel is to be found is therefore given by ((DOGY−1-y)/4)*160+x, with the two bits being determined by y%4. Note that the two bits for the top row go into the two least significant bits of the byte.
The “lookup tables” pelshift and pelmasks are used to speed up the retrieval and setting of a pel within a byte.
X and Y coordinates are always checked so there is no possibility of buffer overrun or addressing exception.
Pel data values are not checked on set (they may cause local pel corruption but will not cause addressing errors).
| Functions | |
|---|---|
| drawClearIO | set every pel to the same value |
| drawFromRGBIO | convert RGB to a pel value |
| drawGetPelIO | get pel value |
| drawInitIO | initialize display and discover its configuration |
| drawRawIO | read and/or write the screen buffer ‘as is’ |
| drawSetPelIO | set pel to a new value |
| drawStopIO | stop the display device |
| drawToRGBIO | convert pel value to RGB |
| drawWriteIO | write buffer to screen (draw) |
drawClearIO – set every pel to the same value
void drawClearIO(int pel);
pel – new value for the screen
This sets every pel in the screen buffer to the provided value.
drawFromRGBIO – convert RGB to a pel value
int drawFromRGBIO(drawRGB rgb);
rgb – colour value [0..255 in each]
returns the corresponding pel value
This converts standard RGB to a private pel value suitable for use in drawSetPelIO, etc.
drawGetPelIO – get pel value
int drawGetPelIO(int x, int y);
x – pel X coordinate
y – pel Y coordinate
returns the value of the pel at x, y
If x or y is too large or less than zero, 0 is returned.
drawInitIO – initialize display and discover its configuration
int drawInitIO(drawConfig *config);
config – configuration structure (always set)
returns 0 if OK, negative if error (e.g., device not available, or bus error)
This function initializes the display, clears the screen buffer to white, and sets the configuration structure so the caller can determine the device geometry and characteristics. The screen buffer is cleared and the configuration is set even if an error occurred during hardware initialization.
The DOGXL device is write only when SPI-connected, so this function always returns 0 unless there is an SPI bus error.
drawRawIO – read and/or write the screen buffer ‘as is’
void drawRawIO(byte *to, const byte *from);
to – first byte to copy screen buffer to, or NULL for no read
from – first byte to copy screen buffer to, or NULL for no write
This function is used to provide private access to the screen buffer, which will be in device-specific format. The entire buffer is copied, with a read (copy to the caller) taking place before the write (copy to the screen buffer)
This is intended for experimental use or when performance is critical. Tollos code rules do not permit direct cross-module memory sharing, so a copy is still necessary.
drawSetPelIO – set pel to a new value
void drawSetPelIO(int x, int y, int pel);
x – pel X coordinate
y – pel Y coordinate
pel – new value for the pel
If x or y is too large or less than zero, this function has no effect. If pel is too large some pels in the buffer may be undefined.
The code below runs in about 1.85 us on a 96 MHz MCU, so to write every pel on the screen individually takes about 7.7ms.
drawStopIO – stop the display device
void drawStopIO(void);
This puts the device into a clean or low power/off mode. For LCDs this should save power as well as properly discharging the display.
drawToRGBIO – convert pel value to RGB
void drawToRGBIO(int pel, drawRGB *rgb);
pel – pel value to convert
rgb – returned colour value [0..255 in each]
This converts a private pel value back to standard RGB.
drawWriteIO – write buffer to screen (draw)
int drawWriteIO(void);
returns 0 if OK, negative if error (e.g., bus error)
This function sends the screen buffer to the device.
For the DOGXL, this is done by sending a ‘page’ at a time, where a page is four rows of pels, starting at the top of the screen. The bytes to be sent are a vertical swathe of the pels, 2 bits per row.
Later a dirty flag per page might be added, so that only changed pages will be sent.
The entire screen buffer could be sent as a single write; the send by page has the advantage that if a noise burst corrupts a transmission then only one page will be corrupt instead of perhaps the entire screen.
The time to write all 26 pages to the DOGXL using this code and an SPI clock of 12 MHz (the maximum, using the 3-wire 9-bit connection) is 5.3 ms (800,000 9-bit ‘bytes’ per second).