WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

_gdisplay_common.h

Defines all of the commands that are common to all graphical displays. This file is automatically included once you include the header file for the actual display you are using.
The graphic displays can, at the very least, be used instead of text displays but give a larger number of text lines and columns.
When using graphical displays with WebbotLib it introduces the concept of a background colour (the paper colour) as well as the foreground colour (the ink colour) used when drawing.
In the same way that a character based display has a text cursor position there is also 'graphics cursor' holding the current pixel position where 0,0 represents the top left corner. The drawing functions can then specify either absolute screen pixel positions or they can be relative to the current graphics cursor. This allows you, for example, to have a function which draws a complex shape relative to the current graphics cursor and this can then be called multiple times to draw the shape at different positions on the screen.
WebbotLib also allows you to easily add graphic "widgets" at any position, and size, on the screen. The current set of widgets allow you to use dials, thermometers and numbers. The widgets are extensible, ie you can add your own, and if you want to contribute them to the library then get in touch. Don't forget you can also use the displayHorizGraph and displayVertGraph functions to display bar graphs just like you can on a text display.

 

Function

 


displayShutdown(GDISPLAY* display)

Shuts down the display.
Most graphical displays don't react too kindly to you just switching them off - and can even blow the display. This command should therefore be used, where possible, as it shuts the display down properly.
Perhaps you could use a push button, which when pressed, does things like shutting down the display and turning off motors etc and then enters an infinite loop.
Once shut down the display cannot be woken up again via software until the power is turned back on again.

displaySetPaperRGB(GDISPLAY* display, uint8_t r,uint8_t g,uint8_t b)

Sets the paper colour to the specified red, green and blue components.
Drawing non-transparent text will use the paper colour as the text background.
If the display is cleared then the whole display is set to the new background colour.
For example: to set the whole 'display' background to green then:-
displaySetPaperRGB(&display, 0,255,0);
displayClear(&display);

displaySetPaper(GDISPLAY* display, const COLOR* color)

Sets the paper colour.
Drawing non-transparent text will use the paper colour as the text background.
If the display is cleared then the whole display is set to the new background colour.
For example: to set the whole 'display' background to the colour of the pixel at 10,20 then:-
COLOR pixel;
// Read the pixel at 10,20
displayReadAt(&display, 10,20, &pixel);
 
// Set the paper colour to that colour
displaySetPaper(&display, &pixel);
 
// Clear the whole screen to the paper colour
displayClear(&display);

displaySetInkRGB(GDISPLAY* display, uint8_t r,uint8_t g,uint8_t b)

Sets the ink colour to the specified red, green and blue components.
For example: to set the ink colour to white then:-
displaySetInkRGB(&display, 255,255,255);

displaySetInk(GDISPLAY* display, const COLOR* color)

Sets the ink colour.
For example: to set the ink colour to be the same colour as the pixel at the current graphics cursor position:-
COLOR pixel;
// Read the pixel at the current cursor position
displayReadBy(&display, 0,0, &pixel);
 
// Set the ink colour to that colour
displaySetInk(&display, &pixel);

displayMoveTo(GDISPLAY* display, PIXEL x, PIXEL y)

Moves the graphics cursor to the absolute x,y position on the display without drawing anything.
Note that since there is no 'flashing cursor' then there is no visual effect.

displayMoveBy(GDISPLAY* display, PIXEL x, PIXEL y)

Moves the graphics cursor by adding the specified x,y offsets to the current graphics cursor.
Note that since there is no 'flashing cursor' then there is no visual effect.

