display

display Module

Class TFT

This class includes full support for TFT display modules used on Sipeed MAIX boards.

---

Create the TFT class instance

Before using the display, the display module must be imported and the instance of the TFT class has to be created:

import display
tft = display.TFT()

Framebuffer

TFT module can draw to the display directly or using the framebuffer.
If frame buffer is used, no changes on the display will be visible until the tft.show() command is executed.
After initialization, the framebuffer is used and tft.useFB() command can be used to change the mode.

Colors

Color values are given as 16 bit integer numbers, coded as 5-6-5 RGB values.
For example: 0xF800 represents the RED color.
Color values can also be given as a tuple of RGB values, for example (255, 0, 0) (red collor).

The following color constants are defined and can be used as color arguments:

BLACK, NAVY, DARKGREEN, DARKCYAN, MAROON, PURPLE
OLIVE, LIGHTGREY, DARKGREY, BLUE, GREEN, CYAN, RED
MAGENTA, YELLOW, WHITE, ORANGE, GREENYELLOW, PINK

Drawing

All drawings coordinates are relative to the display window.

Initialy, the display window is set to full screen, and there are methods to set the window to the part of the full screen.

Fonts

9 bit-mapped fonts and one vector 7-segment font are included. Unlimited number of fonts from file can also be used.

The following font constants are defined and can be used as font arguments:

FONT_Default, FONT_DefaultSmall, FONT_DejaVu18, FONT_Dejavu24
FONT_Ubuntu, FONT_Comic, FONT_Minya, FONT_Tooney, FONT_Small
FONT_7seg

External fonts (from file) can be used.
Web application Font creator is provided to convert any TTF or OpenType font to binary .fon file suitable for use with this module.
Create the desired font, download it and copy to the internal file system. You can select it using tft.font() method.

Touch panel

Touch panels are not supported at the moment, but the support will be added later.

---

Methods

tft.init( type, [, opt_args] )

Initialize the SPI interface and set the warious operational modes.

All arguments are optional and of KW argument type and must be entered as arg=value.

