- Warning
- openGLCD is not backward compatible with GLCDv3.
While many of the API functions are the same names, there are differences that will prevent existing code from compiling or working properly.
The primary library include header file name used by GLCDv3 is a different name which will keep existing GLCDv3 code from compiling.
More importantly, width and height parameters to all API functions in openGLCD are exact pixels for the drawn object whereas this was not the case in GLCDv3.
Examples:
- If a width of 6 is specified, the width of the drawn object will be exactly 6 pixels
- If a height of 6 is specified, the height of the drawn object will be exactly 6 pixels
The main include header file for sketches is
If any of the following library functions are used, the code must be modified to use the new function names.
Also, the length parameter will have to be adjusted for the height/width parameters.
- DrawVertLine(x, y, length, color) is now: DrawVLine(x, y, height, color)
- DrawHoriLine(x, y, length, color) is now : DrawHLine(x, y, width, color)
- ClearSysTextLine(row) is now EraseTextLine(row)
- SetTextMode() is now SetAreaMode(mode)
If any of the following GLCDv3 functions are used:
height and width parameters will will have to be adjusted since openGLCD specifies exact pixels for height and width parameters.
All versions of the function DefineArea() return 0 on sucess or an error code on failure vs GLCDv3 DefineArea() returned a status of true on success and false on failure.
GLCDv3 Compatibility Header
openGLCD provides a header file to temporarily aid in transitioning existing GLCDv3 sketches to openGLCD. Sketches may include the GLCDv3 compatibility header file just after the main openGLCD header to automatically map the sketches use of GLCDv3 functions and parameters to openGLCD.
#include <openGLCD.h>
#include <include/openGLCD_GLCDv3.h>
Notable exceptions are the following functions:
- DefineArea()for which there is no backward compatibilty.
The returns status from this funtion has changed.
- Warning
- While using this compatibility header should allow most existing GLCDv3 sketches to compile and work as if they were still using GLCDv3, it is not recommended as a permanent solution.
Also, it should be noted that when using this backward compability capability, the documention no longer matches the API functions and parameters the sketch is actually using. For example:
The documenation will state that width and height are an exact number of pixels; however, when the sketch is running in GLCDv3 compability mode, the compatibilty header will modify the parameters to be GLCDv3 compatible parameters which draws the objects 1 pixel bigger than the width and height parameters. While this makes the existing sketch code backward compability with GLCDv3, this difference can easily create confusion when looking at results obtained vs parameters passed, vs the documenation.
- Note
- For even greater temporary GLCDv3 compatibility, a dummy glcd.h file can be created with the following contents:
#include <openGLCD.h>
#include <include/openGLCD_GLCDv3.h>
which should allow most existing GLCDv3 sketches to work "as is". However, if this is done, GLCDv3 and openGLCD cannot both be installed at the same time since the sketch cannot be assured to get the glcd.h from the openGLCD library.
- Warning
- While creating a glcd.h compatibility file can provide instant backward compatiblity to most existing GLCDv3 sketches, it should be cautioned, as mentioned above, that those sketches will be using the functions and parameters as defined in GLCDv3 vs openGLCD. The results obtained from the functions will not match the openGLCD documenation. Therefore, as stated above, this method of backward compability is not recommeded as a permanent solution.