LCD Modules and Graphics

MMBasic 5.0 supports the use of graphic LCD panels.

There are eight basic drawing commands that you can use within MMBasic programs to interact with an attached LCD display.

All coordinates and measurements on the screen are done in terms of pixels with the X coordinate being the horizontal position and Y the vertical position. The top left corner of the screen has the coordinates X=0 and Y=0 and the values increase as you move down and to the right of the screen.

Read Only Variables

There are four read only variables which provide useful information about the display currently connected:

MM. HRES – Returns the width of the display (the X axis) in pixels.

MM. VRES – Returns the height of the display (the Y axis) in pixels.

MM.FONTHEIGHT – Returns the height of the current default font (in pixels). All characters in a font have the same height.

MM.FONTWIDTH – Returns the width of a character in the current default font (in pixels). All characters in a font have the same width.

LCD Colors

Color is specified as a true color 24 bit number where the top eight bits represent the intensity of the red color, the middle eight bits the green intensity and the bottom eight bits the blue. The easiest way to generate this number is with the RGB() function which has the form:

RGB(red, green, blue)

A value of zero for a color represents black and 255 represents full intensity. The RGB() function also supports a shortcut where you can specify common colors by naming them. For example, RGB(red) or RGB(cyan). The colors that can be named using the shortcut form are white, black, blue, green, cyan, red, magenta, yellow, brown and gray.

MMBasic will automatically translate all colors to the format required by the individual display controller which, in the case of the ILI9341 controller, is 65K colors in the 565 format.

The default for commands that require a color parameter can be set with the COLOR command. This handy if your program uses a consistent color scheme, you can then set the defaults and use the short version of the drawing commands throughout your program.

The COLOR command takes the format:

COLOR foreground-color, background-color

Fonts

MMBasic includes one built in font which is 8 pixels wide by 13 pixels height and includes all 95 standard ASCII characters. Within MMBasic this is referred to as font #1.

If required, additional fonts can be embedded in a BASIC program. The MMBasic firmware zip file includes over a dozen embedded fonts covering a wide range of character sets and includes symbol fonts (Dingbats) which are handy for creating on screen icons, etc. These fonts work exactly same as the built in fonts (ie, selected using the FONT command or specified in the TEXT command).

The format of an embedded font is:

DefineFont #Nbr
  hex [[ hex[…]
  hex [[ hex[…]
END DefineFont

It must start with the keyword “DefineFont” followed by the font number (which may be preceded by an optional # character). Any font number in the range of 1 to 16 can be specified. The body of the font is a sequence of 8-digit hex words with each word separated by one or more spaces or a new line. The font definition is terminated by an “End DefineFont ” keyword.

When a BASIC program is saved to program memory MMBasic will search through it looking for any embedded fonts and the font table will be updated to include them. During execution embedded fonts will be skipped over and this means that they can be placed anywhere in the program.

Embedded fonts can also be saved to the library area. When this is done the font is, for all intent and purposes, permanently added to the MMBasic language. In addition MMBasic will strip out the hex codes in the font definition (because they are no longer needed) and this will save a considerable amount of memory. See the LIBRARY command for details on how to use the library.

The default font used by MMBasic is font #1 however that can be changed with the FONT command:

FONT font-number, scaling

Where ‘font-number’ is a number which can be optionally preceded by a hash (#) character. ‘scaling’ is optional and is a number in the range of 1 to 15. The font will be multiplied by the scaling factor making the displayed character correspondingly wider and taller. For example, specifying ‘scaling’ of 2 will double the height and width. If not specified the scaling factor will be 1 (ie, no scaling).

Drawing Commands

Most drawing commands have optional parameters. You can completely leave these off the end of a command or you can use two commas in sequence to indicate a missing parameter. For example, the fifth parameter of the LINE command is optional so you can use this format:

LINE 0, 0, 100, 100, , rgb(red)

Optional parameters are indicated in this document by italics, for example: font.

In the following commands C is the drawing color and defaults to the current foreground color. FILL is the fill color which defaults to -1 which indicates that no fill is to be used.

The drawing commands are:

CLS C

Clears the screen to the color C. If C is not specified the current default background color will be used.

PIXEL X, Y, C

Illuminates a pixel. If C is not specified the current default foreground color will be used.

LINE X1, Y1, X2, Y2, LW, C

Draws a line starting at X1 and Y1 and ending at X2 and Y2. LW is the line’s width and is only valid for horizontal or vertical lines. It defaults to 1 if not specified or if the line is a diagonal.

BOX X1, Y1, W, H, LW, C, FILL

Draws a box starting at X1 and Y1 which is W pixels wide and H pixels high. LW is the width of the sides of the box and can be zero. It defaults to 1.

RBOX X1, Y1, W, H, R, C, FILL

Draws a box with rounded corners starting at X1 and Y1 which is W pixels wide and H pixels high. R is the radius of the corners of the box. It defaults to 10.

CIRCLE X, Y, R, LW, A, C, FILL

Draws a circle with X and Y as the centre and a radius R. LW is the width of the line used for the circumference and can be zero (defaults to 1). A is the aspect ratio which is a floating point number and defaults to 1. For example, an aspect of 0.5 will draw an oval where the width is half the height.

TEXT X, Y, STRING, JUSTIFICATION, FONT, SCALE, C, BC

Displays a string starting at X and Y. JUSTIFICATION is one or two letters where the first letter is the horizontal justification around X and can be L, C or R for LEFT, CENTER, RIGHT and the second letter is the vertical placement around Y and can be T, M or B for TOP, MIDDLE, BOTTOM. The default justification is left/top. FONT and SCALE are optional and default to that set by the FONT command. C is the drawing colour and BC is the background colour. They are optional and default to that set by the COLOR command.

GUI BITMAP X, Y, BITS, WIDTH, HEIGHT, SCALE, C, BC

Displays the bits in a bitmap starting at X and Y. HEIGHT and WIDTH are the dimensions of the bitmap as displayed on the LCD panel and default to 8×8. SCALE, C and BC are the same as for the TEXT command.

The bitmap can be an integer or a string variable or constant and is drawn using the first byte as the first bits of the top line (bit 7 first, then bit 6, etc) followed by the next byte, etc. When the top line has been filled the next line of the displayed bitmap will start with the next bit in the integer or string.

LCD Drawing Example

As an example the following program will draw a simple digital clock on an ILI9341 based LCD display mounted on a CGMICROBOARD. The program will terminate and return to the command prompt if the display screen is touched.

First the display and touch options must be configured by entering commands similar to these at the command prompt:

---

OPTION LCDPANEL ILI9341, L, 21, 22, 23
OPTION TOUCH 18, 14

---

Note that a reset must be performed after each OPTION command.

These specify an ILI9341 based display in the landscape orientation and uses pins 21, 22, and 23 for the LCD and pins 18 and 14 for the touch controller.

Next the touch feature should be calibrated by entering this command and following the calibration procedure.

GUI CALIBRATE

Finally you can enter and run the program:

The program starts by defining a constant with a value corresponding to a dark blue color and then sets the defaults for the colors and the font. It then draws a box with red walls and a dark blue interior.

Following this the program enters a continuous loop where it performs three functions:

1. Displays the current time inside the previously drawn box. The string is drawn centered both horizontally and vertically in the middle of the box. Note that the TEXT command overrides both the default font and colors to set its own parameters.

2. Draws the date centred in the lower half of the screen. In this case the TEXT command uses the default font and colors previously set.

3. Checks for a touch on the screen. This is indicated when the TOUCH(X) function returns something other than -1. In that case the program will terminate.