08. How The Driver Works « Monochrome Graphic Display Source Code Driver Project

Monochrome Graphic Display Source Code Driver Project

Section 08. How The Driver Works

08. How The Driver Works

Contents:

Note – this section of the manual is for information should you wish to gain an understanding of how each of the driver components works.

Generic Driver and Screen Specific Files

The ‘display.c’ and ‘display.h’ files contain all of the driver generic functions and defines.

The ‘display-model.c’ and display-model.h’ files contain functions and defines that are particular to a specific screen and controller IC.

Delay Function

display_delay_ms(delay_ms)

Provides a simple means for the drive to delay while initialising the screen. Accuracy is not important as long as a value of 1 = a delay of at least 1mS (i.e. longer delays don’t matter).

Initialise The Screen

void display_initialise (void)

This function calls a screen specific function in the ‘display-model.c’ file. The function contains the screen initialisation sequence.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and ‘display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Set the Contrast

void display_set_contrast (BYTE contrast_value)

This function is only used for screens that have built in digital contrast adjustment. It calls a screen specific function in the ‘display-model.c’ file. The function contains the screen initialisation sequence.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Clear Screen

void display_clear_screen (BYTE invert_pixels)

This function writes 0×00 or 0xFF to every screen output byte location to clear it.

Usage examples:-

display_clear_screen(0); //Normal clear screen

display_clear_screen(1); //Set all screen pixels on

This is a universal function – modification is not normally required.

Display Bitmap

void display_bitmap (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord)

image_flash_address

Start address of bitmap in flash memory (set to 0 if bitmap is in program memory))

*p_image_memory_address

Pointer to bitmap in program memory (set to 0 if bitmap is in flash memory)

image_options

Bit 15:13 Unused

Bit 12 Font table image: 1 = Scroll text, 0 = static text

Bit 11:10 If either is high then do not output to the screen (used for centre and right aligned text)

Bit 9 Font table image: 1 = using proportionally spaced characters

Bit 8 Font table image: 0 = displayed along X axis, 1 = display along Y axis

Bit 7 1 = Invert pixels (i.e. a pixel on becomes off and vice versa)

Bit 6:0

0 = image is a normal bitmap.

>0 = Image is from a font table. The address given is the start of the font table. The value of bits 6:0 is the ASCII character required (0×01 – 0x7F)

x_start_coord

0 to DISPLAY_WIDTH_PIXELS. (If = 0xFFFF then the ‘ display_auto_x_coordinate’ variable is used for the bitmap x coordiante. This variable is updated with the next x coordinate each time this function is called to allow successive display across a screen).

ui_y_start_coord

0 to DISPLAY_HEIGHT_PIXELS. (If = 0xFFFF then the ‘display_auto_y_coordinate’ variable is used for the bitmap y coordiante. This variable is updated with the next y coordinate each time this function is called to allow successive display across a screen).

image_options standard defines:

DISPLAY_BITMAP_INVERT_PIXELS_OFF

DISPLAY_BITMAP_INVERT_PIXELS_ON

This is a large complex function that carries out all of the bitmap display functions. At a basic level it is simply reading bitmap data from memory and displaying each column in order. It is complex because it is dealing with all the problems having to read bitmaps in bytes of 8 pixels each and then write to the screen in bytes of 8 pixels but without there necessarily being any alignment between the two, and in as efficient a manor as possible. This function is also used to display each character of a string and when displaying text in proportional mode it deals with calculating how each character bitmap should be shifted and masked for any of the 4 possible screen orientations that may be used.

Usage example:-

display_bitmap(0, ec_logo_128x64, //Bitmap

DISPLAY_BITMAP_INVERT_PIXELS_ON, //Options

0, 0); //X, Y

This is a universal function – modification is not normally required.

Special Note

The X and Y start coordinates are screen based, not screen orientation based. Depending on how your particular screen is addressed and orientated in your application the X and Y values may relate to either actual real world axis and their values may run in either direction. An easy way of determining this for a new application is to display a bitmap or an ASCII text string in the centre of the screen and then alter the X and Y values to see how they affect the position of the bitmap or string.

Display String

Version for displaying constant strings:-

void display_const_string (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord, const rom BYTE *p_ascii_string)

Version for displaying variable strings:-

void display_variable_string (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord, BYTE *p_ascii_string)

image_flash_address

Start address of font table bitmap in flash memory (set to 0 if bitmap is in program memory))

*p_image_memory_address

Pointer to font table bitmap in program memory (set to 0 if bitmap is in flash memory)

image_options

Bits15:10 Unused

Bit9 0 = Monospace / fixed pitch characters, 1 = proportionally spaced characters

Bit8 0 = Display string along X axis, 1 = Display string along Y axis

Bit7 1 = Invert pixels (i.e. a pixel on becomes off and vice versa)

