Understanding CFunctions, 3

Author: P. Mather

 

As promised here is the last of the CFunction tutorials. This time the objective is to write a loadable display driver. Many months ago, the first displays I looked at were the monochrome SSD1306 OLED displays and the Nokia 5110 LCD displays.

These have been somewhat superseded by the huge choice of colour TFT displays but they still offer an option where the requirement is a small but visible and cheap display technology that can be connected using SPI. This tutorial will develop a fully worked loadable driver for the SSD1306 OLED display.

The Micromite firmware from V4.7 provides hooks to allow loadable drivers to be written for displays in C that can then be accessed by the standard Basic drawing commands: TEXT, BOX, CIRCLE etc.

There are three routines that need to be written as part of a CFunction display driver:
First, there must be a “main” program that initialises the display and hooks the drawing routines into the Micromite firmware.
Second, there needs to be a drawing routine to draw a filled rectangular box on the display.
Finally, there needs to be a drawing routine to write a two colour bitmap to the display.
It is that simple

Everything else is created in the Micromite firmware using just the two drawing routines. So a single pixel is a rectangle with length and height both set to 1.
A horizontal or vertical line is a rectangle with one dimension set to 1 and the other set to the length of the line.
A diagonal line is a series of pixels.
A circle outline is also a series of pixels
A filled circle is a set of filled rectangles calculated to fill out the circular area of the screen.
A text character is a bitmap
etc.

The calling sequence for the two drawing routines is completely defined and must be followed by any loadable driver:

DrawRectangle(int x1, int y1, int x2, int y2, int c)

draws a rectangle where the top left hand corner is at x1,y1 and the bottom right hand corner is at x2,y2 using the colour provided in c.

