ht t p: / / el ect r oni cs. henni ngkar l sen.

com ( C) 2014 Henni ng Kar l sen

UTFT
Arduino and chipKit Universal TFT display library

Manual


UTFT l i br ar y Page 1
PREFACE:
Thi s l i br ar y i s t he cont i nuat i on of my I TDB02_Gr aph, I TDB02_Gr aph16 and RGB_GLCD l i br ar i es f or
Ar dui no and chi pKi t . As t he number of suppor t ed di spl ay modul es and cont r ol l er s st ar t ed t o
i ncr ease I f el t i t was t i me t o make a si ngl e, uni ver sal l i br ar y as i t wi l l be much easi er t o
mai nt ai n i n t he f ut ur e.

Basi c f unct i onal i t y of t hi s l i br ar y was or i gi anl l y based on t he demo- code pr ovi ded by I Tead
st udi o ( f or t he I TDB02 modul es) and NKC El ect r oni cs ( f or t he RGB GLCD modul e/ shi el d) .

Thi s l i br ar y suppor t s a number of 8bi t , 16bi t and ser i al gr aphi c di spl ays, and wi l l wor k wi t h
bot h Ar dui no and chi pKi t boar ds. For a f ul l l i st of t est ed di spl ay modul es and cont r ol l er s,
see t he document UTFT_Supported_display_modules_&_controllers.pdf.

You can al ways f i nd t he l at est ver si on of t he l i br ar y at
http://electronics.henningkarlsen.com/

I f you make any modi f i cat i ons or i mpr ovement s t o t he code, I woul d appr eci at e t hat you shar e
t he code wi t h me so t hat I mi ght i ncl ude i t i n t he next r el ease. I can be cont act ed t hr ough
http://electronics.henningkarlsen.com/contact.php.

For ver si on i nf or mat i on, pl ease r ef er t o version.txt.

IMPORTANT:
When usi ng 8bi t and 16bi t di spl ay modul es t her e ar e some r equi r ement s you must adher e t o.
These r equi r ement s can be f ound i n t he document UTFT_Requirements.pdf.
Ther e ar e no speci al r equi r ement s when usi ng ser i al di spl ays.

Si nce most peopl e have onl y one or possi bl y t wo di f f er ent di spl ay modul es a l ot of memor y has
been wast ed t o keep suppor t f or many unneeded cont r ol l er chi ps.
As of v1. 1 you now have t he opt i on t o easi l y r emove t hi s unneeded code f r omt he l i br ar y. By
di sabl i ng t he cont r ol l er s you don' t need you can r educe t he memor y f oot pr i nt of t he l i br ar y by
sever al Kb. For mor e i nf or mat i on, pl ease r ef er t o memorysaver.h.

I f you ar e usi ng t he AquaLEDSource All in One Super Screw Shield on a chi pKi t Max32, pl ease
r ead t he comment i n hardware/pic32/HW_PIC32_defines.h

I f you ar e usi ng t he CTE TFT LCD/SD Shield for Arduino Due or t he ElecHouse TFT LCD Screen
Shield for Arduino DUE /Taijiuino, pl ease r ead t he comment i n hardware/arm/HW_ARM_defines.h

8 bi t di spl ay shi el ds desi gned f or use on Ar dui no Uno ( and si mi l ar l y si zed boar ds) can now be
used on Ar dui no Megas. Pl ease r ead t he comment i n hardware/avr/HW_AVR_defines.h

The 7 di spl ay modul es have not been t est ed on t he chi pKi t boar ds due t o t he hi gh cur r ent
r equi r ement f or t he LED backl i ght .



Thi s l i br ar y i s l i censed under a CC BY-NC-SA 3.0 ( Cr eat i ve Commons At t r i but i on-
NonCommer ci al - Shar eAl i ke 3. 0 Unpor t ed) Li cense.

For mor e i nf or mat i on see: http://creativecommons.org/licenses/by-nc-sa/3.0/

UTFT l i br ar y Page 2

DEFINED LITERALS:

Alignment
For use with print(), printNumI() and printNumF()

LEFT:
RI GHT:
CENTER:
0
9999
9998

Orientation
For use with InitLCD()

PORTRAI T:
LANDSCAPE:
0
1

VGA Colors
Predefined colors for use with setColor() and setBackColor()

