Programming the ezLCD+ with Lua

Screen Coordinates

For displaying both raster and vector graphics, the ezLCD+ uses the X-Y Cartesian coordinate system. The origin is located in the upper-left corner of the display. The X values increase to the right, while Y increase to the bottom of the display.
The ezLCD+ uses 16-bit numbers to specify X and Y coordinates. Negative numbers are represented using two’s complement system. For example:
2 dec = 0000 0000 0000 0010 bin
1 dec = 0000 0000 0000 0001 bin
0 dec = 0000 0000 0000 0000 bin
-1 dec = 1111 1111 1111 1111 bin
-2 dec = 1111 1111 1111 1110 bin
etc.
This means that the numbers range
From: -32768 dec = 1000 0000 0000 0000 bin
To: 32767 dec = 0111 1111 1111 1111 bin
The above system is used to represent 16-bit signed integers by most of the CPUs and programming languages.
The ezLCD+ drawing position (Current Position) may be set outside the screen range. The portions of the image, which do not fit on the screen are just clipped-out. For example: if a circle is drawn with radius 100 and the center at x = -20, y = -30, the following figure will appear at the upper-left corner of the screen:
The Current Position is updated by some drawing commands. For example: if you set the Current Position to (10, 20) and then draw the line to (200, 100), the Current Position will change to (200, 100).

Vector Graphics

Vector Graphics is the use of geometrical primitives such as points, lines, curves, and polygons, which are all based upon mathematical equations to represent images in computer graphics. It is used in contrast to the term Raster Graphics, which is the representation of images as a collection of pixels.
The ezLCD supports drawing of various geometrical shapes, like lines, polygons, ellipses, arcs, etc.
The rendering of Vector Graphics is affected by the following Drawing Parameters:
• Current Position
• Current Color
• Transparency
• Pen
• Current Drawing Frame
Note: Since the ezLCD is physically a raster display, all Vector Graphics is converted to the Raster Graphics during rendering.

Raster Graphics (Bitmaps)

A Raster Graphics image, digital image, or bitmap, is the representation of images as a collection of pixels, or points of color. It is used in contrast to the term Vector Graphics which is the use of geometrical primitives such as points, lines, curves, and polygons, all based upon mathematical equations to represent images.
Raster images are commonly stored in image files with varying formats.The ezLCD can display the following formats of raster images:
• 24-bit .bmp
• .jpg
• .ezp (16-bit color format used in other ezLCD products, added here for compatibility).
A bitmap corresponds bit-for-bit with an image displayed on a screen, in the same format used for storage in the display’s video memory. Bitmap is technically characterized by the width and height of the image in pixels and by the number of bits per pixel (a color depth, which determines the number of colors it can represent).
The bitmaps (raster images), can be displayed from the User ROM or SD card using the Bitmap functions.
Additionally, ezLCD supports direct pixel drawing on the display using the Plot Functions
The rendering of Raster Graphics is affected by the following Drawing Parameters:
• Current Position
• Current Drawing Frame
• Transparency
• Transparent Color (direct pixel drawing is not affected)

Drawing Parameters

General

Graphics are drawn according to the following parameters:
Current Drawing Frame
• Set by Frame Management Functions
Current Position.
• Set by the SET Position Functions
• Updated by drawing commands
Current Color.
• Set by SetColor
• Bitmaps are not affected
Background Color.
• Set by SetBgColor
• Only Bitmap Fonts are affected
Transparent Color.
• Set by SetTrColor and TrColorNone
• Specifies the color, which is ignored during Bitmap drawing
• Only Bitmaps are affected (direct pixel drawing is not affected).
Transparency
• Set by SetAlpha
Pen
• Set by SetPenSize
• Only the Vector Graphics is affected
• Pen Height affects only the drawing of curves (ellipse, circle, arc, etc)

Transparency