displayPlotAt(GDISPLAY* display, PIXEL x,PIXEL y

Moves the graphics cursor to the absolute x,y position on the display and plots that pixel in the current ink colour.
On return the graphics cursor is set to the specified x,y position.

displayPlotBy(GDISPLAY* display, PIXEL x,PIXEL y)

Plots the pixel at the current graphics cursor plus the specified x,y offsets in the current ink colour.
Note that the current graphics cursor is left unchanged,

boolean displayReadAt(GDISPLAY* display, PIXEL x,PIXEL y, COLOR* color)

Moves the graphics cursor to the absolute x,y position on the display and reads the colour of the pixel.
Returns FALSE if there is no response from the display.
On return the graphics cursor is set to the specified x,y position.

boolean displayReadBy(GDISPLAY* display, PIXEL x,PIXEL y, COLOR* color)

Reads the pixel at the current graphics cursor plus the specified x,y offsets.
Returns FALSE if there is no response from the display.
Note that the current graphics cursor is left unchanged.

displayLineTo(GDISPLAY* display, PIXEL x, PIXEL y)

Draws a line from the graphics cursor to the specified absolute x,y position in the current ink colour.
On return the graphics cursor is set to the specified x,y position.

displayLineBy(GDISPLAY* display, PIXEL x, PIXEL y)

Draws a line from the current graphics cursor to the current graphics cursor plus the specified x,y offsets in the current ink colour.
On return the graphics cursor is set to the end of the line.
Example: to draw a rectangle that is 10 pixels wide and 10 high using the current graphics cursor as the top left corner:
displayLineBy(&display, 10, 0); // Top
displayLineBy(&display, 0, 10); // Right
displayLineBy(&display, -10, 0); // Bottom
displayLineBy(&display, 0, -10); // Left

PIXEL displayGetXRes(const GDISPLAY* display)

Returns the total number of pixels across the display.

PIXEL displayGetYRes(const GDISPLAY* display)

Returns the total number of pixels down the display.

PIXEL displayGetXPos(const GDISPLAY* display)

Returns the x position of the current graphics cursor.

PIXEL displayGetYPos(const GDISPLAY* display)

Returns the y position of the current graphics cursor.

displayTriangleAt(GDISPLAY* display, PIXEL x1,PIXEL y1, PIXEL x2,PIXEL y2, PIXEL x3,PIXEL y3, boolean fill)

Draws, or fills, a triangle in the current ink colour between the three specified co-ordinates.
On return the graphics cursor will be set to x1,y1.
Note that drawing beyond the edges of the screen will have an 'unknown' effect.

displayTriangleBy(GDISPLAY* display, PIXEL x1,PIXEL y1, PIXEL x2,PIXEL y2, PIXEL x3,PIXEL y3, boolean fill)

Draws, or fills, a triangle in the current ink colour by adding the three specified co-ordinate offsets to the current graphics cursor.
On return the graphics cursor will be left unchanged.
Note that drawing beyond the edges of the screen will have an 'unknown' effect.

displayRectangleAt(GDISPLAY* display, PIXEL x1,PIXEL y1, PIXEL x2,PIXEL y2, boolean fill)

Draws, or fills, a rectangle in the current ink colour using the two specified co-ordinates as the top left and bottom right corners.
On return the graphics cursor will be set to x1,y1.
Note that drawing beyond the edges of the screen will have an 'unknown' effect.

displayRectangleBy(GDISPLAY* display, PIXEL x1,PIXEL y1, PIXEL x2,PIXEL y2, boolean fill)

Draws, or fills, a rectangle in the current ink colour by adding the two specified co-ordinate offsets to the current graphics cursor to give the top left and bottom right corners.
On return the graphics cursor will be left unchanged.
Note that drawing beyond the edges of the screen will have an 'unknown' effect.

displayCircle(GDISPLAY* display, PIXEL radius, boolean fill)

Draws, or fills, a circle in the current ink colour centred on the current graphics cursor and of the specified radius.
On return the graphics cursor will be left unchanged.
Note that drawing beyond the edges of the screen will have an 'unknown' effect.

displayReplace(GDISPLAY* display, const COLOR *src, const COLOR *dst, PIXEL x, PIXEL y, PIXEL w, PIXEL h)

Replaces all pixels within the specified rectangle that are of one colour with a new colour.
Example: to change any red pixels to green pixels in the rectangle whose top left corner is at 10,11 and is 20 pixels wide and 15 high:-
COLOR red = MAKE_COLOR_RGB( 255,0,0 );
COLOR green = MAKE_COLOR_RGB( 0,255,0 );
displayReplace(&display, &red, &green, 10,11, 20,15)

displayChar(GDISPLAY* display, uint8_t c, boolean transparent)

Draws a text character in the current ink colour at the current graphics cursor position.
If the 'transparent' parameter is FALSE then the background of the character is set to the current paper colour otherwise the character is plotted on top of the existing pixel colours.
On return the graphics cursor is moved to the right so that this function can be called multiple times to plot a string of text.

widgetDraw(GDISPLAY_WIDGET* widget)

Draws the static (non-changeable) part of the widget.
When using widgets you normally never clear the screen and so the drawing of the main part of the widget can be done once - in appInitSoftware.

widgetUpdate(GDISPLAY_WIDGET* widget)

Draws the variable part of the widget ie the part that displays the current value(s).
If the current value(s) haven't changed since the last time this was called then it will not send any commands to the display.

DIAL_WIDGET MAKE_DIAL_WIDGET

Create a circular dial widget with a needle to show the current value.
This command takes a long list of parameters which should be specified in the following order:-
GDISPLAY* - the address of the display ie the name you have given the display in Project Designer prefixed with an '&' symbol
x - The x screen co-ordinate of the top left corner of the widget
y - The y screen co-ordinate of the top left corner of the widget
w - The pixel width of the widget
h - The pixel height of the widget
p - The number of pixels to be used as padding (border) inside the widget
r,g,b - The rgb colour for the background colour of the widget rectangle
r,g,b - The rgb colour for the needle
r,g,b - The rgb colour for the background of the dial
r,g,b - The rgb colour for the graduation tick marks on the dial
minAngle - The starting angle in degrees for the arc of the dial. Where 0 is due North.
maxAngle - The ending angle in degrees for the arc of the dial. Where 0 is due North.
minVal - The value that will move the needle to 'minAngle'
maxVal - The value that will move the needle to 'maxValue'
gradVal - Plot graduation tick marks every 'gradVal' steps between 'minVal' and 'maxVal'
Note that 'minAngle + maxAngle' must be <= 360
Dial Widget Example
Here is an example that assumes your graphical display is called 'display':
DIAL_WIDGET dial = MAKE_DIAL_WIDGET( \
    &display,    /* The graphic display */
    10,10,       /* Top left corner */
    40,40,       /* Width and height of widget */
    1,           /* Padding around widget */
    0,0,96,      /* Background colour = blue */
    255,0,0,     /* Needle colour = red */
    128,128,128, /* Dial background = grey */
    255,255,255, /* Grad mark colour = white */
    -140,140,    /* min and max angle */
    -5,5,        /* display values from -5 to +5 */
    2.5          /* grad mark every 2.5 */
);
In your appInitSoftware you should draw the widget:
widgetDraw( &dial );
In your main loop you can set the new value for the needle. In this case we will make the needle gradually move along the dial:
for(double v = -5; v <= 5; v += 0.2){
    // Set the value for the needle
    dialSetValue(&dial,v);
 
    // Draw the needle
    widgetUpdate(&dial);
 
    // Wait for a moment before moving again
    clockWaitms(50);
}
If you want to also be able to see the actual numeric value then combine this example with that given in MAKE_NUMBER_WIDGET

NUMBER_WIDGET MAKE_NUMBER_WIDGET

Create a widget for displaying numbers which is useful if you want to see the actual value being displayed by some other more graphical widget.
This command takes a long list of parameters which should be specified in the following order:-
GDISPLAY* - the address of the display ie the name you have given the display in Project Designer prefixed with an '&' symbol
x - The x screen co-ordinate of the top left corner of the widget
y - The y screen co-ordinate of the top left corner of the widget
w - The pixel width of the widget
h - The pixel height of the widget
p - The number of pixels to be used as padding (border) inside the widget
r,g,b - The rgb colour for the background colour of the widget rectangle
r,g,b - The rgb colour for the number digits
r,g,b - The rgb colour for the background of the numbers
digits - The number of digits to the left of the decimal point
places - The number of digits to the right of the decimal point
minVal - The lowest value that will be displayed
maxVal - The maximum value that will be displayed
Note that when you assign a new value to the widget then it will be clamped to make sure that it is the range 'minVal' to 'maxVal'.
Number Widget Example
Here is an example that assumes your graphical display is called 'display':
NUMBER_WIDGET numb = MAKE_NUMBER_WIDGET( \
    &display,    /* The graphic display */
    10,50,       /* Top left corner */
    40,20,       /* Width and height of widget */
    1,           /* Padding around widget */
    0,0,96,      /* Background colour = blue */
    255,255,255, /* Digit colour = white */
    0,0,96,      /* Background = grey */
    2,1,    /* Number format is XX.X */
    -5,5,        /* display values from -5 to +5 */
);
In your appInitSoftware you should draw the widget:
widgetDraw( &numb );
In your main loop you can set the new value for the number. In this case we will make the number gradually move between the min and max values:
for(double v = -5; v <= 5; v += 0.2){
    // Set the value for the display
    numberSetValue(&numb,v);
 
    // Draw the number
    widgetUpdate(&numb);
 
    // Wait for a moment before moving again
    clockWaitms(50);
}
Combining this example with the example for MAKE_DIAL_WIDGET then you should see the number being displayed below the dial.

THERMO_WIDGET MAKE_THERMO_WIDGET

Create a mercury temperature gauge widget with a column to show the current value.
This command takes a long list of parameters which should be specified in the following order:-
GDISPLAY* - the address of the display ie the name you have given the display in Project Designer prefixed with an '&' symbol
x - The x screen co-ordinate of the top left corner of the widget
y - The y screen co-ordinate of the top left corner of the widget
w - The pixel width of the widget
h - The pixel height of the widget
p - The number of pixels to be used as padding (border) inside the widget
r,g,b - The rgb colour for the background colour of the widget rectangle
r,g,b - The rgb colour for the mercury column
r,g,b - The rgb colour to draw the outline of the thermometer
r,g,b - The rgb colour for the graduation tick marks on the thermometer
minVal - The value that will move the mercury to the bottom
maxVal - The value that will move the mercury to the top
gradVal - Plot graduation tick marks every 'gradVal' steps between 'minVal' and 'maxVal'
Thermometer Widget Example
Here is an example that assumes your graphical display is called 'display':
THERMO_WIDGET thermo = MAKE_THERMO_WIDGET( \
    &display,    /* The graphic display */
    10,10,       /* Top left corner */
    30,40,       /* Width and height of widget */
    1,           /* Padding around widget */
    0,0,96,      /* Background colour = blue */
    255,0,0,     /* Mercury colour = red */
    128,128,128, /* Outline colour = grey */
    255,255,255, /* Grad mark colour = white */
    -5,5,        /* display values from -5 to +5 */
    2.5          /* grad mark every 2.5 */
);
In your appInitSoftware you should draw the widget:
widgetDraw( &thermo );
In your main loop you can set the new value for the mercury. In this case we will make the mercury gradually move up the thermometer:
for(double v = -5; v <= 5; v += 0.2){
    // Set the value for the needle
    thermoSetValue(&thermo,v);
 
    // Draw the needle
    widgetUpdate(&thermo);
 
    // Wait for a moment before moving again
    clockWaitms(50);
}
If you want to also be able to see the actual numeric value then combine this example with that given in MAKE_NUMBER_WIDGET

Valid XHTML 1.0 Transitional