VGA_BLACK VGA_SI LVER VGA_GRAY VGA_WHI TE
VGA_MAROON VGA_RED VGA_PURPLE VGA_FUCHSI A
VGA_GREEN VGA_LI ME VGA_OLI VE VGA_YELLOW
VGA_NAVY VGA_BLUE VGA_TEAL VGA_AQUA
VGA_TRANSPARENT ( onl y val i d f or set BackCol or ( ) )

Display model
For use with UTFT()

Pl ease see UTFT_Supported_display_modules_&_controllers.pdf

INCLUDED FONTS:

SmallFont

Char act er si ze:
Number of char act er s:
8x12 pi xel s
95

BigFont

Char act er si ze:
Number of char act er s:
16x16 pi xel s
95

SevenSegNumFont

Char act er si ze:
Number of char act er s:
32x50 pi xel s
10

UTFT l i br ar y Page 3
FUNCTIONS:

UTFT(Model, RS, WR, CS, RST[, ALE]);
The main class constructor when using 8bit or 16bit display modules.

Parameters: Model : See t he separ at e document f or t he suppor t ed di spl ay modul es
RS: Pi n f or Regi st er Sel ect
WR: Pi n f or Wr i t e
CS: Pi n f or Chi p Sel ect
RST: Pi n f or Reset
ALE: <optional> Onl y used f or l at ched 16bi t shi el ds
Pi n f or Lat ch si gnal

Usage: UTFT myGLCD( I TDB32S, 19, 18, 17, 16) ; / / St ar t an i nst ance of t he UTFT cl ass

UTFT(Model, SDA, SCL, CS, RST[, RS]);
The main class constructor when using serial display modules.

Parameters: Model : See t he separ at e document f or t he suppor t ed di spl ay modul es
SDA: Pi n f or Ser i al Dat a
SCL: Pi n f or Ser i al Cl ock
CS: Pi n f or Chi p Sel ect
RST: Pi n f or Reset
RS: <optional> Onl y used f or 5pi n ser i al modul es
Pi n f or Regi st er Sel ect

Usage: UTFT myGLCD( I TDB18SP, 11, 10, 9, 12, 8) ; / / St ar t an i nst ance of t he UTFT cl ass

InitLCD([orientation]);
Initialize the LCD and set display orientation.

Parameters: Or i ent at i on: <optional>
PORTRAI T
LANDSCAPE (default)
Usage: myGLCD. i ni t LCD( ) ; / / I ni t i al i ze t he di spl ay
Notes: Thi s wi l l r eset col or t o whi t e wi t h bl ack backgr ound. Sel ect ed f ont wi l l be r eset t o none.

getDisplayXSize();
Get the width of the screen in the current orientation.

Parameters: None
Returns: Wi dt h of t he scr een i n t he cur r ent or i ent at i on i n pi xel s
Usage: Xsi ze = myGLCD. get Di spl ayXSi ze( ) ; / / Get t he wi dt h

getDisplayYSize();
Get the height of the screen in the current orientation.

Parameters: None
Returns: Hei ght of t he scr een i n t he cur r ent or i ent at i on i n pi xel s
Usage: Ysi ze = myGLCD. get Di spl ayYSi ze( ) ; / / Get t he hei ght


UTFT l i br ar y Page 4
lcdOff();
Turn off the LCD. No commands will be executed until a lcdOn(); is sent.

Parameters: None
Usage: myGLCD. l cdOf f ( ) ; / / Tur n of f t he l cd
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833 and CPLD- based di spl ays.
CPLD- based di spl ays wi l l onl y t ur n of f t he backl i ght . I t wi l l accept f ur t her commands/ wr i t es.

lcdOn();
Turn on the LCD after issuing a lcdOff()-command.

Parameters: None
Usage: myGLCD. l cdOn( ) ; / / Tur n on t he l cd
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833 and CPLD- based di spl ays.
CPLD- based di spl ays wi l l onl y t ur n on t he backl i ght .

setContrast(c);
Set the contrast of the display.

Parameters: c: Cont r ast - l evel ( 0- 64)
Usage: myGLCD. set Cont r ast ( 64) ; / / Set cont r ast t o f ul l ( def aul t )
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833- based di spl ays

setBrightness(br);
Set the brightness of the display backlight.

Parameters: br : Br i ght ness- l evel ( 0- 16)
Usage: myGLCD. set Br i ght ness( 16) ; / / Set br i ght ness t o maxi mum( def aul t )
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays

setDisplayPage(pg);
Set which memory page to display.