Bits6:0 Not available (used by display bitmap function)

x_start_coord

y_start_coord

0 to DISPLAY_HEIGHT_PIXELS. (If = 0xFFFF then the ‘ display_auto_y_coordinate’ variable is used for the bitmap y coordinate. This variable is updated with the next y coordiante each time this function is called to allow successive display across a screen).

*p_ascii_string

Pointer to the string to be displayed (must be null terminated)

image_options standard defines:

DISPLAY_STRING_INVERT_PIXELS_OFF

DISPLAY_STRING_INVERT_PIXELS_ON

DISPLAY_STRING_ON_X_AXIS

DISPLAY_STRING_ON_Y_AXIS

DISPLAY_STRING_MONOSPACE

DISPLAY_STRING_PROPORTIONAL

DISPLAY_STRING_LEFT_ALIGN

DISPLAY_STRING_CENTER_ALIGN

DISPLAY_STRING_CENTRE_ALIGN

DISPLAY_STRING_RIGHT_ALIGN

These functions are relatively straightforward and they simply read the string one character at a time calling the display_display_bitmap function to display each character and to display the space between each character. A bitmap is displayed for the space between each character so that any underlying display pixels are overwritten as a string is displayed and so that the number of pixels required between each character can be effectively set by the special gap character in each font table bitmap (character 0x7f).

Constant string usage example:-

const rom BYTE sample_const_string[] = {“Hello World”};

display_const_string(0, font_05x07, //Bitmap

(DISPLAY_STRING_ON_X_AXIS | DISPLAY_STRING_INVERT_PIXELS_OFF |

DISPLAY_STRING_MONOSPACE |

DISPLAY_STRING_LEFT_ALIGN), //Options

0, 0, //X, Y

sample_const_string); //String

Variable string usage example:-

BYTE sample_variable_string[15] = {“Hello World”};

display_variable_string (0, font_05x07, //Bitmap

(DISPLAY_STRING_ON_X_AXIS | DISPLAY_STRING_INVERT_PIXELS_OFF |

DISPLAY_STRING_MONOSPACE |

DISPLAY_STRING_LEFT_ALIGN), //Options

0, 0, //X, Y

sample_variable_string); //String

This is a universal function – modification is not normally required.

Special Note

Text Alignment

Left aligned text is the default way that strings are displayed. If you select centre or right aligned text the driver has automatically to calculate the required string start position as if the string was left aligned. It does this by simply displaying the string once, but with the data not actually being output to the screen, and then using the completed string end position to calculate the required left aligned string start position. The string is then displayed again, this time being outputted to the display. You don’t need to worry about the complexities of how the driver does this, but bear in mind that there is additional time required for this double processing of the string to take place. The double display approach is required because when centre or right aligning proportional text (which centre and right aligning is so useful for from a programmers point of view) each character has to be completely read and analysed to determine its width.

Byte Ordering Test Sequence

void display_byte_ordering_test_sequence (BYTE flags)

uc_flags

bit 0 set = reset to byte 0

bit 1 clear = move forwards 1 byte, set = move back 1 byte

This function may be used when configuring a new screen, to test how each sequential byte gets displayed on the screen. Call the function the first time with bit 0 set. The function will send a byte to the display at address 0×00, 0×00. Using push buttons or a timer, repeat calling the function with bit 0 and 1 clear and the function will write to the next byte, then the next, then the next…

The test byte sent is formatted as follows:-

7	6	5	4	3	2	1	0

This is a really useful way to discover how the screen is mapped and if there are bytes at the beginning of the address space that are unused (i.e. you have to call the function several times before you see the first byte). In this instance update the DISPLAY_WIDTH_START_OFFSET constant with the required offset to correct this.

This is a universal function – modification is not normally required.

Write Bitmap Byte

void display_write_bitmap_byte (BYTE bitmap_mask, BYTE bitmap_data, WORD x_byte_coord, WORD y_byte_coord);

bitmap_mask

bit high = use the bitmap_data value, bit low = use the existing screen value

bitmap_data

The data to write, controlled by the bitmap_mask bits

x_byte_coord

The X coordinate to write to

y_byte_coord

The Y coordinate to write to

This function first reads the current display value for the byte being addressed, then applies the bitmap data AND’d with the mask, before writing the byte back to the display.

Set Byte Address

void display_set_address (WORD x_coord, WORD y_coord_page)

This functions deals with the complexities of how a screen is mapped and sends the address to be accessed to the screen. Displays with non logical or reverse orientation addressing are corrected using this function.

Write Command

void display_write_command (BYTE data)

This function is usually that same as the instructions in the write part of display_write_bitmap_byte. The only difference may be setting the DC data / command line. However to allow for screens that aren’t so normal this separate write command function is used.