TiLDA MK3/ugfx

The badge makes use of uGFX for providing drawing functions on the LCD. Most of this functionality is available through the micropython interface, and you may wish to browse the uGFX documentation for more details

Tips and tricks

Tearing

When writing large areas of the screen, a 'tearing' [1] effect may be observed.

The screen module is comprised of a large memory, with one memory location to store the RGB data for each pixel. The LCD driver continuously updates the LCD pixels, by reading the memory in a sequential, line-by-line manner, and updating the LCD with the data from the memory. This 'read line-pointer' moves from the top to the bottom of the screen (when viewed in portrait), at about 70Hz (the refresh rate of the screen)

This large memory as part of the screen means it can be driven by a microcontroller which may have a considerably smaller memory. The microcontroller therefore only needs to update the memory when it whats the content to change.

Consider the scenario where the microcontroller wants to set the screen from one colour to another. The microcontroller needs to update the entire memory (320x240x2 = 153kB) with the new colour. At the same time the 'read line-pointer' is reading the same memory to update the LCD. In this case, tearing occurs if the 'read line-pointer' reads the top half of the memory containing the new colour, but then catches up with microcontroller writing to the memory, then the 'read line-pointer' starts reading the old colour in the bottom half of the memory.

To avoid tearing the 'read line-pointer' should not cross the region the microcontroller is updating. Since the microcontroller writes to the screen slightly slower* than the LCD reads it, providing the microntroller starts writes to the top of the memory just after the LCD starts reading from the top, the read and write pointers will not overlap, and tearing will not occur. To sync the microcontroller with the LCD 'read line-pointer,' there is a vsync/tear output (connected to pin named 'TEAR') which is pulled high when the 'read line-pointer' reaches a given line (default is line 0). This can be turned on and off with ugfx.enable_tear() and ugfx.disable_tear(). To change the line at which the tear output is generated, use ugfx.set_tear_line(0..319).

(*true at line of writing, it now might have been sped up)

Detailed documentation

Note. all co-ordinates are from the top left (battery symbol) corner.

Colour format

Internally, ugfx uses 565 format (5 bits for red and blue, 6 for green). Preset colours are available, for example ugfx.RED, ugfx.ORANGE, etc. To convert from 24 bit RGB format, use ugfx.html_color(0xRRGGBB) to return the 16 bit 565 format.

Containers

ugfx.circle(<x>,<y>,<diameter>,<colour>)

Draws a circle at <x>,<y> of <diameter> with a 1 pixel border of <colour>.

eg. ugfx.circle(180,150,40,ugfx.RED)