Parameters: pg: Page ( 0- 7) ( 0 i s def aul t )
Usage: myGLCD. set Di spl ayPage( 4) ; / / Di spl ay page 4
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays

setWritePage(pg);
Set which memory page to use for subsequent display writes.

Parameters: pg: Page ( 0- 7) ( 0 i s def aul t )
Usage: myGLCD. set Wr i t ePage( 2) ; / / Use page 2 f or subsequent wr i t es
Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays


UTFT l i br ar y Page 5
clrScr();
Clear the screen. The background-color will be set to black.

Parameters: None
Usage: myGLCD. cl r Scr ( ) ; / / Cl ear t he scr een

fillScr(r, g, b);
Fill the screen with a specified color.

Parameters: r : Red component of an RGB val ue ( 0- 255)
g: Gr een component of an RGB val ue ( 0- 255)
b: Bl ue component of an RGB val ue ( 0- 255)
Usage: myGLCD. f i l l Scr ( 255, 127, 0) ; / / Fi l l t he scr een wi t h or ange

fillScr(color);
Fill the screen with a specified pre-calculated RGB565 color.

Parameters: col or : RGB565 col or val ue
Usage: myGLCD. f i l l Scr ( VGA_RED) ; / / Fi l l t he scr een wi t h r ed

setColor(r, g, b);
Set the color to use for all draw*, fill* and print commands.

Parameters: r : Red component of an RGB val ue ( 0- 255)
g: Gr een component of an RGB val ue ( 0- 255)
b: Bl ue component of an RGB val ue ( 0- 255)
Usage: myGLCD. set Col or ( 0, 255, 255) ; / / Set t he col or t o cyan

setColor(color);
Set the specified pre-calculated RGB565 color to use for all draw*, fill* and print commands.

Parameters: col or : RGB565 col or val ue
Usage: myGLCD. set Col or ( VGA_AQUA) ; / / Set t he col or t o aqua

getColor();
Get the currently selected color.

Parameters: None
Returns: Cur r ent l y sel ect ed col or as a RGB565 val ue ( wor d)
Usage: Col or = myGLCD. get Col or ( ) ; / / Get t he cur r ent col or

setBackColor(r, g, b);
Set the background color to use for all print commands.

Parameters: r : Red component of an RGB val ue ( 0- 255)
g: Gr een component of an RGB val ue ( 0- 255)
b: Bl ue component of an RGB val ue ( 0- 255)
Usage: myGLCD. set BackCol or ( 255, 255, 255) ; / / Set t he backgr ound col or t o whi t e

setBackColor(color);
Set the specified pre-calculated RGB565 background color to use for all print commands.

Parameters: col or : RGB565 col or val ue
Usage: myGLCD. set BackCol or ( VGA_LI ME) ; / / Set t he backgr ound col or t o l i me

getBackColor();
Get the currently selected background color.

Parameters: None
Returns: Cur r ent l y sel ect ed backgr ound col or as a RGB565 val ue ( wor d)
Usage: BackCol or = myGLCD. get BackCol or ( ) ; / / Get t he cur r ent backgr ound col or



UTFT l i br ar y Page 6
drawPixel(x, y);
Draw a single pixel.

Parameters: x: x- coor di nat e of t he pi xel
y: y- coor di nat e of t he pi xel
Usage: myGLCD. dr awPi xel ( 119, 159) ; / / Dr aw a si ngl e pi xel

drawLine(x1, y1, x2, y2);
Draw a line between two points.

Parameters: x1: x- coor di nat e of t he st ar t - poi nt
y1: y- coor di nat e of t he st ar t - poi nt
x2: x- coor di nat e of t he end- poi nt
y2: y- coor di nat e of t he end- poi nt
Usage: myGLCD. dr awLi ne( 0, 0, 239, 319) ; / / Dr aw a di agonal l i ne

drawRect(x1, y1, x2, y2);
Draw a rectangle between two points.

Parameters: x1: x- coor di nat e of t he st ar t - cor ner
y1: y- coor di nat e of t he st ar t - cor ner
x2: x- coor di nat e of t he end- cor ner
y2: y- coor di nat e of t he end- cor ner
Usage: myGLCD. dr awRect ( 119, 159, 239, 319) ; / / Dr aw a r ect angl e

drawRoundRect(x1, y1, x2, y2);
Draw a rectangle with slightly rounded corners between two points. The minimum size is 5 pixels in both directions. If a
smaller size is requested the rectangle will not be drawn.