The ezLCD+ supports transparency by alpha-blending of the pixel being drawn with the background pixel at the particular position. Alpha blending is a technique for combinating of two colors allowing for transparency effects in computer graphics. The alpha is a level of opaqueness of the pixel. The value of alpha ranges from 0 to 255, where 0 represents a fully transparent color, and 255 represents a fully opaque color. The drawing below shows a picture of electronic circuit drawn over another image using different values of alpha.
All of the vector graphics, bitmaps and fonts are drawn according to the alpha set by SetAlpha.
Upon power-up, alpha is set to 255 (fully opaque).
Drawing Performance Impact
Rendering is almost 3 time slower when alpha is set to any value other than 255 or 0.

Pen

Vector Graphics are drawn using the Pen. Calling SetPenSize allows setting of the pen height and width.
Pen Width specifies the horizontal dimension the drawing line (in pixels).
Pen Height specifies the vertical dimension of Pen (in pixels), when drawing curves. Note that the pen height is ignored when drawing straight lines.
Notes:
1. Straight lines are not drawn when Pen Width is set to 0.
2. Curves are not drawn when either Pen Width or Height is set to 0.
The drawings below show a line drawn with different Pen Sizes
Pen Size = 1 Pen Size = 4 Pen Size = 20
The drawings below show an ellipse drawn with different Pen Widths and Heights
Pen Width = 1 Pen Width = 1
Pen Height = 1 Pen Height = 40
Pen Width = 40
Pen Height = 4

Fonts

The ezLCD+ is capable of rendering 2 types of fonts:
1. Bitmap Fonts.
2. True Type Fonts (Free Type Fonts)
The above font types have some advantages over one another. The table below describes some of them.
While the ezLCD+ True Type fonts have a lot advantages, their rendering is much slower with the comparison to the speed in which the Bitmap Fonts are rendered. Also, the rendering quality is usually poor for the True Type Fonts with the height smaller than 16 pixels.
Note: Throughout this manual the term « True Type Fonts » is used interchangeably with « Free Type Fonts », « Open Type Fonts » and « Scalable Fonts ». They all mean the same.
The drawing below shows rendered Bitmap Font (left) and True Type Font (right).
The drawing below shows the same drawing as above, however magnified 8 times.

Bitmap Fonts

The ezLCD+ bitmap fonts reside in the User ROM, which is described in the « ezLCD+10x Manual ». They are created using ezLCDrom or ezLCDconfig utility and saved as .ezf files.
Note: Both ezLCDrom and ezLCDconfig utilities have been written for the other ezLCD+ products, however the .ezf files generated by them are compatible with the ezLCD+. They can be downloaded from the support section of the http://www.ezlcd.com. In the nearest future, a special bitmap font utility will be developed for ezLCD+.
Bitmap font files (.ezf) can be copied from the SD card to the User ROM by the ezLCD+ Executable:
User.eze. The whole procedure is described in the « ezLCD+10x Manual ».
The rendering of Bitmap Fonts is affected by the following Drawing Parameters:
• Current Position.
• Current Color.
• Background Color.
• Transparency
The following bitmap fonts are installed in the ezLCD+, when it is shipped:

True Type Fonts