DrawBitmap(int x, int y, int width, int height, int scale, int fc, int bc, unsigned char bitmap[]){

draws a rectangle where the top left hand corner is at x,y. It takes the information contained in the array “bitmap” which is “width” bits wide and “height” bits tall and where a 1 in the bitmap means use the colour fc and a 0 means use the colour bc. The main use is of course for text. The scale parameter says for each bit in the bitmap create an area on the display scale * scale in the specified colour.

Note that the display driver is the only bit of code that needs to understand the workings of the particular display. The Micromite firmware just needs to know that it can call DrawRectangle and/or DrawBitmap and magically things will appear on the display. We will provide the Micromite firmware with information about the orientation of the display and its height and width so that it can integrate touch capability but other than that the driver is the only code that manages the display and the hardware interface to it.

So given the above we can look at how to implement a driver for the SSD1306.

Colour displays use multiple bits of information to describe the colour of each pixel. However, in general monochrome displays use one bit per pixel and so typically a transfer of one byte of information to the display will update 8 pixels. This means if I want to change a single pixel I need to know the current value of the 7 other pixels which are linked in the same byte of input. I could do this by reading the display memory but in many cases of SPI displays they do not provide read capability so this is impossible. This means I need to keep a memory map of the current state of the display in my microprocessor memory.

In the case of the SSD1306 display it is 128 pixels wide and 64 pixels high so I need to maintain a memory map of 1024 bytes (128*64/8) to track the current state of the display.

The SSD1306 (in common with many monochrome display drivers) organises the display as 128*8 bytes so byte zero relates to pixels 0,0 0,1 0,2 0,3 0,4 0,5 0,6 0,7 i.e. a line 8-pixels long running down the screen starting at the top left hand corner (0,0).

It supports a mechanism for positioning the writing point (0-127,0-7) to define which set of 8 pixels will be updated.

To get the SSD1306 to display anything at all it needs some configuration data written to it. All display controllers need initialisation and they are all different. Google and the controller datasheet are your friend in sorting out the requirements for a specific controller. In the case of the SSD1306 it is quite straightforward particularly compared to some of the colour display controllers.

So to summarise this introduction:
We need to write three routines for the SSD1306: initialisation, drawrectangle, drawbitmap.
We need to handle the hardware mechanics of talking to the display (SPI)
We need to create and maintain some persistent memory to use as a memory map of the display.

Lets get started on the driver. First we need to set up some information at the top of the CFunction that will be used by the code:

---

/*******************************************************************************
 *
 * Driver for SSD1306 Display written as CFunctions
 *
 * Author: Peter Mather 2015 with acknowledgements to Peter Carnegie & Geoff Graham
 * 
 *
 * This CFunction MUST be compiled with Optimization Level 1, -O1
 * -O2,-O3,-Os will compile successfully, but generate exceptions at runtime.
 *
 * When Generating the CFunction, use MERGE CFunction mode, and name the CFunction
 * SSD1306
 *
 * Entry point is function long long main(long long *MyAddress,
 *                                        long long *DC,
 *                                        long long *RST
 *                                        long long *CS
 *                                        long long *size //zero for 0.96", non-zero for 1.3"
 *                                        long long *orientation)
 *
 * V1.0     2015-10-15 Peter Mather
 * 
 ******************************************************************************/

#define Version 100     //Version 1.00
#define _SUPPRESS_PLIB_WARNING                                      // required for XC1.33  Later compiler versions will need PLIB to be installed
#include <plib.h>                                                   // the pre Harmony peripheral libraries
#include "../cfunctions.h"

#define LANDSCAPE       1
#define PORTRAIT        2
#define RLANDSCAPE      3
#define RPORTRAIT       4

#define screenwidth 128
#define screenheight 64
#define screenrows screenheight/8
#define update screenwidth*screenrows //location for status to force screen write
#define displaysize update+1 //location for screen size 

// SPI pin numbers and registers
#define SPI_INP_PIN         (HAS_44PINS ? 41 : 14)
#define SPI_OUT_PIN         (HAS_44PINS ? 20 :  3)
#define SPI_CLK_PIN         (HAS_44PINS ? 14 : 25)
#define SPI_PPS_OPEN        PPSInput(2, SDI1, RPB5); PPSOutput(2, RPA1, SDO1)
#define SPI_PPS_CLOSE       PPSOutput(2, RPA1, NULL)
#define SPICON *(volatile unsigned int *)(0xbf805800)               //SPI config 1 register
#define SPISTAT *(volatile unsigned int *)(0xbf805810)              //SPI status register
#define SPIBUF *(volatile unsigned int *)(0xbf805820)               //SPI I/O buffer
#define SPIBRG *(volatile unsigned int *)(0xbf805830)               //SPI clock register
#define SPICON2 *(volatile unsigned int *)(0xbf805840)              //SPI config 2 register

#define SPIsend(a) {int j;SPIBUF=a; while((SPISTAT & 0x80)==0); j=SPIBUF;}

---

 

 

We tell the compiler that we want access to Microchips peripheral library “plib” and that we also want to access the Micromite internal routines as defined in “cfunctions.h”.
Then we set up some “defines”. These are simply string substitutions that can be used to make the code more readable. So when I use the value “screenwidth” the compiler will automatically substitute 128.

This version of the CFunction will only run on the MX170 but we need to know if it is running on a 44-pin chip or 28-pin one. This is needed because the pin numbers of the SPI pins are different on each.
HAS_44PINS is defined in cfunctions.h and reads the chips ID code to work out which chip is in use. This allows us to set SPI_INP_PIN etc. to the correct pin number for the part.
We then define the SPI registers that will be used by the code:
“define SPIBUF *(volatile unsigned int *)(0xbf805820)”
This says that when we use SPIBUF in our code we will actually be talking directly to memory location &HBF805820 which is the location in the PIC’s memory map of the I/O buffer for SPI read/write. The “volatile” syntax is used to tell the compiler that the value may change without being changed in the code itself and therefore optimisations must be done without any assumptions of the value.

Finally we define the macro SPIsend. Again the string is just substituted by the compiler but in this case it is a block of code that writes to the SPI I/O register, waits for the write to complete, and then reads the buffer to clear it. This is our main way of outputting to the display.

Having set up these definitions we can start to look at the main program.

---

 

//CFunction Driver_SSD1306
long long main(long long *MyAddress, long long *CD, long long *RST, long long *CS,long long *size, long long *orientation){
    int  i,DrawRectangleVectorOffset,DrawBitmapVectorOffset,updatedisplayVectorOffset,HorizontalRes=screenwidth,VerticalRes=scree nheight;
    unsigned int consave=0,brgsave=0,con2save;

    Option->LCD_Reset=*RST;
    Option->LCD_CD=*CD;
    Option->LCD_CS=*CS;
    Option->DISPLAY_ORIENTATION=*orientation;

    //Get some persistent memory
    unsigned char * p = GetMemory(screenwidth*screenrows+256);
    //Save the address for other CFunctions
    StartOfCFuncRam=(unsigned int)(p);
    p[displaysize]=*size;

    ExtCfg(Option->LCD_Reset,EXT_DIG_OUT,0);ExtCfg(Option->LCD_Reset,EXT_BOOT_RESERVED,0);
    PinSetBit(Option->LCD_Reset, LATSET);
    ExtCfg(Option->LCD_CD,EXT_DIG_OUT,0);ExtCfg(Option->LCD_CD,EXT_BOOT_RESERVED,0);
    PinSetBit(Option->LCD_CD, LATSET);
    ExtCfg(Option->LCD_CS,EXT_DIG_OUT,0);ExtCfg(Option->LCD_CS,EXT_BOOT_RESERVED,0);
    PinSetBit(Option->LCD_CS, LATSET);
    if(ExtCurrentConfig[SPI_OUT_PIN] == EXT_RESERVED) { //already open
        brgsave=SPIBRG;
        consave=SPICON;
        con2save=SPICON2;
    }
    ExtCfg(SPI_OUT_PIN, EXT_DIG_OUT, 0); ExtCfg(SPI_OUT_PIN, EXT_BOOT_RESERVED, 0);
    ExtCfg(SPI_INP_PIN, EXT_DIG_IN, 0); ExtCfg(SPI_INP_PIN, EXT_BOOT_RESERVED, 0);
    ExtCfg(SPI_CLK_PIN, EXT_DIG_OUT, 0); ExtCfg(SPI_CLK_PIN, EXT_BOOT_RESERVED, 0);
    SPI_PPS_OPEN; 
    SPICON=0x8060;
    SPIBRG=2;
    SPICON2=0xC00;// this is defined in IOPorts.h
    if(!brgsave){ //save my settings
        brgsave=SPIBRG;
        consave=SPICON;
        con2save=SPICON2;
    }    

---

The function call “main” follows the pattern from all the other examples we have looked at. It takes in an address which is used to define its own position in memory in a specific use, the pin numbers of the three control pins on the SSD1306: command/data, reset, chip select, a size code for the display which is used to correct for the different wiring of the 0.96″ and 1.3″ variants, and the orientation of the display: landscape, portrait, reverse landscape, reverse portrait.

We then define some variables we will use in the “main” routine.

Next we store the main parameters in special locations Geoff has provided specifically for display use .e.g. “Option->LCD_Reset=*RST;”
The Option structure is defined in cfunctions.h

We then allocate some memory we can use for the display’s memory map using GetMemory.
This is permanently allocated so will still be there after the “main” function terminates. We save the address of the memory in “StartOfCFuncRam” so it can be accessed by the actual drawing routines. We defined the pointer to the memory as a pointer to a character array so we can access the memory as a simple array of characters.
“p[displaysize]=*size;” saves the size code of our display in this array after the memory map.

Next we set up the I/O pins in the same way we saw in the previous tutorials however in this case we additionally give them a status of EXT_BOOT_RESERVED. This protects them from being de-allocated by a “NEW” command or an “EDIT” allowing the graphics to be used at all times including from the command line. The function “main” will be called from Basic by MM.STARTUP so that the display is always initialised after a reset or power-up.

It is possible that a user program is also using the SPI port. We can check this by looking for the status “EXT_RESERVED” on one of the I/O pins.
“if(ExtCurrentConfig[SPI_OUT_PIN] == EXT_RESERVED)”
If this is case we then save the user configuration so that it can be restored before we exit.
We can then set up the SPI port in the configuration we need for the SSD1306 and if the port wasn’t in use store our own settings: “brgsave=SPIBRG;”

---

//Calculate the address vectors
    if ((unsigned int)&DrawRectangleMEM < (unsigned int)&main){
        DrawRectangleVectorOffset=*MyAddress - ((unsigned int)&main - (unsigned int)&DrawRectangleMEM);
    }else{
        DrawRectangleVectorOffset=*MyAddress + ((unsigned int)&DrawRectangleMEM - (unsigned int)&main);
    }
    
    if ((unsigned int)&DrawBitmapMEM < (unsigned int)&main){
        DrawBitmapVectorOffset=*MyAddress - ((unsigned int)&main - (unsigned int)&DrawBitmapMEM);
    }else{
        DrawBitmapVectorOffset=*MyAddress + ((unsigned int)&DrawBitmapMEM - (unsigned int)&main);
    }
    if ((unsigned int)&updatedisplay < (unsigned int)&main){
        updatedisplayVectorOffset=*MyAddress - ((unsigned int)&main - (unsigned int)&updatedisplay);
    }else{
        updatedisplayVectorOffset=*MyAddress + ((unsigned int)&updatedisplay - (unsigned int)&main);
    }

---

 

The next part of the code is exactly the same as we saw in tutorial 2. We calculate the location in memory of the routines that will be called by the Micromite firmware.

We have talked about “drawrectangle” and “drawbitmap” above. “updatedisplay” uses another feature of the Micromite firmware. This is a routine which will be called at the end of every Basic statement in the same routine Basic uses to check for Ctrl-C and for interrupts. We will use it to do the actual physical updating of the display rather than doing it in the draw routines. This optimises screen update as follows:
Drawing a filled circle will call drawrectangle multiple times. By putting the screen update after completion of the CIRCLE Basic statement rather than after each drawrectangle I/O to the screen is minimised. Remember there are 8 pixels represented by each byte so we want to minimise the chance of writing the same byte multiple times by waiting until the complete circle is drawn.

Next we are going to initialise the screen itself so a helper function is useful

---

void spi_write_command(unsigned char data){
    PinSetBit(Option->LCD_CD, LATCLR);
    PinSetBit(Option->LCD_CS, LATCLR);
    SPIsend(data);
    PinSetBit(Option->LCD_CS, LATSET);
}

---

 

spi_write_command sets the display to receive a command byte by setting CD low. It then sets chip-select low and outputs the command byte before returning chip-select high.

Using this we can then send the commands needed to initialise the screen:

---

//Reset the SSD1963
    PinSetBit(Option->LCD_Reset,LATSET);
    uSec(10000);
    PinSetBit(Option->LCD_Reset,LATCLR);
    uSec(10000);
    PinSetBit(Option->LCD_Reset,LATSET);
    uSec(10000);
    spi_write_command(0xAE); //DISPLAYOFF) 
    spi_write_command(0xD5); //DISPLAYCLOCKDIV 
    spi_write_command(0x80); //the suggested ratio 0x80 
    spi_write_command(0xA8); //MULTIPLEX 
    spi_write_command(0x3F); // 
    spi_write_command(0xD3); //DISPLAYOFFSET 
    spi_write_command(0x0); //no offset 
    spi_write_command(0x40); //STARTLINE 
    spi_write_command(0x8D); //CHARGEPUMP 
    spi_write_command(0x14) ;
    spi_write_command(0x20); //MEMORYMODE 
    spi_write_command(0x00); //0x0 act like ks0108 
    spi_write_command(0xA1); //SEGREMAP OR 1 
    spi_write_command(0xC8); //COMSCANDEC 
    spi_write_command(0xDA); //COMPINS 
    spi_write_command(0x12) ;
    spi_write_command(0x81); //SETCONTRAST 
    spi_write_command(0xCF) ;
    spi_write_command(0xd9); //SETPRECHARGE 
    spi_write_command(0xF1) ;
    spi_write_command(0xDB); //VCOMDETECT 
    spi_write_command(0x40) ;
    spi_write_command(0xA4); //DISPLAYALLON_RESUME 
    spi_write_command(0xA6); //NORMALDISPLAY 
    spi_write_command(0xAF); //DISPLAYON

---

 

First we toggle the reset line to set things back to a defined state. Then we send a sequence of commands that are required by the SSD1306 controller. As stated above Google and the controller datasheet are the only ways of deriving the appropriate commands for any given controller.

Next we need to tell the Micromite firmware about the size of the display :

---

if(Option->DISPLAY_ORIENTATION&1){
        HRes=HorizontalRes;
        VRes=VerticalRes;
    } else {
        VRes=HorizontalRes;
        HRes=VerticalRes;
    }

---

 

HRes and VRes are defined in cfunctions.h

Finally we need to set the locations of our drawrectangle, drawbitmap, and updatedisplay routines for access by Basic, clear the screen and restore the SPI configuration. We return the address of the memory map to Basic so that we can inspect it if required using PEEK.

---

 

//Set the DrawRectangle vector to point to our function
    DrawRectangleVector=DrawRectangleVectorOffset;

    //Set the DrawBitmap vector to point to our function
    DrawBitmapVector=DrawBitmapVectorOffset;
     
     //Set the end of Basic statement vector to point to our routine
    
    CFuncmInt=updatedisplayVectorOffset;
    
    //CLS
    DrawRectangle(0,0,HRes-1,VRes-1,0);
    SPIBRG=brgsave; //restore user (or my) setup
    SPICON=consave;
    SPICON2=con2save;

    return (unsigned int)p;

---

 

That is all we need in the main routine. Next post I’ll look at the actual drawing routines. I’ll put the complete code at the end of the thread. In this post we look at the first of the three routines that we have told the Micromite firmware about and which it will use to actually write to the display in response to the various Basic drawing commands: BOX, CIRCLE, TEXT etc.

First we will look at “updatedisplay” and its helper function OLED_setxy.

---

void OLED_setxy(int x,int y){ //Set the cursor to column x and row (page) y
  unsigned char* p=(void *)(unsigned int)(StartOfCFuncRam);
  if(p[displaysize])x+=2;
  spi_write_command(0xB0+y)        ; //set page address 
  spi_write_command(0x10 | ((x>>4) & 0x0F))  ; //set high col address 
  spi_write_command(x & 0x0f)     ; //set low col address 
}

void updatedisplay(void){
    int m,n;
    char* p=(void *)(unsigned int)(StartOfCFuncRam);
    if(p[update]){
        unsigned int consave=0,brgsave=0,con2save;
        p[update]=0;
        brgsave=SPIBRG; //save any user SPI setup
        consave=SPICON;
        con2save=SPICON2;
        SPICON=0x8060;
        SPIBRG=2;
        SPICON2=0xC00;
        for(n=0;n<screenrows;n++){
            OLED_setxy(0,n);
            PinSetBit(Option->LCD_CS, LATCLR);
            PinSetBit(Option->LCD_CD, LATSET);
            for(m=n*screenwidth;m<(n+1)*screenwidth;m++){
                SPIsend(p[m]);
            }
            PinSetBit(Option->LCD_CS, LATCLR);
        } 
        SPIBRG=brgsave;  //restore user (or my) setup
        SPICON=consave;
        SPICON2=con2save;
    }
}

---

 

As stated previously this is the only routine that actually outputs to the display hardware. It is called after every Basic statement irrespective of whether that statement was a drawing command so the first thing it needs to do is establish if a drawing command has been used and exit immediately if not.

char* p=(void *)(unsigned int)(StartOfCFuncRam);
if(p[update]){

These two statements set up access to the permanent memory area and then test whether a flag has been set in p[update]. We will see later that this flag is set in both drawrectangle and drawbitmap. If it isn’t set we can exit immediately with no further processing minimising the overhead on Basic.

If p[update] is set then we know that the screen needs updating.

In this case the first thing we do is to set up some local variables and zero the flag to mark that the update is going to be done. We then save any user SPI setup and replace it with our own.

unsigned int consave=0,brgsave=0,con2save;
p[update]=0;
brgsave=SPIBRG; //save any user SPI setup
consave=SPICON;
con2save=SPICON2;
SPICON=0x8060;
SPIBRG=2;
SPICON2=0xC00;

We could then do all sorts of optimisations to work out which bits of the display need updating but there are only 1024 bytes needed to update the complete display and we are running the SPI bus at 6Mbps (assuming 48MHz CPU) so the time taken to completely refresh the display is less than 2msec. Given this it is easiest to just do a complete refresh.

As previously mentioned the display is divided into 8 rows of 8 vertical pixels (64 total) and 128 columns. We therefore set up a loop to update each row:

for(n=0;n<screenrows;n++){

At the beginning of the loop we need to call OLED_setxy to position the write cursor. This sends specific commands to the display as specified by the datasheet to do this.

Then we need to tell the display that the next bytes sent will be data by setting the command/data pin high “PinSetBit(Option->LCD_CD, LATSET);” and select the controller “PinSetBit(Option->LCD_CS, LATCLR);”

We can then run a loop outputting each byte for that row in turn

for(m=n*screenwidth;m<(n+1)*screenwidth;m++){
SPIsend(p[m]);
}

Note how we are using the row number “n” multiplied by the screenwidth to get the correct offset into the memory map display for that row of data.

At the end of each row we disable the chip ready for the next cursor positioning statement.

Finally when both loops have finished we can restore the user’s SPI setup.

Next post we look at the drawrectangle function.

drawrectangle is the most important of the drawing primitives and is used for all output other than TEXT or GUI BITMAP.

---

long long DrawRectangleMEM(int x1, int y1, int x2, int y2, int c){
    unsigned char* p=(void *)(unsigned int)(StartOfCFuncRam);
    int i,j,loc,t;
    unsigned char mask;
    if(x2 <= x1) { t = x1; x1 = x2; x2 = t; }
    if(y2 <= y1) { t = y1; y1 = y2; y2 = t; }
    if(x1 < 0) x1 = 0; if(x1 >= screenwidth) x1 = screenwidth - 1;
    if(x2 < 0) x2 = 0; if(x2 >= screenwidth) x2 = screenwidth - 1;
    if(y1 < 0) y1 = 0; if(y1 >= screenheight) y1 = screenheight - 1;
    if(y2 < 0) y2 = 0; if(y2 >= screenheight) y2 = screenheight - 1;
        
     for(i=x1;i<=x2;i++){
        for(j=y1;j<=y2;j++){
           loc=i+(j/8)*screenwidth; //get the byte address for this bit
           mask=1<<(j % 8); //get the bit position for this bit
           if(c){
               p[loc]|=mask;
           } else {
               p[loc]&=(~mask);
           }
        }
    }
    p[update]=1;
}

---

 

The code uses the defined calling sequence discussed in the first post on the thread.

long long DrawRectangleMEM(int x1, int y1, int x2, int y2, int c){

This defines the top left and bottom right coordinates of a rectangle and its colour. In the case of our monochrome display we will treat a colour of 0 as black and any other value as white.

As always we start by linking into the permanent shared memory

unsigned char* p=(void *)(unsigned int)(StartOfCFuncRam);

giving us access to the in-processor memory map.

The next two statements make sure x2 is bigger than x1 and swap them round if not before doing the same for y2 and y1.

Then we need to check that the limits of the rectangle fall within our screen space and truncate them if not. Some displays don’t mind coordinates outside the drawing area, others crash. In our case an invalid coordinate could cause us to write outside of the memory map crashing the Micromite! It is good practice to include the checks in all cases.

Next we set up two loops for the x and y extents of the rectangle and for each coordinate within the rectangle calculate the position in the memory map in which it is represented and the bit position within the byte

loc=i+(j/8)*screenwidth; //get the byte address for this bit
mask=1<<(j % 8); //get the bit position for this bit

Then based upon the colour we either “OR” the bit into the memory map or “AND” it out of the memory map.

if(c){
p[loc]|=mask;
} else {
p[loc]&=(~mask);
}

Once we have done this for all locations within the rectangle we then set the status marker to tell the updatedisplay routine that it needs to refresh the display. Note however, as discussed above, this will only happen at the end of the complete Basic statement which may contain many calls to drawrectangle.

This all looks good but at the moment it only caters for the default orientation i.e. landscape. The SSD1306 doesn’t support any sort of hardware rotation so we need a bit of code to do this for us by remapping the X,Y coordinates of the rectangle based on the required orientation. The code as-is works for landscape so we will need three conditionals to cater for portrait, reverse landscape and reverse portrait.

---

if(Option->DISPLAY_ORIENTATION==PORTRAIT){
        t=x1;
        x1=screenwidth-y2-1;
        y2=t;
        t=x2;
        x2=screenwidth-y1-1;
        y1=t;
    }
     if(Option->DISPLAY_ORIENTATION==RLANDSCAPE){
        x1=screenwidth-x1-1;
        x2=screenwidth-x2-1;
        y1=screenheight-y1-1;
        y2=screenheight-y2-1;
    }
   if(Option->DISPLAY_ORIENTATION==RPORTRAIT){
        t=y1;
        y1=screenheight-x1-1;
        x1=t;
        t=y2;
        y2=screenheight-x2-1;
        x2=t;
    }

---

 

Nothing very complicated here but it took a few minutes of trial and error and writing coordinate mappings on the back of old envelopes to get right. If we look at the RLANDSCAPE clause we can see the code is just swapping each x and y coordinate to the opposite end of its axis.

Next drawbitmap

drawbitmap is the more complicated of the two drawing routines because it has to cater for scaling the bitmap as well as just outputting it.

---

void DrawBitmapMEM(int x1, int y1, int width, int height, int scale, int fc, int bc, unsigned char *bitmap){
    int i, j, k, m, x, y,t, loc;
    unsigned char omask, amask;
    unsigned char* p=(void *)(unsigned int)(StartOfCFuncRam);
    for(i = 0; i < height; i++) {                                   // step thru the font scan line by line
        for(j = 0; j < scale; j++) {                                // repeat lines to scale the font
            for(k = 0; k < width; k++) {                            // step through each bit in a scan line
                for(m = 0; m < scale; m++) {                        // repeat pixels to scale in the x axis
                    x=x1 + k * scale + m ;
                    y=y1 + i * scale + j ;
                    loc=x+(y/8)*screenwidth; //get the byte address for this bit
                    omask=1<<(y % 8); //get the bit position for this bit
                    amask=~omask;
                    if(x >= 0 && x < screenwidth && y >= 0 && y < screenheight) {  // if the coordinates are valid
                        if((bitmap[((i * width) + k)/8] >> (((height * width) - ((i * width) + k) - 1) %8)) & 1) {
                            if(fc){
                                p[loc]|=omask;
                             } else {
                                p[loc]&=amask;
                             }
                       } else {
                            if(bc){
                                p[loc]|=omask;
                             } else {
                                p[loc]&=amask;
                             }
                        }
                   }
                }
            }
        }
    }
    p[update]=1;
}

---

 

As before the calling sequence is completely specified and must be followed exactly:

void DrawBitmapMEM(int x1, int y1, int width, int height, int scale, int fc, int bc, unsigned char *bitmap)

This defines the top left of the area of the screen in which the bitmap will be displayed and the height and width of the bitmap. Using the scale parameter then defines the size of the bitmap on the screen: width * scale by height * scale.

As before, we first get access to the processor memory map and then there are four loops within loops that do the main work. This code was “acquired” from Geoff’s Micromite source and I have then adapted it for the various flavours of displays.

The loops are commented to explain how they step through the on-screen display area. In the middle of the four loops is the code that actually gets the “bit” from the bitmap and outputs the required information, in this case by updating the memory map, but, in the case of a colour display, it would be a direct write to the TFT display controller.

First we need to calculate the screen x,y coordinates from the loop counters:

x=x1 + k * scale + m ;
y=y1 + i * scale + j ;

Then we need to convert these into a byte/bit location in the memory map

loc=x+(y/8)*screenwidth; //get the byte address for this bit
omask=1<<(y % 8); //get the bit position for this bit
amask=~omask; //create a mask for ANDing this bit out

Next we need to make sure the x,y coordinates are within the display area:

if(x >= 0 && x < screenwidth && y >= 0 && y < screenheight) // if the coordinates are valid

If they are we can locate the relevant bit in the bitmap and test whether it is a one or a zero:

if((bitmap[((i * width) + k)/8] >> (((height * width) – ((i * width) + k) – 1) %8)) & 1) {

This tells us whether to output the foreground colour (fc) or the background colour (bc). In our monochrome example these can only be zero or non-zero so based on this we can update our memory map:

if(fc){
p[loc]|=omask;
} else {
p[loc]&=amask;
}
or:
if(bc){
p[loc]|=omask;
} else {
p[loc]&=amask;
}

Finally as all the loops terminate we set the status byte to say a screen update is required.

As with the drawrectangle code this version only deals with the default orientation: landscape.

The code to generalise this is the same as draw rectangle but we only need to do it for one coordinate pair:

---

if(Option->DISPLAY_ORIENTATION==PORTRAIT){
                        t=x;
                        x=VRes-y-1;
                        y=t;
                    }
                    if(Option->DISPLAY_ORIENTATION==RLANDSCAPE){
                        x=HRes-x-1;
                        y=VRes-y-1;
                    }
                    if(Option->DISPLAY_ORIENTATION==RPORTRAIT){
                        t=y;
                        y=HRes-x-1;
                        x=t;
                    }

---

 

This code is inserted once the x,y coordinates have been calculated in the inner loop.

Next post we will look at putting this all together.

I’ve attached the complete self-contained MPLabX project directory for this driver so that if you are up and running with MPLabX and XC32 v1.33 you can build it yourself.

Once this is compiled and the .ELF file run through CFGEN a simple MM.STARTUP routine is required to load the driver. The complete Basic program is given below.
After “LIBRARY SAVE” this takes just 4K of memory.

This concludes the set of CFunction tutorials. Please let me have comments and questions and I’ll do my best to answer. Hopefully over the three tutorials you have seen that writing CFunctions is fairly easy but more importantly is incredibly powerful in allowing the scope of Micromite Basic to be expanded in many different ways.