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

com ( C) 2012 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.

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.

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.

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.




Thi s l i br ar y i s f r ee sof t war e; you can r edi st r i but e i t and/ or modi f y i t under t he t er ms of t he GNU Lesser Gener al Publ i c
Li cense as publ i shed by t he Fr ee Sof t war e Foundat i on; ei t her ver si on 2. 1 of t he Li cense, or ( at your opt i on) any l at er
ver si on.

Thi s l i br ar y i s di st r i but ed i n t he hope t hat i t wi l l be usef ul , but WI THOUT ANY WARRANTY; wi t hout even t he i mpl i ed war r ant y
of MERCHANTABI LI TY or FI TNESS FOR A PARTI CULAR PURPOSE. See t he GNU Lesser Gener al Publ i c Li cense f or mor e det ai l s.

You shoul d have r ecei ved a copy of t he GNU Lesser Gener al Publ i c Li cense al ong wi t h t hi s l i br ar y; i f not , wr i t e t o t he Fr ee
Sof t war e Foundat i on, I nc. , 51 Fr ankl i n St , Fi f t h Fl oor , Bost on, MA 02110- 1301 USA


DISPLAY ORIENTATION:




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

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);
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

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. Font si ze wi l l be r eset t o FONT_SMALL.

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

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

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



UTFT l i br ar y Page 4
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 5
print(st, x, y[, deg]);
Print a string at the specified coordinates. An optional background color can be specified. Default background is black.
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. An optional background color can be specified. Default background is
black.
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 ( 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. An optional background color can be specified. Default background is
black.
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 ( 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.



UTFT l i br ar y Page 6
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.

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.

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- based di spl ays

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- based di spl ays

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

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