Parameters: x1: x- coor di nat e of t he st ar t - cor ner
y1: y- coor di nat e of t he st ar t - cor ner
x2: x- coor di nat e of t he end- cor ner
y2: y- coor di nat e of t he end- cor ner
Usage: myGLCD. dr awRoundRect ( 0, 0, 119, 159) ; / / Dr aw a r ounded r ect angl e

fillRect(x1, y1, x2, y2);
Draw a filled rectangle between two points.

Parameters: x1: x- coor di nat e of t he st ar t - cor ner
y1: y- coor di nat e of t he st ar t - cor ner
x2: x- coor di nat e of t he end- cor ner
y2: y- coor di nat e of t he end- cor ner
Usage: myGLCD. f i l l Rect ( 119, 0, 239, 159) ; / / Dr aw a f i l l ed r ect angl e

fillRoundRect(x1, y1, x2, y2);
Draw a filled rectangle with slightly rounded corners between two points. The minimum size is 5 pixels in both directions. If a
smaller size is requested the rectangle will not be drawn.

Parameters: x1: x- coor di nat e of t he st ar t - cor ner
y1: y- coor di nat e of t he st ar t - cor ner
x2: x- coor di nat e of t he end- cor ner
y2: y- coor di nat e of t he end- cor ner
Usage: myGLCD. f i l l RoundRect ( 0, 159, 119, 319) ; / / Dr aw a f i l l ed, r ounded r ect angl e

drawCircle(x, y, radius);
Draw a circle with a specified radius.

Parameters: x: x- coor di nat e of t he cent er of t he ci r cl e
y: y- coor di nat e of t he cent er of t he ci r cl e
r adi us: r adi us of t he ci r cl e i n pi xel s
Usage: myGLCD. dr awCi r cl e( 119, 159, 20) ; / / Dr aw a ci r cl e wi t h a r adi us of 20 pi xel s

fillCircle(x, y, radius);
Draw a filled circle with a specified radius.

Parameters: x: x- coor di nat e of t he cent er of t he ci r cl e
y: y- coor di nat e of t he cent er of t he ci r cl e
r adi us: r adi us of t he ci r cl e i n pi xel s
Usage: myGLCD. f i l l Ci r cl e( 119, 159, 10) ; / / Dr aw a f i l l ed ci r cl e wi t h a r adi us of 10 pi xel s



UTFT l i br ar y Page 7
print(st, x, y[, deg]);
Print a string at the specified coordinates.
You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen.

Parameters: st : t he st r i ng t o pr i nt
x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st char act er
y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st char act er
deg: <optional>
Degr ees t o r ot at e t ext ( 0- 359) . Text wi l l be r ot at ed ar ound t he upper l ef t cor ner .
Usage: myGLCD. pr i nt ( Hel l o, Wor l d! , CENTER, 0) ; / / Pr i nt Hel l o, Wor l d!
Notes: CENTER and RI GHT wi l l not cal cul at e t he coor di nat es cor r ect l y when r ot at i ng t ext .
The st r i ng can be ei t her a char ar r ay or a St r i ng obj ect

printNumI(num, x, y[, length[, filler]]);
Print an integer number at the specified coordinates.
You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen.

Parameters: num: t he val ue t o pr i nt ( - 2, 147, 483, 648 t o 2, 147, 483, 647) INTEGERS ONLY
x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn
y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn
l engt h: <optional>
mi ni mumnumber of di gi t s/ char act er s ( i ncl udi ng si gn) t o di spl ay
f i l l er : <optional>
f i l l er char act er t o use t o get t he mi ni muml engt h. The char act er wi l l be i nser t ed i n f r ont
of t he number , but af t er t he si gn. Def aul t i s ' ' ( space) .
Usage: myGLCD. pr i nt NumI ( num, CENTER, 0) ; / / Pr i nt t he val ue of num

printNumF(num, dec, x, y[, divider[, length[, filler]]]);
Print a floating-point number at the specified coordinates.
You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen.
WARNING: Floating point numbers are not exact, and may yield strange results when compared. Use at your own discretion.