Argument	Description
type	optional, sets the display controler type, for now this argument is ignored.
width	optional, default=240, display phisical width in pixels (display's smaller dimension).
height	optional, default=320, display phisical height in pixels (display's larger dimension).
speed	optional, default=5000000, SPI speed for display comunication in Hz. Maximal usable speed depends on display type and the wiring length
rot	optional, default=LANDSCAPE; Set the initial display orientation
bgr	optional, default=True, set to True if the display panel has BGR matrix. If you get inverted RED and BLUE colors, try to change this argument
splash	optional, default=True; If set to False do not display "MicroPython" string in RGB colors atfter initialization

tft.deinit()

De initialize the used spi device(s), free all used resources.
Not used at the moment.

tft.pixel(x, y [,color])

Draw the pixel at position (x,y).
If color is not given, current foreground color is used.

tft.line(x, y, x1, y1 [,color])

Draw the line from point (x,y) to point (x1,y1)
If color is not given, current foreground color is used.

tft.lineByAngle(x, y, start, length, angle [,color])

Draw the line from point (x,y) with length lenght starting st distance start from center.
If color is not given, current foreground color is used.
The angle is given in degrees (0~359).

tft.triangle(x, y, x1, y1, x2, y2 [,color, fillcolor])

Draw the triangel between points (x,y), (x1,y1) and (x2,y2).
If color is not given, current foreground color is used.
If fillcolor is given, filled triangle will be drawn.

tft.circle(x, y, r [,color, fillcolor])

Draw the circle with center at (x,y) and radius r.
If color is not given, current foreground color is used.
If fillcolor is given, filled circle will be drawn.

tft.ellipse(x, y, rx, ry [opt, color, fillcolor])

Draw the circle with center at (x,y) and radius r.
If color is not given, current foreground color is used.
*opt argument defines the ellipse segment to be drawn, default id 15, all ellipse segments.

Multiple segments can drawn, combine (logical or) the values.

• 1 - upper left segment
• 2 - upper right segment
• 4 - lower left segment
• 8 - lower right segment

If fillcolor is given, filled elipse will be drawn.

tft.arc(x, y, r, thick, start, end [color, fillcolor])

Draw the arc with center at (x,y) and radius r, starting at angle start and ending at angle end
The thicknes of the arc outline is set by the thick argument
If fillcolor is given, filled arc will be drawn.

tft.poly(x, y, r, sides, thick, [color, fillcolor, rotate])

Draw the polygon with center at (x,y) and radius r, with number of sides sides
The thicknes of the polygon outline is set by the thick argument
If fillcolor is given, filled polygon will be drawn.
If rotate is given, the polygon is rotated by the given angle (0~359)

tft.rect(x, y, width, height, [color, fillcolor])

Draw the rectangle from the upper left point at (x,y) and width width and height height
If fillcolor is given, filled rectangle will be drawn.

tft.roundrect(x, y, width, height, r [color, fillcolor])

Draw the rectangle with rounded corners from the upper left point at (x,y) and width width and height height
Corner radius is given by r argument.
If fillcolor is given, filled rectangle will be drawn.

tft.clear([color])

Clear the screen with default background color or specific color if given.

tft.clearWin([color])

Clear the current display window with default background color or specific color if given.

tft.orient(orient)

Set the display orientation.
Use one of predifined constants:
tft.PORTRAIT, tft.LANDSCAPE, tft.PORTRAIT_FLIP, tft.LANDSCAPE_FLIP

tft.font(font [,rotate, transparent, fixedwidth, dist, width, outline, color])

Set the active font and its characteristics.

Argument	Description
font	required, use font name constant or font file name
rotate	optional, set font rotation angle (0~360)
transparent	only draw font's foreground pixels
fixedwidth	draw proportional font with fixed character width, max character width from the font is used
dist	only for 7-seg font, the distance between bars
width	only for 7-seg font, the width of the bar
outline	only for 7-seg font, draw the outline
color	font color, if not given the current foreground color is used

tft.attrib7seg(dist, width, outline, color)

Set characteristics of the 7-segment font

Argument	Description
dist	the distance between bars
width	the width of the bar
outline	outline color
color	fill color

tft.fontSize()

Return width and height of the active font

tft.text(x, y, text [, color])

Display the string text at possition (x,y).
If color is not given, current foreground color is used.

• x: horizontal position of the upper left point in pixels, special values can be given:
  • CENTER, centers the text
  • RIGHT, right justifies the text
  • LASTX, continues from last X position; offset can be used: LASTX+n
• y: vertical position of the upper left point in pixels, special values can be given:
  • CENTER, centers the text
  • BOTTOM, bottom justifies the text
  • LASTY, continues from last Y position; offset can be used: LASTY+n
• text: string to be displayed. Two special characters are allowed in strings:
  • \r CR (0x0D), clears the display to EOL
  • \n LF (ox0A), continues to the new line, x=0

tft.textWidth(text)

Return the width of the string text using the active font fontSize

tft.textClear(x, y, text [, color])

Clear the the screen area used by string text at possition (x,y) using the bacckground color color.
If color is not given, current background color is used.

tft.image(x, y, file [,scale, type])

Display the image from the file file on position (x,y)

• JPG images are supported.
  Baseline only. Progressive and Lossless JPEG format are not supported.
  Image size: Up to 65520 x 65520 pixels
  Color space: YCbCr three components only. Gray scale image is not supported.
  Sampling factor: 4:4:4, 4:2:2 or 4:2:0.
• BMP images are supported.
  Only uncompressed RGB 24-bit with no color space information BMP images can be displayed.
• RAW image format is supported.
  Only fool screen images are supported for now, e.g. the saved framebuffer.
• Constants tft.CENTER, tft.BOTTOM, tft.RIGHT can be used for x&y
• x and y values can be negative

scale (jpg): image scale factor: 0 to 3; if scale>0, image is scaled by factor 1/(2^scale) (1/2, 1/4 or 1/8)
scale (bmp): image scale factor: 0 to 7; if scale>0, image is scaled by factor 1/(scale+1)
type: optional, set the image type, constants tft.JPG, tft.BMP or tft.RAW can be used. If not set, file extension and/or file content will be used to determine the image type.

tft.setwin(x, y, x1, y1)

Set active display window to screen rectangle (x,y) - (x1,y1)

tft.resetwin()

Reset active display window to full screen size.

tft.savewin()

Save active display window dimensions.

tft.restorewin()

Restore active display window dimensions previously saved wint savewin().

tft.screensize()

Return the display size, (width, height)

tft.winsize()

Return the active display window size, (width, height)

tft.hsb2rgb(hue, saturation, brightness)

Converts the components of a color, as specified by the HSB model, to an equivalent set of values for the default RGB model.
Returns 16-bit integer value suitable to be used as color argument

Arguments

• hue: float: any number, the floor of this number is subtracted from it to create a fraction between 0 and 1. This fractional number is then multiplied by 360 to produce the hue angle in the HSB color model.
• saturation: float; 0 ~ 1.0
• brightness: float; 0 ~ 1.0

tft.rgb2color(color_tuple)

Converts the RGB components of a color given as a tuple (R, G, B) to the 16-bit RGB565 value used by TFT.
Returns 16-bit integer value suitable to be used as color argument.

tft.get_bg()

Get the default background color

tft.get_fg()

Get the default foreground color

tft.set_bg(color)

Set the default background color

tft.set_fg(color)

Set the default foreground color

tft.tft_setspeed(speed)

Set the display's SPI speed in Hz
Speeds form 1000000 to 16000000 Hz can be set.

tft.show()

Show (send to display) the current content of the frame buffer
Only executes if the current operating mode is framebuffer mode

tft.useFB(True|False)

Set the current operating mode to framebuffer mode or direct mode

tft.FBsave(file_name)

Save the current content of the framebuffer to file.

---