Using Primitive Rendering Functions in Blocking and Non-Blocking Modes

All primitive rendering functions returns a status.

• 0 – when the primitive was not successfully rendered
• 1 – when the primitive was successfully rendered

#define USE_NONBLOCKING_CONFIG // Comment this line to use blocking configuration

When using a display controller with hardware accelerated primitives (like SSD1926 which is on the Graphics PICtail™ Plus Board Version 3 (AC164127-3) faster primitive rendering on Line(), Rectangle() and Bar() functions will be performed. Compiling with the Blocking or Non-Blocking mode set will still use the accelerated primitives but the application code directly calling the primitive functions will have to be coded accordingly. 

To explain the two modes when directly calling the primitive functions please take a look at the example below. 

Case 1: USE_NONBLOCKING_CONFIG disabled

// all primitives are blocking calls
Line(a,b);
Rectangle(c,d,e,f);
Bar(c+2, d+2, e-2, f-2)

Case 2: USE_NONBLOCKING_CONFIG enabled

// all primitives are non-blocking calls
while(!Line(a,b));
while(!Rectangle(c,d,e,f));
while(!Bar(c+2, d+2, e-2, f-2));

If the while check is not in place, it possible that the only primitive that you will see in the screen is the Line(). 

For case 2, one can also be creative in the application code and implement some form of non-blocking scheme and make use of the time while waiting for the primitives to render. 

Another example for case 2:

WORD DrawMyFigure(a, b, c, d, e, f)
{
    typedef enum {
       DRAW_LINE,
       DRAW_RECT,
       DRAW_BAR,
} DRAW_MYFIGURE_STATES;
static DRAW_MYFIGURE_STATES state = DRAW_LINE;

    if(IsDeviceBusy()) // checks if the hardware is still busy
        return 0;

    switch(state){
        case DRAW_LINE:
            if (!Line(a, b))
                return 0;
            state = DRAW_RECT;
        case DRAW_RECT:
            if(!Rectangle(c,d,e,f))
                return 0;
            state = DRAW_BAR;
        case DRAW_BAR:
            if(!Bar(c+2, d+2, e-2, f-2));
                return 0;
            state = DRAW_LINE;
            return 1;
    }
}

This non-blocking code can be used in the application and the application can do other tasks whenever DrawMyFigure() returns 0. Application should call DrawMyFigure() again until it return a 1 signifying that the Line, Rectangle and Bar were drawn successfully.