Parameters: num: t he val ue t o pr i nt ( See note)
dec: di gi t s i n t he f r act i onal par t ( 1- 5) 0 is not supported. Use printNumI() instead.
x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn
y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn
di vi der : <Optional>
Si ngl e char act er t o use as deci mal poi nt . Def aul t i s ' . '
l engt h: <optional>
mi ni mumnumber of di gi t s/ char act er s ( i ncl udi ng si gn) t o di spl ay
f i l l er : <optional>
f i l l er char act er t o use t o get t he mi ni muml engt h. The char act er wi l l be i nser t ed i n f r ont
of t he number , but af t er t he si gn. Def aul t i s ' ' ( space) .
Usage: myGLCD. pr i nt NumF( num, 3, CENTER, 0) ; / / Pr i nt t he val ue of num wi t h 3 f r act i onal di gi t s
Notes: Suppor t ed r ange depends on t he number of f r act i onal di gi t s used.
Appr ox r ange i s +/ - 2*( 10^( 9- dec) )

setFont(fontname);
Select font to use with print(), printNumI() and printNumF().

Parameters: f ont name: Name of t he ar r ay cont ai ni ng t he f ont you wi sh t o use
Usage: myGLCD. set Font ( Bi gFont ) ; / / Sel ect t he f ont cal l ed Bi gFont
Notes: You must decl ar e t he f ont - ar r ay as an ext er nal or i ncl ude i t i n your sket ch.

getFont();
Get the currently selected font.

Parameters: None
Returns: Cur r ent l y sel ect ed f ont
Usage: Cur r ent Font = myGLCD. get Font ( ) ; / / Get t he cur r ent f ont

getFontXsize();
Get the width of the currently selected font.

Parameters: None
Returns: Wi dt h of t he cur r ent l y sel ect ed f ont i n pi xel s
Usage: Xsi ze = myGLCD. get Font Xsi ze ( ) ; / / Get f ont wi dt h

getFontYsize();
Get the height of the currently selected font.

Parameters: None
Returns: Hei ght of t he cur r ent l y sel ect ed f ont i n pi xel s
Usage: Ysi ze = myGLCD. get Font Ysi ze ( ) ; / / Get f ont hei ght



UTFT l i br ar y Page 8
drawBitmap (x, y, sx, sy, data[, scale]);
Draw a bitmap on the screen.

Parameters: x: x- coor di nat e of t he upper , l ef t cor ner of t he bi t map
y: y- coor di nat e of t he upper , l ef t cor ner of t he bi t map
sx: wi dt h of t he bi t map i n pi xel s
sy: hei ght of t he bi t map i n pi xel s
dat a: ar r ay cont ai ni ng t he bi t map- dat a
scal e: <optional>
Scal i ng f act or . Each pi xel i n t he bi t map wi l l be dr awn as <scal e>x<scal e> pi xel s on scr een.
Usage: myGLCD. dr awBi t map( 0, 0, 32, 32, bi t map) ; / / Dr aw a 32x32 pi xel bi t map
Notes: You can use t he onl i ne- t ool ImageConverter 565 or ImageConverter565.exe i n t he Tool s- f ol der t o
conver t pi ct ur es i nt o compat i bl e ar r ays. The onl i ne- t ool can be f ound on my websi t e.
Requi r es t hat you #include <avr/pgmspace.h> when usi ng an Ar dui no ot her t han Ar dui no Due.

drawBitmap (x, y, sx, sy, data, deg, rox, roy);
Draw a bitmap on the screen with rotation.

Parameters: x: x- coor di nat e of t he upper , l ef t cor ner of t he bi t map
y: y- coor di nat e of t he upper , l ef t cor ner of t he bi t map
sx: wi dt h of t he bi t map i n pi xel s
sy: hei ght of t he bi t map i n pi xel s
dat a: ar r ay cont ai ni ng t he bi t map- dat a
deg: Degr ees t o r ot at e bi t map ( 0- 359)
r ox: x- coor di nat e of t he pi xel t o use as r ot at i onal cent er r el at i ve t o bi t maps upper l ef t cor ner
r oy: y- coor di nat e of t he pi xel t o use as r ot at i onal cent er r el at i ve t o bi t maps upper l ef t cor ner
Usage: myGLCD. dr awBi t map( 50, 50, 32, 32, bi t map, 45, 16, 16) ; / / Dr aw a bi t map r ot at ed 45 degr ees ar ound
i t s cent er
Notes: You can use t he onl i ne- t ool ImageConverter 565 or ImageConverter565.exe i n t he Tool s- f ol der t o
conver t pi ct ur es i nt o compat i bl e ar r ays. The onl i ne- t ool can be f ound on my websi t e.
Requi r es t hat you #include <avr/pgmspace.h> when usi ng an Ar dui no ot her t han Ar dui no Due.