The ezLCD+ True Type Fonts can reside in the User ROM, which is described in the « ezLCD+10x Manual ». . Also, they can be dynamically loaded from the SD card. The True Type fonts are generally available as files with the extensions: .ttf and .otf.
The True Type Fonts can be copied from the SD card to the User ROM by the ezLCD+ Executable:
User.eze. The whole procedure is described in the « ezLCD+10x Manual ».
Acknowledgement: The True Type Fonts rendering software is based in part on the work of the FreeType Team (http://www.freetype.org). The ezLCD+ uses the FreeType 2 engine.
Note: Throughout this manual the term « True Type Fonts » is used interchangeably with « Free Type Fonts », « Open Type Fonts » and « Scalable Fonts ». They all mean the same.
Rendering of the True Type Fonts is much slower than in the case of Bitmap Fonts. There are significant differences in the speed in which the different True Type Fonts are rendered. Some of them are rendered quite fast, other: very slow. This means that the users should choose their fonts wisely. The ezLCD+ has a font cache mechanism, which significantly reduces rendering time of already used characters.
Quite often, the True Type Font contains a lot of regional characters, which may be of no use for the particular application. The font file size may be significantly reduced when such characters are removed from the .ttf file by using font editing software like, for example, FontCreator by High-Logic.
The rendering of True Type Fonts is affected by the following Drawing Parameters:
• Current Position
• Current Color
• Transparency

Quick Start
1 Quick .S…t.a..r.t.:.. .L..u..a
ezLCD+ Customization
Drawing on the ezLCD+
1 Print
2 Screen.. ..C..o..o…r.d..i.n..a..t..e..s
3 Vector. .G…r..a..p..h..i.c..s
4 Raster. .G…r.a..p..h…i.c..s.. (..B..i.t.m….a..p..s..).
5 Drawin..g.. ..P…a..r.a..m…e..t.e..r..s
General  Transparency.
Pen
6 Fonts
Bitmap Fonts
True Type Fon..t..s
Programming the ezLCD+ with Lua
1 Consta..n..t.s
2 Positio..n.. .F..u..n..c..t..i.o..n..s
SetXY(x, y)
SetX(x)
SetY(y)
GetX()
GetY()
3 Color F..u..n…c..t.i.o..n..s
RGB(red, gree.n…,. .b…l.u..e..).
GetRed(ezLCD..c..o…l.o..r.)
GetGreen(exL.C…D…c..o..l.o..r..).
GetBlue(ezLC.D..c..o…l.o..r.)
SetColor(ezLC..D…c..o..l.o…r.)
SetBgColor(ez..L..C…D…c..o..l.o..r..).
ReplaceColor(.x..,. .y..,. ..w…i.d..t.h…,. .h…e..i.g..h..t.,. ..O…l.d..C…o..l.o..r..,. .N…e..w…C…o
GetPixel()
GetPixel(x, y)
4 ezLCD+ Lua Application Programming Interface
4 Transp..a..r.e..n…c..y.. .F..u..n..c..t.i.o…n..s
SetAlpha(alph.a..).
TrColorNone()
SetTrColor(ez.L..C…D…c..o..l.o…r.)
5 Pen Si.z..e.. ..F..u..n..c..t.i.o…n..s
SetPenSize(he.i.g..h…t.,. …w…i.d…t.h..).
6 Angle .F..u..n…c..t.i.o..n..s
Deg(degrees).
Rad(radians)
7 Button.. F..u..n…c..t.i.o..n..s
Overview
Button(ID, iSta..t.e..,. .i.c..o..n…U..p…,. .i.c..o..n..D…o..w…n..,. ..i.c..o..n..D…i.s..a..b..l.e..d..,
Button(ID, iSta.t..e..,. .i.c..o..n..U…p..,. .i..c..o..n..D…o..w…n..,. .i.c..o..n…D..i.s..a..b…l.e..d..,
Button(iD, iSta..t.e..).
DelButtons()
SetButtonEve.n..t.(.s..B…u..t..t.o..n…H..a..n…d..l.e..r..).
8 Fill Are..a.. ..F..u..n..c..t..i.o..n..s
Overview
Cls()
Cls(ezLCDcolo…r.).
Fill()
Fill(ezLCDcolo..r.)
Fill(x, y)
Fill(x, y, FillCo.l.o..r.)
CircleFill(x, y, ..r.a..d..i.u…s..).
CircleFill(x, y, ..r.a..d..i.u…s..,. .c..o..l.o…r.).
Ellipse(a, b)
Ellipse(a, b, co..l.o..r..).
BoxFill(x2, y2.,. .c..o..l.o…r.).
BoxFill(x1, y1.,. .x..2..,. .y..2..).
Wait_ms(ms.).
SetTime(tim.e..).
19 Timer.. .M…a..n…a..g..e..m…e..n..t. ..F..u..n…c..t.i.o..n..s
Timer(msec, ..L..u…..e..N..o..,. .S..y..n..c..)
Poke16(a.d..d..r.e…s.s..,. .d..a..t.a..)
Poke8(ad.d..r.e..s..s..,. .d..a..t.a..)
ExitReq()
GLOSSARY