RA8875.h

00001 ///
00002 /// @mainpage RA8875 Display Controller Driver library
00003 ///
00004 /// The RA8875 Display controller is a powerful interface for low cost displays. It
00005 /// can support displays up to 800 x 480 pixels x 16-bit color. 
00006 ///
00007 /// Aside from 800 x 480 pixel displays, another common implementation is 
00008 /// 480 x 272 x 16 with two layers. The two layers can be exchanged, or blended 
00009 /// in various ways (transparency, OR, AND, and more). It includes graphics 
00010 /// acceleration capabilities for drawing primitives, such as line, rectangle, 
00011 /// circles, and more.
00012 ///
00013 /// It is not a display for video-speed animations, and maybe could hold its own 
00014 /// as a slow picture frame, at least when using the SPI ports. How the performance 
00015 /// differs using I2C, 8-bit parallel or 16-bit parallel has not been evaluated.
00016 /// Certainly the parallel interface option would be expected to be a lot faster.
00017 ///
00018 /// What it is good at is performing as a basic display for appliance or simple
00019 /// home automation, and because of the built-in capability to draw lines, circles, 
00020 /// ellipses, rectangles, rounded rectangles, and triangles, it does a lot of the 
00021 /// work that your host micro would otherwise be doing, and in many cases it does
00022 /// it much faster.
00023 ///
00024 /// While it is good to know about Bresenham's algorithm (to draw a line) and how
00025 /// to implement it in software, this controller simplifies things - 
00026 /// You just give it (x1,y1), (x2,y2) and tell it to draw a line. 
00027 /// Without the hardware acceleration built into the RA8875, the host would have to
00028 /// compute every point, set the graphics cursor to that point, and fill in that
00029 /// point with the target color. A diagonal line of some length might take 100
00030 /// interactions instead of just a few. Other drawing primitives are similarly easy. 
00031 ///
00032 /// It has some built-in fonts, which can be enhanced with optional font-chips, and 
00033 /// with the provided software font engine, and a few instructions, you can convert
00034 /// most any True Type Font into the data structures suitable for this display. 
00035 ///
00036 /// To round out the features, this library offers the ability to render Bitmap (BMP),
00037 /// Icon (ICO), Join Photographic Experts Group (JPG), and Graphics Interchange Format 
00038 /// (GIF) images. These are implemented primarily in software, taking advantage of the 
00039 /// hardware acceleration where it can. 
00040 ///
00041 /// When you are satisfied with what appears on screen, there is a PrintScreen method 
00042 /// to pull that image back out and write it to a file system as a BitMap image.
00043 ///
00044 /// The controller additionally supports backlight control (via PWM), keypad scanning
00045 /// (for a 4 x 5 matrix) and resistive touch-panel support. Support for capacitive
00046 /// touch screens is also integrated, in a manner that makes the resistive and
00047 /// capacitive interfaces nearly API identical. The capacitive touch support is for 
00048 /// either the FT5206 or the GSL1680 controller chips.
00049 ///
00050 /// Here's a few hints to get started:
00051 /// * @ref Display_Config
00052 /// * @ref Touch_Panel
00053 /// * @ref Hardwired_KeyPad
00054 /// * @ref Example_Program
00055 /// * @ref Wiring_Diagram
00056 /// * @ref Future_Plans
00057 ///
00058 /// @todo Add APIs for the 2nd RA8875 PWM channel. If the frequency can be independently
00059 ///     controlled, it could be used as a simple beeper.
00060 /// @todo Figure out how to "init()" in the constructor. I ran into some issues if
00061 ///     the display was instantiated before main(), and the code would not run,
00062 ///     thus the exposure and activation of the init() function. If the constructor
00063 ///     was within main(), then it seemed to work as expected.
00064 ///
00065 /// @note As the author of this library, let me state that I am not affiliated with
00066 ///     Raio (silicon provider of the RA8875), or with BuyDisplay.com (where a lot 
00067 ///     of these displays can be purchased), I am simply a very satisfied customer 
00068 ///     of the technology of the RA8875 chip.
00069 ///
00070 /// @copyright Copyright © 2012-2019 by Smartware Computing, all rights reserved.
00071 ///     This library is predominantly, that of Smartware Computing, however some
00072 ///     portions are compiled from the work of others. Where the contribution of 
00073 ///     others was listed as copyright, that copyright is maintained, even as a 
00074 ///     derivative work may have been created for better integration in this library.
00075 ///     See @ref Copyright_References.
00076 ///
00077 /// @page Copyright_References Copyright References
00078 /// 
00079 /// Following are links to the known copyright references. If I overlooked any, it was
00080 /// unintentional - please let me know so I can update it. Some portions of the code
00081 /// have been acquired from the cloud, and where any copyright information was available,
00082 /// it was preserved.
00083 ///
00084 /// * @ref GraphicDisplay_Copyright
00085 /// * @ref TextDisplay_Copyright
00086 /// * @ref TinyJPEGDecompressor_Copyright
00087 /// * @ref RA8875::TouchPanelComputeCalibration
00088 ///
00089 /// @page Display_Config Display Configuration
00090 ///
00091 /// This section details basics for bringing the display online. At a minimum,
00092 /// the display is instantiated, after which nearly any of the available commands
00093 /// may be issued.
00094 ///
00095 /// During the instantiation, the display is powered on, cleared, and the backlight
00096 /// is energized. Additionally, the keypad and touchscreen features are activated.
00097 /// It is important to keep in mind that the keypad has its default mapping, 
00098 /// a resistive touchscreen does not yet have the calibration matrix configured, 
00099 /// and the RA8875::init() function is required to configure other important options
00100 /// like the display resolution.
00101 /// 
00102 /// @code 
00103 /// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
00104 /// lcd.init();
00105 /// lcd.foreground(Blue);
00106 /// lcd.line(0,0, 479,271);
00107 /// ...
00108 /// @endcode
00109 ///
00110 /// @section RA8875_Capabilities Basic Capabilities
00111 /// @subsection RA8875_Resolution Display Resolution
00112 /// There are two very common display resolutions that use the RA8875:
00113 /// * 480 x 272 pixels
00114 /// * 800 x 480 pixels
00115 ///
00116 /// @subsection RA8875_Layers Display Layers
00117 /// The RA8875 Controller, depending on the resolution and color depth, can support 
00118 /// multiple display layers.
00119 ///
00120 /// * 1 Layer - when the color depth is 16 bits per pixel
00121 /// * 2 Layers - when the color depth is 8 bits per pixel and the resolution is 480 x 272.
00122 ///
00123 ///
00124 ///
00125 /// @page Touch_Panel Touch Panel
00126 ///
00127 /// There is support for various touch panel interfaces.
00128 /// * @ref Resistive_Touch_Panel - native control for a resistive touch panel. 
00129 ///     There are a few steps to enable this interface.
00130 /// * @ref CapSense_FT5206 - FT5206 capacitive touch controller, integrated in 
00131 ///     several popular RA8875-based displays. See @ref Capacitive_Touch_Panel.
00132 /// * @ref CapSense_GSL1680 - GSL1680 capacitive touch controller, integrated in 
00133 ///     several popular RA8875-based displays. See @ref Capacitive_Touch_Panel.
00134 ///
00135 ///
00136 ///
00137 /// @page Hardwired_KeyPad Hardwired Keypad
00138 ///
00139 /// The RA8875 controller supports a hardwired matrix of keys, which can be used to
00140 /// easily monitor for up to 20 keys (4 x 5 matrix). It is quite flexible, so these
00141 /// could be a set of independent functions, or they could be wired as a simple 
00142 /// calculator or telephone style of keypad.
00143 ///
00144 /// Various parameters can be configured, such as the scan rate, using @ref RA8875::KeypadInit().
00145 /// The keypad has a default keypad mapping, but there is an API that permits
00146 /// installing a custom @ref RA8875::SetKeyMap().
00147 ///
00148 /// @page Resistive_Touch_Panel Resistive Touch Panel
00149 ///
00150 /// The RA8875 controller supports a native resistive touchscreen interface than can
00151 /// track a single touch-point. 
00152 ///
00153 /// If your display has this option, you can easily accept touch input, but it comes with
00154 /// some additional requirements - calibration being the primary concern.
00155 ///
00156 /// @section Touch_Panel_Enable Touch Panel Enable
00157 ///
00158 /// @ref RA8875::TouchPanelInit() has two forms - one fully automatic, and more controlled. 
00159 /// See the APIs for details.
00160 ///
00161 /// @section Touch_Panel_Calibration
00162 /// 
00163 /// The touch panel is not initially calibrated on startup. The application should 
00164 /// provide a means to activate the calibration process, and that should not require
00165 /// the touchscreen as it may not yet be usable. Alternately, a calibration matrix
00166 /// can be loaded from non-volatile and installed.
00167 ///
00168 /// @page Capacitive_Touch_Panel Capacitive Touch Panel
00169 ///
00170 /// Common to many of the commercially available display modules that use the RA8875 is
00171 /// an option for a capacitive sense touch screen [Cap Sense] There are two known Cap Sense
00172 /// controllers that this library can work with:
00173 ///
00174 /// * @ref CapSense_FT5206.
00175 /// * @ref CapSense_GSL1680.
00176 /// 
00177 /// @page CapSense_FT5206 Capacitive Sense - FT5206 Controller
00178 ///
00179 /// This is the more common controller. It supports up to 5 simultaneous touch point
00180 /// tracking.
00181 ///
00182 /// @page CapSense_GSL1680 Capacitive Sense - GSL1680 Controller
00183 ///
00184 /// This is the less common controller. It supports either 5 or 10 simultaneous touch point
00185 /// tracking, depending on the firmware installed in the controller.
00186 ///
00187 /// @page Example_Program Example Program
00188 ///
00189 /// This is just a small sample of what can be done, and what it can look like:
00190 /// @image html Example_Program.png "Example Program"
00191 ///
00192 /// @code
00193 /// // Small test program
00194 /// #include "mbed.h"       // Working: v146, not fully working: v147
00195 /// #include "RA8875.h"     // Working: v149
00196 /// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
00197 ///  
00198 /// int main()
00199 /// {
00200 ///     lcd.init(480,272,16,100);
00201 ///     lcd.printf("printing 3 x 2 = %d", 3*2);
00202 ///     lcd.circle(       400,25,  25,               BrightRed);
00203 ///     lcd.fillcircle(   400,25,  15,               RGB(128,255,128));
00204 ///     lcd.ellipse(      440,75,  35,20,            BrightBlue);
00205 ///     lcd.fillellipse(  440,75,  25,10,            Blue);
00206 ///     lcd.triangle(     440,100, 475,110, 450,125, Magenta);
00207 ///     lcd.filltriangle( 445,105, 467,111, 452,120, Cyan);
00208 ///     lcd.rect(         400,130, 475,155,          Brown);
00209 ///     lcd.fillrect(     405,135, 470,150,          Pink);
00210 ///     lcd.roundrect(    410,160, 475,190, 10,8,    Yellow);
00211 ///     lcd.fillroundrect(415,165, 470,185,  5,3,    Orange);
00212 ///     lcd.line(         430,200, 460,230,          RGB(0,255,0));
00213 ///     for (int i=0; i<=30; i+=5) 
00214 ///         lcd.pixel(435+i,200+i, White);
00215 /// }
00216 /// @endcode
00217 ///
00218 /// @page Wiring_Diagram Example Wiring Diagram
00219 ///
00220 /// This library was crafted around the 4-Wire SPI interface. This was the chosen 
00221 /// interface method in order to balance the requirements of the host micro IO with 
00222 /// the capability of this display. Alternatives include: 3-Wire SPI, I2C, 8-bit and
00223 /// 16-bit parallel.
00224 /// 
00225 /// @image html Example_Wiring.png "Example Wiring Diagram"
00226 ///
00227 /// @page Future_Plans Future Plans
00228 ///
00229 /// Following are some notions of future plans. This does not mean they will all be
00230 /// implemented, just consider them as things I'm thinking about. If you have a suggestion,
00231 /// please send it to me.
00232 ///
00233 /// - Change the return values for several functions. Most functions return @ref RA8875::RetCode_t,
00234 ///     but would benefit from returning a data type related to that function. For example,
00235 ///     @ref RA8875::SelectDrawingLayer() could return the current drawing layer even as a new
00236 ///     layer is defined. This can facilitate switching back and forth between configurations.
00237 ///     Examples:
00238 ///     - @ref RA8875::SelectDrawingLayer()
00239 ///     - @ref RA8875::SelectUserFont()
00240 ///     - @ref RA8875::SetBackgroundTransparencyColor()
00241 ///     - @ref RA8875::SetLayerMode()
00242 ///     - @ref RA8875::SetLayerTransparency()
00243 ///     - @ref RA8875::SetOrientation()
00244 ///     - @ref RA8875::SetTextCursor()
00245 ///     - @ref RA8875::SetTextCursorControl()
00246 ///     - @ref RA8875::SetTextFont()
00247 ///     - @ref RA8875::SetTextFontControl()
00248 ///     - @ref RA8875::SetTextFontSize()
00249 ///     - @ref RA8875::background()
00250 ///     - @ref RA8875::foreground()
00251 ///     - @ref RA8875::Backlight()
00252 ///     - @ref RA8875::window()
00253 ///     - @ref RA8875::WindowMax()
00254 ///
00255 /// - Change the title-case of the functions to be consistent. Because this was adapted 
00256 ///     from parts of several different libraries, it isn't very consistently titled.
00257 ///
00258 /// - Change names of some of the functions to be more consistent. Why are some Set* 
00259 ///     and others are Select*. The layer commands SetDrawingLayer and GetDrawingLayer do
00260 ///     not need 'Drawing' in them.
00261 ///
00262 /// - Improve the PrintScreen method. There are two functions - one that accepts a filename, 
00263 ///     and a second more experimental version that could pipe the image stream back to
00264 ///     a calling process. This could be used, for example, to send the image over a
00265 ///     network interface. The intended side effect is that there is then only a single
00266 ///     PrintScreen method with either an internal helper (for file system access) or
00267 ///     a callback for the user handled process.
00268 ///
00269 #ifndef RA8875_H
00270 #define RA8875_H
00271 #include <mbed.h>
00272 
00273 #include "RA8875_Regs.h"
00274 #include "RA8875_Touch_FT5206.h"
00275 #include "RA8875_Touch_GSL1680.h"
00276 #include "GraphicsDisplay.h"
00277 
00278 #define RA8875_DEFAULT_SPI_FREQ 5000000
00279 
00280 #ifndef MBED_ENCODE_VERSION
00281 #define MBED_ENCODE_VERSION(major, minor, patch) ((major)*10000 + (minor)*100 + (patch))
00282 #endif
00283 
00284 // Define this to enable code that monitors the performance of various
00285 // graphics commands.
00286 //#define PERF_METRICS
00287 
00288 // What better place for some test code than in here and the companion
00289 // .cpp file. See also the bottom of this file.
00290 //#define TESTENABLE
00291 
00292 /// @page PredefinedColors Predefined Colors
00293 ///
00294 /// Keep in mind that the color scheme shown here is unlikely to precisely match
00295 /// that on the actual display. The perceived color is additional affected by 
00296 /// other attributes, such as the backlight brightness.
00297 ///
00298 /// These are the predefined colors that are typically used where any @ref color_t 
00299 /// variable is applied.
00300 ///
00301 /// <blockquote>
00302 /// <table>
00303 /// <tr>
00304 /// <td bgcolor='#000000'>&nbsp;</td><td>@ref Black</td>
00305 /// <td bgcolor='#0000BB'>&nbsp;</td><td>@ref Blue</td>
00306 /// <td bgcolor='#00BB00'>&nbsp;</td><td>@ref Green</td>
00307 /// <td bgcolor='#00BBBB'>&nbsp;</td><td>@ref Cyan</td>
00308 /// </tr>
00309 /// <tr>
00310 /// <td bgcolor='#BB0000'>&nbsp;</td><td>@ref Red</td>
00311 /// <td bgcolor='#BB00BB'>&nbsp;</td><td>@ref Magenta</td>
00312 /// <td bgcolor='#3F3F3F'>&nbsp;</td><td>@ref Brown</td>
00313 /// <td bgcolor='#BBBBBB'>&nbsp;</td><td>@ref Gray</td>
00314 /// </tr>
00315 /// <tr>
00316 /// <td bgcolor='#555555'>&nbsp;</td><td>@ref Charcoal</td>
00317 /// <td bgcolor='#0000FF'>&nbsp;</td><td>@ref BrightBlue</td>
00318 /// <td bgcolor='#00FF00'>&nbsp;</td><td>@ref BrightGreen</td>
00319 /// <td bgcolor='#00FFFF'>&nbsp;</td><td>@ref BrightCyan</td>
00320 /// </tr>
00321 /// <tr>
00322 /// <td bgcolor='#FF5555'>&nbsp;</td><td>@ref Orange</td>
00323 /// <td bgcolor='#FF55FF'>&nbsp;</td><td>@ref Pink</td>
00324 /// <td bgcolor='#BBBB00'>&nbsp;</td><td>@ref Yellow</td>
00325 /// <td bgcolor='#FFFFFF'>&nbsp;</td><td>@ref White</td>
00326 /// </tr>
00327 /// <tr>
00328 /// <td bgcolor='#00003F'>&nbsp;</td><td>@ref DarkBlue </td>
00329 /// <td bgcolor='#003F00'>&nbsp;</td><td>@ref DarkGreen</td>
00330 /// <td bgcolor='#003F3F'>&nbsp;</td><td>@ref DarkCyan </td>
00331 /// <td bgcolor='#3F0000'>&nbsp;</td><td>@ref DarkRed  </td>
00332 /// </tr>
00333 /// <tr>
00334 /// <td bgcolor='#3F003F'>&nbsp;</td><td>@ref DarkMagenta</td>
00335 /// <td bgcolor='#3F3F00'>&nbsp;</td><td>@ref DarkBrown  </td>
00336 /// <td bgcolor='#3F3F3F'>&nbsp;</td><td>@ref DarkGray   </td>
00337 /// <td bgcolor='#FFFFFF'>&nbsp;</td><td>&nbsp;</td>
00338 /// </tr>
00339 /// </table>
00340 /// </blockquote>
00341 ///
00342 
00343 #define Black       (color_t)(RGB(0,0,0))
00344 #define Blue        (color_t)(RGB(0,0,187))
00345 #define Green       (color_t)(RGB(0,187,0))
00346 #define Cyan        (color_t)(RGB(0,187,187))
00347 #define Red         (color_t)(RGB(187,0,0))
00348 #define Magenta     (color_t)(RGB(187,0,187))
00349 #define Brown       (color_t)(RGB(63,63,0))
00350 #define Gray        (color_t)(RGB(187,187,187))
00351 #define Charcoal    (color_t)(RGB(85,85,85))
00352 #define BrightBlue  (color_t)(RGB(0,0,255))
00353 #define BrightGreen (color_t)(RGB(0,255,0))
00354 #define BrightCyan  (color_t)(RGB(0,255,255))
00355 #define BrightRed   (color_t)(RGB(255,0,0))
00356 #define Orange      (color_t)(RGB(255,85,85))
00357 #define Pink        (color_t)(RGB(255,85,255))
00358 #define Yellow      (color_t)(RGB(187,187,0))
00359 #define White       (color_t)(RGB(255,255,255))
00360 
00361 #define DarkBlue    (color_t)(RGB(0,0,63))
00362 #define DarkGreen   (color_t)(RGB(0,63,0))
00363 #define DarkCyan    (color_t)(RGB(0,63,63))
00364 #define DarkRed     (color_t)(RGB(63,0,0))
00365 #define DarkMagenta (color_t)(RGB(63,0,63))
00366 #define DarkBrown   (color_t)(RGB(63,63,0))
00367 #define DarkGray    (color_t)(RGB(63,63,63))
00368 
00369 #define min(a,b) ((a<b)?a:b)
00370 #define max(a,b) ((a>b)?a:b)
00371 
00372 
00373 //namespace SW_graphics
00374 //{
00375 
00376 class FPointerDummy;    // used by the callback methods.
00377 
00378 /// This is a graphics library for the Raio RA8875 Display Controller chip
00379 /// attached to a 4-wire SPI interface.
00380 ///
00381 /// It offers both primitive and high level APIs.
00382 ///
00383 /// Central to this API is a coordinate system, where the origin (0,0) is in
00384 /// the top-left corner of the display, and the width (x) extends positive to the
00385 /// right and the height (y) extends positive toward the bottom.
00386 ///
00387 /// @note As there are both graphics and text commands, one must take care to use
00388 /// the proper coordinate system for each. Some of the text APIs are in units
00389 /// of column and row, which is measured in character positions (and dependent
00390 /// on the font size), where other text APIs permit pixel level positioning.
00391 ///
00392 /// @code
00393 /// #include "RA8875.h"
00394 /// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
00395 ///
00396 /// int main()
00397 /// {
00398 ///     lcd.init();
00399 ///     lcd.printf("printing 3 x 2 = %d", 3*2);
00400 ///     lcd.circle(       400,25,  25,               BrightRed);
00401 ///     lcd.fillcircle(   400,25,  15,               RGB(128,255,128));
00402 ///     lcd.ellipse(      440,75,  35,20,            BrightBlue);
00403 ///     lcd.fillellipse(  440,75,  25,10,            Blue);
00404 ///     lcd.triangle(     440,100, 475,110, 450,125, Magenta);
00405 ///     lcd.filltriangle( 445,105, 467,111, 452,120, Cyan);
00406 ///     lcd.rect(         400,130, 475,155,          Brown);
00407 ///     lcd.fillrect(     405,135, 470,150,          Pink);
00408 ///     lcd.roundrect(    410,160, 475,190, 10,8,    Yellow);
00409 ///     lcd.fillroundrect(415,165, 470,185,  5,3,    Orange);
00410 ///     lcd.line(         430,200, 460,230,          RGB(0,255,0));
00411 ///     for (int i=0; i<=30; i+=5) 
00412 ///         lcd.pixel(435+i,200+i, White);
00413 /// }
00414 /// @endcode
00415 ///
00416 /// @todo Add Scroll support for text.
00417 /// @todo Add Hardware reset signal - but testing to date indicates it is not needed.
00418 /// @todo Add high level objects - x-y graph, meter, others... but these will
00419 ///     probably be best served in another class, since they may not
00420 ///     be needed for many uses.
00421 /// 
00422 class RA8875 : public GraphicsDisplay
00423 {
00424 public:   
00425     /// cursor type argument for @ref SetTextCursorControl()
00426     typedef enum
00427     {
00428         NOCURSOR,   ///< cursor is hidden
00429         IBEAM,      ///< I Beam '|' cursor
00430         UNDER,      ///< Underscore '_' cursor
00431         BLOCK       ///< Block cursor
00432     } cursor_t;
00433 
00434     /// font type selection argument for @ref SetTextFont()
00435     typedef enum
00436     {
00437         ISO8859_1,      ///< ISO8859-1 font
00438         ISO8859_2,      ///< ISO8859-2 font
00439         ISO8859_3,      ///< ISO8859-3 font
00440         ISO8859_4       ///< ISO8859-4 font
00441     } font_t;
00442     
00443     /// display orientation argument for @ref SetOrientation()
00444     /// with landscape mode as the normal (0 degree) orientation.
00445     typedef enum
00446     {
00447         normal,         ///< normal (landscape) orientation
00448         rotate_0 = normal,  ///< alternate to 'normal'
00449         rotate_90,      ///< rotated clockwise 90 degree
00450         rotate_180,     ///< rotated (clockwise) 180 degree
00451         rotate_270,     ///< rotated clockwise 270 degree
00452     } orientation_t;
00453     
00454     /// alignment control argument for @ref SetTextFontControl()
00455     typedef enum
00456     {
00457         align_none,     ///< align - none
00458         align_full      ///< align - full
00459     } alignment_t;    
00460     
00461     /// Font Horizontal Scale factor - 1, 2, 3 4 for @ref SetTextFontSize(), @ref GetTextFontSize()
00462     typedef int HorizontalScale;
00463     
00464     /// Font Vertical Scale factor - 1, 2, 3, 4 for @ref SetTextFontSize(), @ref GetTextFontSize()
00465     typedef int VerticalScale;
00466 
00467     /// Clear screen region option for @ref clsw()
00468     typedef enum
00469     {
00470         FULLWINDOW,     ///< Full screen
00471         ACTIVEWINDOW    ///< active window/region
00472     } Region_t;
00473 
00474     /// Layer Display Mode argument for @ref SetLayerMode, @ref GetLayerMode
00475     typedef enum
00476     {
00477         ShowLayer0,         ///< Only layer 0 is visible, layer 1 is hidden (default)
00478         ShowLayer1,         ///< Only layer 1 is visible, layer 0 is hidden
00479         LightenOverlay,     ///< Lighten-overlay mode
00480         TransparentMode,    ///< Transparent mode
00481         BooleanOR,          ///< Boolean OR mode
00482         BooleanAND,         ///< Boolean AND mode
00483         FloatingWindow      ///< Floating Window mode
00484     } LayerMode_T;
00485     
00486     /// Touch Panel modes
00487     typedef enum
00488     {
00489         TP_Auto,               ///< Auto touch detection mode
00490         TP_Manual,             ///< Manual touch detection mode
00491     } tpmode_t;
00492 
00493     /// PrintScreen callback commands for the user code @ref PrintCallback_T()
00494     typedef enum
00495     {
00496         OPEN,       ///< command to open the file. cast uint32_t * to the buffer to get the total size to be written.
00497         WRITE,      ///< command to write some data, buffer points to the data and the size is in bytes.
00498         CLOSE,      ///< command to close the file
00499     } filecmd_t;
00500 
00501     /// print screen callback
00502     ///
00503     /// The special form of the print screen will pass one blob at a time 
00504     /// to the callback. There are basic commands declaring that the stream
00505     /// can be opened, a block written, and the stream closed. There is
00506     /// also a command to communicate the total size being delivered.
00507     ///
00508     /// If the idle callback is registered, it will be activated passing
00509     /// a parameter indicating the percent complete, which may be of value.
00510     ///
00511     /// @code
00512     /// lcd.PrintScreen(x,y,w,h,callback);
00513     /// ... 
00514     /// void callback(filecmd_t cmd, uint8_t * buffer, uint16_t size) {
00515     ///     switch(cmd) {
00516     ///         case OPEN:
00517     ///             pc.printf("About to write %u bytes\r\n", *(uint32_t *)buffer);
00518     ///             fh = fopen("file.bmp", "w+b");
00519     ///             break;
00520     ///         case WRITE:
00521     ///             fwrite(buffer, size, fh);
00522     ///             break;
00523     ///         case CLOSE:
00524     ///             fclose(fh);
00525     ///             break;
00526     ///         default:
00527     ///             pc.printf("Unexpected callback %d\r\n", cmd);
00528     ///             break;
00529     ///     }
00530     /// }
00531     /// @endcode
00532     ///
00533     /// @param cmd is the command to execute. See @ref filecmd_t.
00534     /// @param buffer is a pointer to the buffer being passed.
00535     /// @param size is the number of bytes in the buffer.
00536     /// @returns @ref RetCode_t value.
00537     ///
00538     typedef RetCode_t (* PrintCallback_T)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
00539     
00540     /// Idle reason provided in the Idle Callback @ref IdleCallback_T()
00541     typedef enum {
00542         unknown,            ///< reason has not been assigned (this should not happen)
00543         status_wait,        ///< driver is polling the status register while busy
00544         command_wait,       ///< driver is polling the command register while busy
00545         getc_wait,          ///< user has called the getc function
00546         touch_wait,         ///< user has called the touch function
00547         touchcal_wait,      ///< driver is performing a touch calibration
00548         progress,           ///< communicates progress
00549     } IdleReason_T;
00550     
00551     /// Idle Callback 
00552     ///
00553     /// This defines the interface for an idle callback. That is, when the 
00554     /// driver is held up, pending some event, it can call a previously registered
00555     /// idle function. This could be most useful for servicing a watchdog.
00556     ///
00557     /// The user code, which is notified via this API, can force the idle
00558     /// to abort, by returning the external_abort value back to the driver.
00559     /// It is important to note that the abort could leave the driver in
00560     /// an undesireable state, so this should be used with care.
00561     ///
00562     /// @note Should it be called the BusyCallback? It is true, that it will
00563     ///     call this function when the RA8875 is busy, but this is also
00564     ///     when the CPU is largely idle.
00565     ///
00566     /// @code
00567     /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason, uint16_t param)
00568     /// {
00569     ///     idleFlasher = !idleFlasher;
00570     ///     if (it_has_been_too_long())
00571     ///         return external_abort;
00572     ///     else
00573     ///         return noerror;
00574     /// }
00575     /// @endcode
00576     ///
00577     /// @param reason informs the callback why it is idle.
00578     /// @param param is a 2nd parameter, which is used for certain reason codes
00579     ///        for 'progress' reason code, param ranges from 0 to 100 (percent)
00580     /// @returns @ref RetCode_t value.
00581     ///
00582     typedef RetCode_t (* IdleCallback_T)(IdleReason_T reason, uint16_t param = 0);
00583 
00584     /// Basic constructor for a display based on the RAiO RA8875 
00585     /// display controller, which can be used with no touchscreen,
00586     /// or the RA8875 managed resistive touchscreen.
00587     ///
00588     /// This constructor differs from the alternate by supportting
00589     /// either No Touch Screen, or the RA8875 built-in resistive
00590     /// touch screen. If the application requires the use of the
00591     /// capacitive touchscreen, the alternate constructor must 
00592     /// be used.
00593     ///
00594     /// This configures the registers and calls the @ref init method.
00595     ///
00596     /// @code
00597     /// #include "RA8875.h"
00598     /// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
00599     ///
00600     /// int main()
00601     /// {
00602     ///     lcd.init();     // defaults for 480x272x16 at low brightness
00603     ///     lcd.printf("printing 3 x 2 = %d", 3*2);
00604     ///     lcd.circle(400,25, 25, BrightRed);
00605     /// }
00606     /// @endcode
00607     ///
00608     /// @param[in] mosi is the SPI master out slave in pin on the mbed.
00609     /// @param[in] miso is the SPI master in slave out pin on the mbed.
00610     /// @param[in] sclk is the SPI shift clock pin on the mbed.
00611     /// @param[in] csel is the DigitalOut pin on the mbed to use as the
00612     ///         active low chip select for the display controller.
00613     /// @param[in] reset is the DigitalOut pin on the mbed to use as the 
00614     ///         active low reset input on the display controller - 
00615     ///         but this is not currently used.
00616     /// @param[in] name is a text name for this object, which will permit
00617     ///         capturing stdout to puts() and printf() directly to it.
00618     ///
00619     RA8875(PinName mosi, PinName miso, PinName sclk, PinName csel, PinName reset, 
00620         const char * name = "lcd");
00621     
00622     
00623     /// Constructor for a display based on the RAiO RA8875 display controller 
00624     /// (using the FT5206 Capacitive TouchScreen Controller)
00625     ///
00626     /// @code
00627     /// #include "RA8875.h"
00628     /// RA8875 lcd(p5, p6, p7, p12, NC, p9,p10,p13, "tft");
00629     /// 
00630     /// int main()
00631     /// {
00632     ///     lcd.init();
00633     ///     lcd.printf("printing 3 x 2 = %d", 3*2);
00634     ///     lcd.circle(400,25, 25, BrightRed);
00635     ///     TouchCode_t tp = lcd.TouchPanelReadable();
00636     ///     if (tp == touch)
00637     ///         ...
00638     /// }
00639     /// @endcode
00640     ///
00641     /// @param[in] mosi is the SPI master out slave in pin on the mbed.
00642     /// @param[in] miso is the SPI master in slave out pin on the mbed.
00643     /// @param[in] sclk is the SPI shift clock pin on the mbed.
00644     /// @param[in] csel is the DigitalOut pin on the mbed to use as the
00645     ///         active low chip select for the display controller.
00646     /// @param[in] reset is the DigitalOut pin on the mbed to use as the 
00647     ///         active low reset input on the display controller - 
00648     ///         but this is not currently used.
00649     /// @param[in] sda is the I2C Serial Data pin you are wiring to the FT5206.
00650     /// @param[in] scl is the I2C Serial Clock pin you are wiring to the FT5206.
00651     /// @param[in] irq is the Interrupt Request pin you are wiring to the FT5206.
00652     /// @param[in] name is a text name for this object, which will permit
00653     ///         capturing stdout to puts() and printf() directly to it.
00654     ///
00655     RA8875(PinName mosi, PinName miso, PinName sclk, PinName csel, PinName reset, 
00656         PinName sda, PinName scl, PinName irq, const char * name = "lcd");
00657  
00658     
00659     /// Constructor for a display based on the RAiO RA8875 display controller 
00660     /// (using the GSL1680 Capacitive TouchScreen Controller)
00661     ///
00662     /// @code
00663     /// #include "RA8875.h"
00664     /// RA8875 lcd(p5, p6, p7, p12, NC, p9,p10,p13,p14, "tft");
00665     /// 
00666     /// int main()
00667     /// {
00668     ///     lcd.init();
00669     ///     lcd.printf("printing 3 x 2 = %d", 3*2);
00670     ///     lcd.circle(400,25, 25, BrightRed);
00671     ///     TouchCode_t tp = lcd.TouchPanelReadable();
00672     ///     if (tp == touch)
00673     ///         ...
00674     /// }
00675     /// @endcode
00676     ///
00677     /// @param[in] mosi is the SPI master out slave in pin on the mbed.
00678     /// @param[in] miso is the SPI master in slave out pin on the mbed.
00679     /// @param[in] sclk is the SPI shift clock pin on the mbed.
00680     /// @param[in] csel is the DigitalOut pin on the mbed to use as the
00681     ///         active low chip select for the display controller.
00682     /// @param[in] reset is the DigitalOut pin on the mbed to use as the 
00683     ///         active low reset input on the display controller - 
00684     ///         but this is not currently used.
00685     /// @param[in] sda is the I2C Serial Data pin you are wiring to the GSL1680.
00686     /// @param[in] scl is the I2C Serial Clock pin you are wiring to the GSL1680.
00687     /// @param[in] wake is the wake control pin you are wiring to the GSL1680.
00688     /// @param[in] irq is the Interrupt Request pin you are wiring to the GSL1680.
00689     /// @param[in] name is a text name for this object, which will permit
00690     ///         capturing stdout to puts() and printf() directly to it.
00691     ///
00692     RA8875(PinName mosi, PinName miso, PinName sclk, PinName csel, PinName reset, 
00693         PinName sda, PinName scl, PinName wake, PinName irq, const char * name = "lcd");
00694  
00695     
00696     // Destructor doesn't have much to do as this would typically be created
00697     // at startup, and not at runtime.
00698     //~RA8875();
00699     
00700     /// Initialize the driver.
00701     ///
00702     /// The RA8875 can control typical displays from the 480x272 to 800x480, and it supports 8 or 16-bit color. 
00703     /// It also supports 2 graphics layers, but it cannot support 2 layers at the maximum color depth and 
00704     /// screen size. When configured under 480x400, it will support both 16-bit color depth and 2 drawing layers. 
00705     /// Above 480x400 it support either 16-bit color, or 2 layers, but not both.
00706     ///
00707     /// Typical of the displays that are readily purchased, you will find 480x272 and 800x480 resolutions.
00708     ///
00709     /// @param[in] width in pixels to configure the display for. This parameter is optional
00710     ///             and the default is 480.
00711     /// @param[in] height in pixels to configure the display for. This parameter is optional
00712     ///             and the default is 272.
00713     /// @param[in] color_bpp can be either 8 or 16, but must be consistent
00714     ///             with the width and height parameters. This parameter is optional
00715     ///             and the default is 16.
00716     /// @param[in] poweron defines if the display should be initialized into the power-on or off state.
00717     ///            If power is non-zero(on), the backlight is set to this value. This parameter is optional
00718     ///             and the default is 40 (on at a low brightness level because many users power
00719     ///             the module from their PC USB port and it often cannot support the curent
00720     ///             required for full brightness). See @ref Power.
00721     /// @param[in] keypadon defines if the keypad support should be enabled. This parameter is optional
00722     ///             and the default is true (enabled). See @ref KeypadInit.
00723     /// @param[in] touchscreeenon defines if the touchscreen support should be enabled. 
00724     ///             This parameter is optional and the default is true (enabled). See @ref TouchPanelInit.
00725     ///             - If the constructor was called with support for the capacitive driver, this 
00726     ///             parameter causes the driver to initialize.
00727     ///             - If the constructor was called without support for the capacitive driver, this
00728     ///             parameter is used to enable and initialize the resistive touchscreen driver.
00729     /// @returns @ref RetCode_t value.
00730     ///
00731     RetCode_t init(int width = 480, int height = 272, int color_bpp = 16, 
00732         uint8_t poweron = 40, bool keypadon = true, bool touchscreeenon = true);
00733 
00734 
00735     /// Get a pointer to the text string representing the RetCode_t
00736     ///
00737     /// This method returns a pointer to a text string that matches the
00738     /// code. See @ref RetCode_t.
00739     ///
00740     /// @param[in] code is the return value from RetCode_t to look up.
00741     /// @returns a pointer to the text message representing code. If code
00742     ///     is not a valid value, then it returns the text for bad_parameter;
00743     ///
00744     const char * GetErrorMessage(RetCode_t code);
00745     
00746     
00747     /// Select the drawing layer for subsequent commands.
00748     ///
00749     /// If the screen configuration is 480 x 272, or if it is 800 x 480 
00750     /// and 8-bit color, the the display supports two layers, which can 
00751     /// be independently drawn on and shown. Additionally, complex
00752     /// operations involving both layers are permitted.
00753     ///
00754     /// @attention If the current display configuration does not support
00755     ///     multiple layers, then layer 0 will be selected.
00756     ///
00757     /// @code
00758     ///     //lcd.SetLayerMode(OnlyLayer0); // default is layer 0
00759     ///     lcd.rect(400,130, 475,155,Brown);
00760     ///     lcd.SelectDrawingLayer(1);
00761     ///     lcd.circle(400,25, 25, BrightRed);
00762     ///     wait(1);
00763     ///     lcd.SetLayerMode(ShowLayer1);
00764     /// @endcode
00765     ///
00766     /// @attention The user manual refers to Layer 1 and Layer 2, however the
00767     ///     actual register values are value 0 and 1. This API as well as
00768     ///     others that reference the layers use the values 0 and 1 for
00769     ///     cleaner iteration in the code.
00770     ///
00771     /// @param[in] layer is 0 or 1 to select the layer for subsequent 
00772     ///     commands.
00773     /// @param[out] prevLayer is an optiona pointer to where the previous layer
00774     ///     will be written, making it a little easer to restore layers.
00775     ///     Writes 0 or 1 when the pointer is not NULL.
00776     /// @returns @ref RetCode_t value.
00777     ///
00778     virtual RetCode_t SelectDrawingLayer(uint16_t layer, uint16_t * prevLayer = NULL);
00779  
00780     
00781     /// Get the currently active drawing layer.
00782     ///
00783     /// This returns a value, 0 or 1, based on the screen configuration
00784     /// and the currently active drawing layer.
00785     ///
00786     /// @code
00787     ///     uint16_t prevLayer = lcd.GetDrawingLayer();
00788     ///     lcd.SelectDrawingLayer(x);
00789     ///     lcd.circle(400,25, 25, BrightRed);
00790     ///     lcd.SelectDrawingLayer(prevLayer);
00791     /// @endcode
00792     ///
00793     /// @attention The user manual refers to Layer 1 and Layer 2, however the
00794     ///     actual register values are value 0 and 1. This API as well as
00795     ///     others that reference the layers use the values 0 and 1 for
00796     ///     cleaner iteration in the code.
00797     ///
00798     /// @returns the current drawing layer; 0 or 1.
00799     /// 
00800     virtual uint16_t GetDrawingLayer(void);
00801  
00802     
00803     /// Set the Layer presentation mode.
00804     ///
00805     /// This sets the presentation mode for layers, and permits showing
00806     /// a single layer, or applying a mode where the two layers
00807     /// are combined using one of the hardware methods.
00808     ///
00809     /// Refer to the RA8875 data sheet for full details.
00810     ///
00811     /// @code
00812     ///     //lcd.SetLayerMode(OnlyLayer0); // default is layer 0
00813     ///     lcd.rect(400,130, 475,155,Brown);
00814     ///     lcd.SelectDrawingLayer(1);
00815     ///     lcd.circle(400,25, 25, BrightRed);
00816     ///     wait(1);
00817     ///     lcd.SetLayerMode(ShowLayer1);
00818     /// @endcode
00819     ///
00820     /// @param[in] mode sets the mode in the Layer Transparency Register.
00821     /// @returns @ref RetCode_t value.
00822     ///
00823     RetCode_t SetLayerMode(LayerMode_T mode);
00824  
00825     
00826     /// Get the Layer presentation mode.
00827     ///
00828     /// This gets the current layer mode. See @ref LayerMode_T.
00829     ///
00830     /// @returns layer mode.
00831     ///
00832     LayerMode_T GetLayerMode(void);
00833  
00834     
00835     /// Set the layer transparency for each layer.
00836     ///
00837     /// Set the transparency, where the range of values is
00838     /// from zero (fully visible) to eight (fully transparent).
00839     /// The input value is automatically limited to this range.
00840     ///
00841     /// @code
00842     ///     // draw something on each layer, then step-fade across
00843     ///     display.SetLayerMode(RA8875::TransparentMode);
00844     ///     for (i=0; i<=8; i++) {
00845     ///         display.SetLayerTransparency(i, 8-i);
00846     ///         wait_ms(200);
00847     ///     }
00848     /// @endcode
00849     ///
00850     /// @param[in] layer1 sets the layer 1 transparency.
00851     /// @param[in] layer2 sets the layer 2 transparency.
00852     /// @returns @ref RetCode_t value.
00853     /// 
00854     RetCode_t SetLayerTransparency(uint8_t layer1, uint8_t layer2);
00855  
00856     
00857     /// Set the background color register used for transparency.
00858     ///
00859     /// This command sets the background color registers that are used
00860     /// in the transparent color operations involving the layers.
00861     /// 
00862     /// @param[in] color is optional and expressed in 16-bit format. If not
00863     ///     supplied, a default of Black is used.
00864     /// @returns @ref RetCode_t value.
00865     ///
00866     RetCode_t SetBackgroundTransparencyColor(color_t color = RGB(0,0,0));
00867  
00868  
00869     /// Get the background color value used for transparency.
00870     ///
00871     /// This command reads the background color registers that define
00872     /// the transparency color for operations involving layers.
00873     ///
00874     /// @returns the color.
00875     ///
00876     color_t GetBackgroundTransparencyColor(void);
00877  
00878  
00879     /// Initialize theTouch Panel controller with default values 
00880     ///
00881     /// This activates the simplified touch panel init, which may work for
00882     /// most uses. The alternate API is available if fine-grained control
00883     /// of the numerous settings of the resistive panel is needed.
00884     ///
00885     /// Additionally, for an even simpler interface for most RESISTIVE
00886     /// touch use cases, the init() method can perform the calibration.
00887     ///
00888     /// @returns @ref RetCode_t value.
00889     ///
00890     RetCode_t TouchPanelInit(void);
00891         
00892  
00893     /// Initialize the Touch Panel controller with detailed settings.
00894     ///
00895     /// This is the detailed touch panel init, which provides the ability
00896     /// to set nearly every option.
00897     ///
00898     /// @note If the capacitive touch panel was constructed, this behaves
00899     ///     the same as the simplified version.
00900     ///
00901     /// @param[in]  bTpEnable           Touch Panel enable/disable control:
00902     ///                                 - TP_ENABLE: enable the touch panel
00903     ///                                 - TP_DISABLE: disable the touch panel
00904     /// @param[in]  bTpAutoManual       Touch Panel operating mode:
00905     ///                                 - TP_MODE_AUTO: automatic capture
00906     ///                                 - TP_MODE_MANUAL: manual capture
00907     /// @param[in]  bTpDebounce         Debounce circuit enable for touch panel interrupt:
00908     ///                                 - TP_DEBOUNCE_OFF: disable the debounce circuit
00909     ///                                 - TP_DEBOUNCE_ON: enable the debounce circuit     
00910     /// @param[in]  bTpManualMode       When Manual Mode is selected, this sets the mode:
00911     ///                                 - TP_MANUAL_IDLE: touch panel is idle   
00912     ///                                 - TP_MANUAL_WAIT: wait for touch panel event   
00913     ///                                 - TP_MANUAL_LATCH_X: latch X data  
00914     ///                                 - TP_MANUAL_LATCH_Y: latch Y data   
00915     /// @param[in]  bTpAdcClkDiv        Sets the ADC clock as a fraction of the System CLK:
00916     ///                                 - TP_ADC_CLKDIV_1: Use CLK   
00917     ///                                 - TP_ADC_CLKDIV_2: Use CLK/2   
00918     ///                                 - TP_ADC_CLKDIV_4: Use CLK/4   
00919     ///                                 - TP_ADC_CLKDIV_8: Use CLK/8   
00920     ///                                 - TP_ADC_CLKDIV_16: Use CLK/16   
00921     ///                                 - TP_ADC_CLKDIV_32: Use CLK/32   
00922     ///                                 - TP_ADC_CLKDIV_64: Use CLK/64   
00923     ///                                 - TP_ADC_CLKDIV_128: Use CLK/128   
00924     /// @param[in]  bTpAdcSampleTime    Touch Panel sample time delay before ADC data is ready:
00925     ///                                 - TP_ADC_SAMPLE_512_CLKS: Wait 512 system clocks   
00926     ///                                 - TP_ADC_SAMPLE_1024_CLKS: Wait 1024 system clocks   
00927     ///                                 - TP_ADC_SAMPLE_2048_CLKS: Wait 2048 system clocks   
00928     ///                                 - TP_ADC_SAMPLE_4096_CLKS: Wait 4096 system clocks   
00929     ///                                 - TP_ADC_SAMPLE_8192_CLKS: Wait 8192 system clocks   
00930     ///                                 - TP_ADC_SAMPLE_16384_CLKS: Wait 16384 system clocks   
00931     ///                                 - TP_ADC_SAMPLE_32768_CLKS: Wait 32768 system clocks   
00932     ///                                 - TP_ADC_SAMPLE_65536_CLKS: Wait 65536 system clocks
00933     /// @returns @ref RetCode_t value.   
00934     ///
00935     RetCode_t TouchPanelInit(uint8_t bTpEnable, uint8_t bTpAutoManual, uint8_t bTpDebounce, 
00936         uint8_t bTpManualMode, uint8_t bTpAdcClkDiv, uint8_t bTpAdcSampleTime);
00937     
00938     
00939     /// Get the screen calibrated point of touch.
00940     ///
00941     /// This method determines if there is a touch and if so it will provide
00942     /// the screen-relative touch coordinates. This method can be used in
00943     /// a manner similar to Serial.readable(), to determine if there was a 
00944     /// touch and indicate that - but not care about the coordinates. Alternately,
00945     /// if a valid pointer to a point_t is provided, then if a touch is detected
00946     /// the point_t will be populated with data. 
00947     ///
00948     /// @code
00949     ///     Timer t;
00950     ///     t.start();
00951     ///     do {
00952     ///        point_t point = {0, 0};
00953     ///        if (display.TouchPanelReadable(&point)) {
00954     ///            display.pixel(point, Red);
00955     ///        }
00956     ///    } while (t.read_ms() < 30000);
00957     /// @endcode
00958     ///
00959     /// @param[out] TouchPoint is a pointer to a point_t, which is set as the touch point, 
00960     ///             if a touch is registered.
00961     /// @returns a value indicating the state of the touch,
00962     ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
00963     ///         - no_touch: no touch is detected, touch coordinates are not returned.
00964     ///         - touch:    touch is detected, touch coordinates are returned.
00965     ///         - held:     held after touch, touch coordinates are returned.
00966     ///         - release:  indicates a release, touch coordinates are returned.
00967     ///
00968     TouchCode_t TouchPanelReadable(point_t * TouchPoint = NULL);
00969 
00970 
00971     /// Get the reported touch gesture, if any.
00972     /// 
00973     /// If it could detect a gesture, it will return a value based on
00974     /// the interpreted gesture.
00975     ///
00976     /// Valid gesture values are:
00977     /// @li 0x00 No gesture
00978     /// @li 0x48 Zoom in
00979     /// @li 0x49 Zoom out
00980     ///
00981     /// The following gestures are defined in the FT5206 specification, but
00982     /// do not appear to work.
00983     /// @li 0x10 Move up
00984     /// @li 0x14 Move left
00985     /// @li 0x18 Move down
00986     /// @li 0x1C Move right
00987     ///
00988     /// @returns gesture information.
00989     ///
00990     uint8_t TouchGesture(void) { return gesture; }
00991     
00992 
00993     /// Get the count of registered touches.
00994     ///
00995     /// @returns count of touch points to communicate; 0 to 5.
00996     ///
00997     int TouchCount(void) { return numberOfTouchPoints; }
00998 
00999     
01000     /// Get the count of possible touch channels.
01001     ///
01002     /// @returns count of touch channels supported by the hardware.
01003     ///
01004     int TouchChannels(void);
01005 
01006     
01007     /// Get the Touch ID value for a specified touch channel.
01008     ///
01009     /// Touch ID is a tracking number based on the order of the touch
01010     /// detections. The first touch is ID 0, the next is ID 1, and 
01011     /// so on. If the first touch is lifted (no touch), the touch count
01012     /// decrements, and the remaining touch is communicated on
01013     /// touch channel zero, even as the Touch ID remains as originally
01014     /// reported (1 in this example). In this way, it is easy to track 
01015     /// a specific touch.
01016     ///
01017     /// It is possible to query the data for a channel that is not
01018     /// presently reported as touched.
01019     ///
01020     /// @param[in] channel is the touch channel, from 0 to 4, or 0 to TouchChannels()-1
01021     ///     It defaults to 0, in case the user is not interested in multi-touch.
01022     /// @returns the touch ID, or 15 if you get the ID for an untouched channel.
01023     /// @returns 0 if an invalid channel is queried.
01024     ///
01025     uint8_t TouchID(uint8_t channel = 0);
01026     
01027     /// Get the Touch Code for a touch channel.
01028     ///
01029     /// It is possible to query the data for a channel that is not
01030     /// presently reported as touched.
01031     ///
01032     /// @param[in] channel is the touch channel, from 0 to 4, or 0 to TouchChannels()-1
01033     ///     It defaults to 0, in case the user is not interested in multi-touch.
01034     /// @returns the touch code (@ref TouchCode_t).
01035     /// @returns channel 0 information if an invalid channel is queried.
01036     ///
01037     TouchCode_t TouchCode(uint8_t channel = 0);
01038 
01039 
01040     /// Get the coordinates for a touch channel.
01041     ///
01042     /// This returns the (X,Y) coordinates for a touch channel.
01043     ///
01044     ///
01045     /// It is possible to query the data for a channel that is not
01046     /// presently reported as touched.
01047     ///
01048     /// @param[in] channel is an optional touch channel, from 0 to 4, or 0 to TouchChannels()-1.
01049     ///     It defaults to 0, in case the user is not interested in multi-touch.
01050     /// @returns the coordinates as a point_t structure.
01051     /// @returns channel 0 information if an invalid channel is queried.
01052     ///
01053     point_t TouchCoordinates(uint8_t channel = 0);
01054     
01055 
01056     /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
01057     ///
01058     /// This method reads the touch controller, which has a 10-bit range for each the
01059     /// x and the y axis.
01060     ///
01061     /// @note The returned values are not in display (pixel) units but are in analog to
01062     ///     digital converter units.
01063     /// 
01064     /// @note This API is usually not needed and is likely to be deprecated. 
01065     ///     See @ref TouchPanelComputeCalibration. 
01066     ///     See @ref TouchPanelReadable.
01067     /// 
01068     /// @param[out] x is the x scale a/d value.
01069     /// @param[out] y is the y scale a/d value.
01070     /// @returns a value indicating the state of the touch,
01071     ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
01072     ///         - no_touch: no touch is detected, touch coordinates are not returned.
01073     ///         - touch:    touch is detected, touch coordinates are returned.
01074     ///         - held:     held after touch, touch coordinates are returned.
01075     ///         - release:  indicates a release, touch coordinates are returned.
01076     ///
01077     TouchCode_t TouchPanelA2DFiltered(int *x, int *y);
01078 
01079 
01080     /// Poll the TouchPanel and on a touch event return the a to d raw x, y coordinates.
01081     ///
01082     /// This method reads the touch controller, which has a 10-bit range for each the
01083     /// x and the y axis. A number of samples of the raw data are taken, filtered,
01084     /// and the results are returned. 
01085     ///
01086     /// @note The returned values are not in display (pixel) units but are in analog to
01087     ///     digital converter units.
01088     /// 
01089     /// @note This API is usually not needed and is likely to be deprecated. 
01090     ///     See @ref TouchPanelComputeCalibration. 
01091     ///     See @ref TouchPanelReadable.
01092     /// 
01093     /// @param[out] x is the x scale a/d value.
01094     /// @param[out] y is the y scale a/d value.
01095     /// @returns a value indicating the state of the touch,
01096     ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
01097     ///         - no_touch: no touch is detected, touch coordinates are not returned.
01098     ///         - touch:    touch is detected, touch coordinates are returned.
01099     ///         - held:     held after touch, touch coordinates are returned.
01100     ///         - release:  indicates a release, touch coordinates are returned.
01101     ///
01102     TouchCode_t TouchPanelA2DRaw(int *x, int *y);
01103 
01104     
01105     /// Wait for a touch panel touch and return it.
01106     /// 
01107     /// This method is similar to Serial.getc() in that it will wait for a touch
01108     /// and then return. In order to extract the coordinates of the touch, a
01109     /// valid pointer to a point_t must be provided.
01110     ///
01111     /// @note There is no timeout on this function, so its use is not recommended.
01112     ///
01113     /// @code
01114     ///     Timer t;
01115     ///     t.start();
01116     ///     do {
01117     ///        point_t point = {0, 0};
01118     ///        display.TouchPanelGet(&point);   // hangs here until touch
01119     ///        display.pixel(point, Red);
01120     ///    } while (t.read_ms() < 30000);
01121     /// @endcode
01122     ///
01123     /// @param[out] TouchPoint is the touch point, if a touch is registered.
01124     /// @returns a value indicating the state of the touch,
01125     ///         - no_cal:   no calibration matrix is available, touch coordinates are not returned.
01126     ///         - no_touch: no touch is detected, touch coordinates are not returned.
01127     ///         - touch:    touch is detected, touch coordinates are returned.
01128     ///         - held:     held after touch, touch coordinates are returned.
01129     ///         - release:  indicates a release, touch coordinates are returned.
01130     ///
01131     TouchCode_t TouchPanelGet(point_t * TouchPoint);
01132 
01133 
01134     /// Configuration Option for the Resistive Touch Panel Calibration.
01135     ///
01136     /// This method is only useful for the resistive touchscreen.
01137     ///
01138     /// Also, this method is optional - the user can take all of the responsibility
01139     /// in their code, or for simplicity sake, this API can be used prior
01140     /// to the init method.
01141     ///
01142     /// @code
01143     ///     RA8875 lcd(p5, p6, p7, p12, NC);
01144     ///     ...
01145     ///     // Be sure you previously mounted the "/sd" file system to put the cal there.
01146     ///     lcd.ResTouchPanelCfg("/sd/tpcal.cfg", "Touch '+' to calibrate the touch panel");
01147     ///
01148     ///     // Only if the touch panel is enabled, AND is configured as the resistive 
01149     ///     // panel will the prior command be useful.
01150     ///     lcd.init(LCD_W,LCD_H,LCD_C,40, false, true);
01151     ///
01152     /// @endcode
01153     ///
01154     /// @param[in] tpFQFN is a pointer to a fully qualified read-write accessible
01155     ///     filename where the calibration is held.
01156     /// @param[in] tpCalMessage is an optional pointer to a message shown to the
01157     ///     user in the calibration process. 
01158     ///     - If this parameter is not included, a default message will be shown.
01159     ///     - If this parameter points to a NULL string, no message is shown.
01160     ///     - If this parameter points to a non-NULL string, that string will be shown.
01161     ///
01162     void ResTouchPanelCfg(const char * tpFQFN = NULL, const char * tpCalMessage = NULL);
01163 
01164 
01165     /// Calibrate the touch panel.
01166     ///
01167     /// This method accepts two lists - one list is target points in ,
01168     /// display coordinates and the other is a lit of raw touch coordinate 
01169     /// values. It generates a calibration matrix for later use. This
01170     /// matrix is also accessible to the calling API, which may store
01171     /// the matrix in persistent memory and then install the calibration
01172     /// matrix on the next power cycle. By doing so, it can avoid the
01173     /// need to calibrate on every power cycle.
01174     ///
01175     /// @note The methods "TouchPanelComputeCalibration", "TouchPanelReadable", and
01176     ///     indirectly the "TouchPanelSetMatrix" methods are all derived
01177     ///     from a program by Carlos E. Vidales. See the copyright note
01178     ///     for further details. See also the article
01179     ///     http://www.embedded.com/design/system-integration/4023968/How-To-Calibrate-Touch-Screens
01180     ///
01181     /// @copyright Copyright &copy; 2001, Carlos E. Vidales. All rights reserved.
01182     ///     This sample program was written and put in the public domain 
01183     ///      by Carlos E. Vidales.  The program is provided "as is" 
01184     ///      without warranty of any kind, either expressed or implied.
01185     ///     If you choose to use the program within your own products
01186     ///      you do so at your own risk, and assume the responsibility
01187     ///      for servicing, repairing or correcting the program should
01188     ///      it prove defective in any manner.
01189     ///     You may copy and distribute the program's source code in any 
01190     ///      medium, provided that you also include in each copy an
01191     ///      appropriate copyright notice and disclaimer of warranty.
01192     ///     You may also modify this program and distribute copies of
01193     ///      it provided that you include prominent notices stating 
01194     ///      that you changed the file(s) and the date of any change,
01195     ///      and that you do not charge any royalties or licenses for 
01196     ///      its use.
01197     ///
01198     /// @param[in] display is a pointer to a set of 3 points, which 
01199     ///             are in display units of measure. These are the targets
01200     ///             the calibration was aiming for.
01201     /// @param[in] screen is a pointer to a set of 3 points, which
01202     ///             are in touchscreen units of measure. These are the
01203     ///             registered touches.
01204     /// @param[out] matrix is an optional parameter to hold the calibration matrix 
01205     ///             as a result of the calibration. This can be saved in  
01206     ///             non-volatile memory to recover the calibration after a power fail.
01207     /// @returns @ref RetCode_t value.
01208     ///
01209     RetCode_t TouchPanelComputeCalibration(point_t display[3], point_t screen[3], tpMatrix_t * matrix);
01210 
01211 
01212     /// Perform the touch panel calibration process.
01213     ///
01214     /// This method provides the easy "shortcut" to calibrating the touch panel.
01215     /// The process will automatically generate the calibration points, present
01216     /// the targets on-screen, detect the touches, compute the calibration
01217     /// matrix, and optionally provide the calibration matrix to the calling code
01218     /// for persistence in non-volatile memory.
01219     ///
01220     /// @param[out] matrix is an optional parameter to hold the calibration matrix 
01221     ///             as a result of the calibration. This can be saved in  
01222     ///             non-volatile memory to recover the calibration after a power fail.
01223     /// @returns @ref RetCode_t value.
01224     ///
01225     RetCode_t TouchPanelCalibrate(tpMatrix_t * matrix = NULL);
01226 
01227 
01228     /// Perform the touch panel calibration process.
01229     ///
01230     /// This method provides the easy "shortcut" to calibrating the touch panel.
01231     /// The process will automatically generate the calibration points, present
01232     /// the targets on-screen, detect the touches, compute the calibration
01233     /// matrix, and optionally provide the calibration matrix to the calling code
01234     /// for persistence in non-volatile memory.
01235     ///
01236     /// @param[in] msg is a text message to present on the screen during the
01237     ///             calibration process.
01238     /// @param[out] matrix is an optional parameter to hold the calibration matrix 
01239     ///             as a result of the calibration. This can be saved in  
01240     ///             non-volatile memory to recover the calibration after a power fail.
01241     /// @param[in] maxwait_s is the maximum number of seconds to wait for a touch
01242     ///             calibration. If no touch panel installed, it then reports
01243     ///             touch_cal_timeout. Default: 30 s.
01244     /// @returns @ref RetCode_t value.
01245     ///
01246     RetCode_t TouchPanelCalibrate(const char * msg, tpMatrix_t * matrix = NULL, int maxwait_s = 30);
01247 
01248 
01249     /// Set the calibration matrix for the resistive touch panel.
01250     ///
01251     /// This method is used to set the calibration matrix for the touch panel. After
01252     /// performing the calibration (See @ref TouchPanelComputeCalibration), the matrix can be stored.
01253     /// On a subsequence power cycle, the matrix may be restored from non-volatile and
01254     /// passed in to this method. It will then be held to perform the corrections when
01255     /// reading the touch panel point.
01256     ///
01257     /// @code
01258     /// FILE * fh = fopen("/local/tpmatrix.cfg", "r");
01259     /// if (fh) {
01260     ///     tpMatrix_t matrix;
01261     ///     if (fread(fh, &matrix, sizeof(tpMatrix_t))) {
01262     ///         lcd.TouchPanelSetMatrix(&matrix);
01263     ///     }
01264     ///     fclose(fh);
01265     /// }
01266     /// @endcode
01267     /// 
01268     /// @param[in] matrix is a pointer to the touch panel calibration matrix.
01269     /// @returns @ref RetCode_t value.
01270     ///
01271     RetCode_t TouchPanelSetMatrix(tpMatrix_t * matrix);
01272 
01273     /// Get the calibration matrix for the resistive touch panel.
01274     ///
01275     /// This method returns a const pointer to the matrix. If this matrix has
01276     /// not be set, with either the TouchPanelSetMatrix API or the calibration
01277     /// process, the results are indeterminate.
01278     ///
01279     /// return const tpMatrix_t pointer
01280     /// 
01281     const tpMatrix_t * TouchPanelGetMatrix();
01282 
01283 #if 0
01284     /// Append interrupt handler for specific RA8875 interrupt source
01285     ///
01286     /// @param[in]    bISRType        Interrupt Source, should be:
01287     ///                                - RA8875_INT_KEYSCAN: KEYCAN interrupt
01288     ///                                - RA8875_INT_DMA: DMA interrupt
01289     ///                                - RA8875_INT_TP: Touch panel interrupt
01290     ///                                - RA8875_INT_BTE: BTE process complete interrupt
01291     ///                                - RA8875_INT_BTEMCU_FONTWR: Multi-purpose interrupt (see spec sheet)   
01292     /// @param[in]    fptr is a callback function to handle the interrupt event.
01293     /// @returns       none
01294     ///
01295     void AppendISR(uint8_t bISRType, void(*fptr)(void));
01296 
01297     /// Unappend interrupt handler for specific RA8875 interrupt source
01298     ///
01299     /// @param[in]    bISRType        Interrupt Source, should be:
01300     ///                                - RA8875_INT_KEYSCAN: KEYCAN interrupt
01301     ///                                - RA8875_INT_DMA: DMA interrupt
01302     ///                                - RA8875_INT_TP: Touch panel interrupt
01303     ///                                - RA8875_INT_BTE: BTE process complete interrupt
01304     ///                                - RA8875_INT_BTEMCU_FONTWR: Multi-purpose interrupt (see spec sheet)   
01305     /// @return       none
01306     ///
01307     void UnAppendISR(uint8_t bISRType);
01308 #endif
01309 
01310 
01311     /// Initialize the keypad interface on the RA8875 controller.
01312     ///
01313     /// Enables the keypad subsystem. It will scan the 4 x 5 matrix
01314     /// and make available key presses.
01315     ///
01316     /// @note See section 5-13 of RAIO RA8875 data sheet for more details.
01317     /// @note When using the display from buy-display.com, be sure that
01318     ///     the option for the keypad is configured on the hardware.
01319     ///
01320     /// All parameters are optional.
01321     /// @param[in] scanEnable when true, enables the key scan function (default: true).
01322     /// @param[in] longDetect when true, additionally enables the long key held detection (default: false).
01323     /// @param[in] sampleTime setting (range: 0 - 3, default: 0).
01324     /// @param[in] scanFrequency setting (range: 0 - 7, default: 0).
01325     /// @param[in] longTimeAdjustment (range: 0 - 3, default: 0).
01326     /// @param[in] interruptEnable when true, enables interrupts from keypress (default: false).
01327     /// @param[in] wakeupEnable when true, activates the wakeup function (default: false).
01328     ///
01329     /// @returns @ref RetCode_t value.
01330     ///
01331     RetCode_t  KeypadInit(bool scanEnable = true, bool longDetect = false, 
01332         uint8_t sampleTime = 0, uint8_t scanFrequency = 0, 
01333         uint8_t longTimeAdjustment = 0,
01334         bool interruptEnable = false, bool wakeupEnable = false);
01335 
01336 
01337     /// Create Key Code definitions for the key matrix.
01338     ///
01339     /// This API provides a table of 22 key-code assignments for the matrix of keys.
01340     /// This can be used to translate the keys 1 - 20 into some other value, as
01341     /// well as to communicate the "no key" (zero) and "error state" (21).
01342     ///
01343     /// In this way, a keypad could easily emulate a piece of a keyboard, transforming
01344     /// 0 - 20 into the values 0, '0', '1', '2', '3', '4', '5', '6', '7', '8',
01345     /// '9', '+', '-', '*' , '/', '=', '(bs)', '(cr)', and so on...
01346     ///
01347     /// @code
01348     /// //        Return Value by Row, Column   Example reassignment
01349     /// //    Column    0    1    2    3    4 
01350     /// //          +-------------------------+  +-------------------------+
01351     /// // Row   0  |   1    2    3    4    5 |  | '7'  '8'  '9'  ',' '<-' |
01352     /// //       1  |   6    7    8    9   10 |  | '4'  '5'  '6'  '/'  '-' |
01353     /// //       2  |  11   12   13   14   15 |  | '1'  '2'  '3'  '*'  '+' |
01354     /// //       3  |  16   17   18   19   20 |  | '0'  '.'  '('  ')' '\n' |
01355     /// //          +-------------------------+  +-------------------------+
01356     /// //     Return value  0 = No Key pressed
01357     /// //     Return value 21 = Error
01358     /// const uint8_t CodeList[22] = 
01359     ///     {0, '7', '8', '9', ',', '\h', 
01360     ///         '4', '5', '6', '/', '-',
01361     ///         '1', '2', '3', '*', '+',
01362     ///         '0', '.', '(', ')', '\n', 
01363     ///         '\x1b'};
01364     ///     lcd.SetKeyMap(CodeList);
01365     /// @endcode
01366     /// 
01367     /// @param[in] CodeList is a pointer to an always available byte-array 
01368     ///             where the first 22 bytes are used as the transformation 
01369     ///             from raw code to your reassigned value.
01370     ///            If CodeList is NULL, the original raw value key map is
01371     ///             restored.
01372     /// @returns @ref RetCode_t value.
01373     ///
01374     RetCode_t SetKeyMap(const uint8_t * CodeList = NULL);
01375 
01376 
01377     /// Determine if a key has been hit
01378     ///
01379     /// @returns true if a key has been hit
01380     ///
01381     bool readable();
01382 
01383 
01384     /// Blocking read of the keypad.
01385     ///
01386     /// @note: This is a blocking read, so it is important to first call _kbhit()
01387     ///         to avoid hanging your processes.
01388     ///
01389     /// A keypad connected to the RA8875 is connected in a matrix of 4 rows and 5 columns.
01390     /// When pressed, this method will return a code in the range of 1 through 20, reserving
01391     /// the value 0 to indicate that no key is pressed.
01392     ///
01393     /// Additionally, if configured to detect a "long press", bit 7 will be set to indicate
01394     /// this. In this situation, first a "normal press" would be detected and signaled and
01395     /// soon after that a "long press" of the same key would be detected and communicated.
01396     ///
01397     /// @return 8-bit where bit 7 indicates a long press. The remaining bits indicate the
01398     ///     keypress using 0 = no key pressed, 1 - 20 = the key pressed.
01399     ///
01400     uint8_t getc();
01401     
01402     
01403     /// Determine if a point is within a rectangle.
01404     ///
01405     /// @param[in] rect is a rectangular region to use.
01406     /// @param[in] p is a point to analyze to see if it is within the rect.
01407     /// @returns true if p is within rect.
01408     ///
01409     bool Intersect(rect_t rect, point_t p);
01410 
01411     /// Determine if a rectangle intersects another rectangle.
01412     ///
01413     /// @param[in] rect1 is a rectangular region.
01414     /// @param[in] rect2 is a second rectangular region.
01415     /// @returns true if any part of rect2 intersects rect1.
01416     ///
01417     bool Intersect(rect_t rect1, rect_t rect2);
01418     
01419     /// Determine if a rectangle intersects another rectangle and provides
01420     /// the area of intersection.
01421     ///
01422     /// @code
01423     ///     +---------------------+
01424     ///     | rect1               |
01425     ///     |                     |
01426     ///     |          +------------------+
01427     ///     |          | rect3    |       |
01428     ///     |          |          |       |
01429     ///     +---------------------+       |
01430     ///                | rect2            |
01431     ///                +------------------+
01432     /// @endcode
01433     ///
01434     /// @note that the first parameter is a pointer to a rect and the 
01435     ///
01436     /// @param[inout] pRect1 is a pointer to a rectangular region, and returns
01437     ///             the area of intersection.
01438     /// @param[in] pRect2 is a pointer to a second rectangular region.
01439     /// @returns true if pRect1 and pRect2 intersect and pRect1 is written with
01440     ///             the rectangle describing the intersection.
01441     ///
01442     bool Intersect(rect_t * pRect1, const rect_t * pRect2);
01443     
01444     
01445     /// Write a command to the display with a word of data.
01446     ///
01447     /// This is a high level command, and may invoke several primitives.
01448     ///
01449     /// @param[in] command is the command to write.
01450     /// @param[in] data is data to be written to the command register.
01451     /// @returns @ref RetCode_t value.
01452     ///
01453     RetCode_t WriteCommandW(uint8_t command, uint16_t data);
01454 
01455 
01456     /// Write a command to the display
01457     ///
01458     /// This is a high level command, and may invoke several primitives.
01459     ///
01460     /// @param[in] command is the command to write.
01461     /// @param[in] data is optional data to be written to the command register
01462     ///     and only occurs if the data is in the range [0 - 0xFF].
01463     /// @returns @ref RetCode_t value.
01464     ///
01465     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF);
01466 
01467     
01468     /// Write a data word to the display
01469     ///
01470     /// This is a high level command, and may invoke several primitives.
01471     ///
01472     /// @param[in] data is the data to write.
01473     /// @returns @ref RetCode_t value.
01474     ///
01475     RetCode_t WriteDataW(uint16_t data);
01476 
01477     
01478     /// Write a data byte to the display
01479     ///
01480     /// This is a high level command, and may invoke several primitives.
01481     ///
01482     /// @param[in] data is the data to write.
01483     /// @returns @ref RetCode_t value.
01484     ///
01485     virtual RetCode_t WriteData(unsigned char data);
01486 
01487     
01488     /// Read a command register
01489     ///
01490     /// @param[in] command is the command register to read.
01491     /// @returns the value read from the register.
01492     ///
01493     unsigned char ReadCommand(unsigned char command);
01494 
01495 
01496     /// Read a word from a command register
01497     ///
01498     /// @param[in] command is the command register to read.
01499     /// @returns the value read from the register.
01500     ///
01501     uint16_t ReadCommandW(unsigned char command);
01502     
01503     
01504     /// Read a data byte from the display
01505     ///
01506     /// This is a high level command, and may invoke several primitives.
01507     ///
01508     /// @returns data that was read.
01509     ///
01510     unsigned char ReadData(void);
01511 
01512     
01513     /// Read a word from the display
01514     ///
01515     /// This is a high level command, and may invoke several primitives.
01516     ///
01517     /// @returns data that was read.
01518     ///
01519     uint16_t ReadDataW(void);
01520 
01521 
01522     /// Read the display status
01523     ///
01524     /// This is a high level command, and may invoke several primitives.
01525     ///
01526     /// @returns data that was read.
01527     ///
01528     unsigned char ReadStatus(void);
01529 
01530 
01531     /// get the width in pixels of the currently active font
01532     ///
01533     /// @returns font width in pixels.
01534     ///    
01535     dim_t fontwidth(void);
01536     
01537 
01538     /// get the height in pixels of the currently active font
01539     ///
01540     /// @returns font height in pixels.
01541     ///    
01542     dim_t fontheight(void);
01543 
01544     
01545     /// get the number of colums based on the currently active font
01546     ///
01547     /// @returns number of columns.
01548     ///    
01549     virtual int columns(void);
01550 
01551 
01552     /// get the number of rows based on the currently active font
01553     ///
01554     /// @returns number of rows.
01555     ///    
01556     virtual int rows(void);
01557 
01558 
01559     /// get the screen width in pixels
01560     ///
01561     /// @returns screen width in pixels.
01562     ///
01563     virtual dim_t width(void);
01564 
01565 
01566     /// get the screen height in pixels
01567     ///
01568     /// @returns screen height in pixels.
01569     ///
01570     virtual dim_t height(void);
01571 
01572 
01573     /// get the color depth in bits per pixel.
01574     ///
01575     /// @returns 8 or 16 only.
01576     ///
01577     virtual dim_t color_bpp(void);
01578 
01579     /// Set cursor position based on the current font size.
01580     /// 
01581     /// @param[in] column is the horizontal position in character positions
01582     /// @param[in] row is the vertical position in character positions
01583     /// @returns @ref RetCode_t value.
01584     ///
01585     virtual RetCode_t locate(textloc_t column, textloc_t row);
01586 
01587 
01588     /// Prepare the controller to write text to the screen by positioning
01589     /// the cursor.
01590     ///
01591     /// @code
01592     ///     lcd.SetTextCursor(100, 25);
01593     ///     lcd.puts("Hello");
01594     /// @endcode
01595     ///
01596     /// @param[in] x is the horizontal position in pixels (from the left edge)
01597     /// @param[in] y is the vertical position in pixels (from the top edge)
01598     /// @returns @ref RetCode_t value.
01599     ///
01600     RetCode_t SetTextCursor(loc_t x, loc_t y);
01601 
01602 
01603     /// Prepare the controller to write text to the screen by positioning
01604     /// the cursor.
01605     ///
01606     /// @code
01607     ///     point_t point = {100, 25};
01608     ///     lcd.SetTextCursor(point);
01609     ///     lcd.puts("Hello");
01610     /// @endcode
01611     ///
01612     /// @param[in] p is the x:y point in pixels from the top-left.
01613     /// @returns @ref RetCode_t value.
01614     ///
01615     RetCode_t SetTextCursor(point_t p);
01616 
01617 
01618     /// Get the current cursor position in pixels.
01619     ///
01620     /// @code
01621     ///     point_t point = GetTextCursor();
01622     ///     if (point.x > 100 && point.y > 150)
01623     ///         //...
01624     /// @endcode
01625     ///
01626     /// @returns cursor position.
01627     ///
01628     point_t GetTextCursor(void);
01629     
01630 
01631     /// Get the current cursor horizontal position in pixels.
01632     ///
01633     /// @returns cursor position horizontal offset.
01634     ///
01635     loc_t GetTextCursor_X(void);
01636 
01637 
01638     /// Get the current cursor vertical position in pixels.
01639     ///
01640     /// @returns cursor position vertical offset.
01641     ///
01642     loc_t GetTextCursor_Y(void);
01643 
01644 
01645     /// Configure additional Cursor Control settings.
01646     ///
01647     /// This API lets you modify other cursor control settings; 
01648     /// Cursor visible/hidden, Cursor blink/normal, 
01649     /// Cursor I-Beam/underscore/box.
01650     ///
01651     /// @param[in] cursor can be set to NOCURSOR (default), IBEAM,
01652     ///         UNDER, or BLOCK.
01653     /// @param[in] blink can be set to true or false (default false)
01654     /// @returns @ref RetCode_t value.
01655     ///
01656     RetCode_t SetTextCursorControl(cursor_t cursor = NOCURSOR, bool blink = false);
01657 
01658     
01659     /// Select the built-in ISO 8859-X font to use next.
01660     ///
01661     /// Supported fonts: ISO 8859-1, -2, -3, -4
01662     ///
01663     /// @note This only modifies the choice of font from the RA8875 internal
01664     ///     fonts.
01665     ///
01666     /// @param[in] font selects the font for the subsequent text rendering.
01667     ///
01668     /// @note if either hScale or vScale is outside of its permitted range,
01669     ///     the command is not executed.
01670     /// @returns @ref RetCode_t value.
01671     ///
01672     RetCode_t SetTextFont(font_t font = ISO8859_1);
01673     
01674 
01675     /// Sets the display orientation.
01676     ///
01677     /// @note This command does not let you "merge" text onto an existing
01678     ///       image, since it reuses the memory for the new orientation.
01679     ///       Therefore, it is recommended that you issue a cls() prior
01680     ///       to sending text to the screen, or you end with a blended
01681     ///       image that is probably not as intended.
01682     ///
01683     /// @note This command only operates on the RA8875 internal fonts.
01684     ///
01685     /// @code
01686     ///     lcd.cls();
01687     ///     lcd.SetOrientation(RA8875::normal);
01688     ///     lcd.puts(30,30, "Normal Landscape");
01689     ///     wait_ms(2500);
01690     ///     
01691     ///     lcd.cls();
01692     ///     lcd.SetOrientation(RA8875::rotate_90);
01693     ///     lcd.puts(30,30, "Rotated 90 Text\r\n");
01694     ///     wait_ms(2500);
01695     ///     
01696     ///     lcd.cls();
01697     ///     lcd.SetOrientation(RA8875::rotate_180);
01698     ///     lcd.puts(30,30, "Rotated 180 Text\r\n");
01699     ///     wait_ms(2500);
01700     /// 
01701     ///     lcd.cls();
01702     ///     lcd.SetOrientation(RA8875::rotate_270);
01703     ///     lcd.puts(30,30, "Rotated 270 Text\r\n");
01704     ///     wait_ms(2500);
01705     /// @endcode
01706     ///
01707     /// @param[in] angle defaults to normal, but can be rotated
01708     ///         - normal | rotate_0
01709     ///         - rotate_90 (clockwise)
01710     ///         - rotate_180
01711     ///         - rotate_270 (clockwise)
01712     /// @returns @ref RetCode_t value.
01713     ///
01714     RetCode_t SetOrientation(orientation_t angle = normal);
01715     
01716 
01717     /// Control the font behavior.
01718     ///
01719     /// This command lets you make several modifications to any text that
01720     /// will be written to the screen.
01721     ///
01722     /// @note This command only operates on the RA8875 internal fonts.
01723     ///
01724     /// Options can be combined:
01725     /// Default:
01726     /// @li Full alignment disabled, 
01727     /// @li Font with Background color, 
01728     /// @li Font in normal orientiation, or rotated 90, 180, or 270 clockwise,
01729     /// @li Horizontal scale x 1, 2, 3, or 4
01730     /// @li Vertical scale x 1, 2, 3, or 4
01731     ///
01732     /// @note alignment is a special mode for the fonts, when mixing half and
01733     ///     full fonts on one presentation. 'align_full' starts each full
01734     ///     character on an even alignment. See section 7-4-7 of the RA8875
01735     ///     specification.
01736     /// 
01737     /// @param[in] fillit defaults to FILL, but can be NOFILL
01738     /// @param[in] hScale defaults to 1, but can be 1, 2, 3, or 4,
01739     ///     and scales the font size by this amount.
01740     /// @param[in] vScale defaults to 1, but can be 1, 2, 3, or 4,
01741     ///     and scales the font size by this amount.
01742     /// @param[in] alignment defaults to align_none, but can be
01743     ///     align_full.
01744     /// 
01745     /// @note if either hScale or vScale is outside of its permitted range,
01746     ///     the command is not executed.
01747     /// @returns @ref RetCode_t value.
01748     ///
01749     RetCode_t SetTextFontControl(fill_t fillit = FILL, 
01750         HorizontalScale hScale = 1, 
01751         VerticalScale vScale = 1, 
01752         alignment_t alignment = align_none);
01753     
01754 
01755     /// Control the font size of the RA8875 rendered fonts.
01756     ///
01757     /// This command lets you set the font enlargement for both horizontal
01758     /// and vertical, independent of the rotation, background, and 
01759     /// alignment. See @ref SetTextFontControl.
01760     ///
01761     /// @note This command operates on the RA8875 internal fonts.
01762     /// @note This command also operates on the selected soft font.
01763     ///
01764     /// @param[in] hScale defaults to 1, but can be 1, 2, 3, or 4,
01765     ///     and scales the font size by this amount.
01766     /// @param[in] vScale is an optional parameter that defaults to the hScale value, 
01767     ///     but can be 1, 2, 3, or 4, and scales the font size by this amount.
01768     ///
01769     /// @code
01770     ///     lcd.SetTextFontSize(2);     // Set the font to 2x normal size
01771     ///     lcd.puts("Two times");
01772     ///     lcd.SetTextFontSize(2,3);   // Set the font to 2x Width and 3x Height
01773     ///     lcd.puts("2*2 3*h");
01774     ///     lcd.SetTextFontSize();      // Restore to normal size in both dimensions
01775     ///     lcd.puts("normal");
01776     ///     lcd.SelectUserFont(BPG_Arial63x63); // Large user font
01777     ///     lcd.puts("B63x63");                 // Show a sample
01778     ///     lcd.SetTextFontSize(2);             // Now twice as big
01779     ///     lcd.puts("x2");                     // Show a sample
01780     /// @endcode
01781     ///
01782     /// @note if either hScale or vScale is outside of its permitted range,
01783     ///     the command is not executed.
01784     /// @returns @ref RetCode_t value.
01785     ///
01786     RetCode_t SetTextFontSize(HorizontalScale hScale = 1, VerticalScale vScale = -1);
01787 
01788 
01789     /// Get the text font size of the RA8875 internal fonts.
01790     ///
01791     /// This command lets you retrieve the current settings for the font
01792     /// horizontal and vertical scale factors. The return value is 
01793     /// one of the scale factors 1, 2, 3, or 4.
01794     ///
01795     /// @param[out] hScale is a pointer to memory where the horizontal scale factor
01796     ///     will be written. If the pointer is null, that item will be ignored.
01797     /// @param[out] vScale is a pointer to memory where the vertical scale factor
01798     ///     will be written. If the pointer is null, that item will be ignored.
01799     /// @returns @ref RetCode_t value.
01800     ///
01801     RetCode_t GetTextFontSize(HorizontalScale * hScale, VerticalScale * vScale);
01802 
01803     /// put a character on the screen.
01804     ///
01805     /// @param[in] c is the character.
01806     /// @returns the character, or EOF if there is an error.
01807     ///
01808     virtual int _putc(int c);
01809 
01810 
01811     /// Write string of text to the display
01812     ///
01813     /// @code
01814     ///     lcd.puts("Test STring");
01815     /// @endcode
01816     ///
01817     /// @param[in] string is the null terminated string to send to the display.
01818     ///
01819     void puts(const char * string);
01820 
01821     
01822     /// Write string of text to the display at the specified location.
01823     ///
01824     /// @code
01825     ///     lcd.puts(10,25, "Test STring");
01826     /// @endcode
01827     ///
01828     /// @param[in] x is the horizontal position in pixels (from the left edge)
01829     /// @param[in] y is the vertical position in pixels (from the top edge)
01830     /// @param[in] string is the null terminated string to send to the display.
01831     ///
01832     void puts(loc_t x, loc_t y, const char * string);
01833     
01834 
01835     /// Prepare the controller to write binary data to the screen by positioning
01836     /// the memory cursor.
01837     ///
01838     /// @param[in] x is the horizontal position in pixels (from the left edge)
01839     /// @param[in] y is the vertical position in pixels (from the top edge)
01840     /// @returns @ref RetCode_t value.
01841     ///
01842     virtual RetCode_t SetGraphicsCursor(loc_t x, loc_t y);
01843 
01844     /// Prepare the controller to write binary data to the screen by positioning
01845     /// the memory cursor.
01846     ///
01847     /// @param[in] p is the point representing the cursor position to set
01848     /// @returns @ref RetCode_t value.
01849     ///
01850     virtual RetCode_t SetGraphicsCursor(point_t p);
01851     
01852     /// Read the current graphics cursor position as a point.
01853     ///
01854     /// @returns the graphics cursor as a point.
01855     ///
01856     virtual point_t GetGraphicsCursor(void);
01857 
01858     
01859     /// Prepare the controller to read binary data from the screen by positioning
01860     /// the memory read cursor.
01861     ///
01862     /// @param[in] x is the horizontal position in pixels (from the left edge)
01863     /// @param[in] y is the vertical position in pixels (from the top edge)
01864     /// @returns @ref RetCode_t value.
01865     ///
01866     virtual RetCode_t SetGraphicsCursorRead(loc_t x, loc_t y);
01867     
01868 
01869     /// Set the window, constraining where items are written to the screen.
01870     ///
01871     /// After setting the window, text and graphics are constrained to this
01872     /// window. Text will wrap from the right edge back to the left and down
01873     /// one row and from the bottom to the top. Graphics drawing will be clipped
01874     /// at the edge of the window.
01875     ///
01876     /// @note If the initial text write is outside the window, it will be shown
01877     /// where the cursor position it. Once the write hits the right edge of
01878     /// the defined window, it will then wrap back to the left edge. Once it
01879     /// hits the bottom, it wraps to the top of the window. For this reason,
01880     /// it is common to set the text cursor to the window.
01881     ///
01882     /// @code
01883     ///     rect_t r = {10,10, 90,90};
01884     ///     lcd.window(r);
01885     ///     lcd.SetTextCursor(r.p1.x, r.p1.y);
01886     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
01887     ///     lcd.window(); restore to full screen
01888     /// @endcode
01889     ///
01890     /// @param[in] r is the rect_t used to set the window.
01891     /// @returns @ref RetCode_t value.
01892     ///
01893     virtual RetCode_t window(rect_t r);
01894     
01895 
01896     /// Set the window, constraining where items are written to the screen.
01897     ///
01898     /// After setting the window, text and graphics are constrained to this
01899     /// window. Text will wrap from the right edge back to the left and down
01900     /// one row and from the bottom to the top. Graphics drawing will be clipped
01901     /// at the edge of the window.
01902     ///
01903     /// @note if no parameters are provided, it restores the window to full screen.
01904     ///
01905     /// @note If the initial text write is outside the window, it will be shown
01906     /// where the cursor position it. Once the write hits the right edge of
01907     /// the defined window, it will then wrap back to the left edge. Once it
01908     /// hits the bottom, it wraps to the top of the window. For this reason,
01909     /// it is common to set the text cursor to the window.
01910     ///
01911     /// @code
01912     ///     lcd.window(10,10, 80,80);
01913     ///     lcd.SetTextCursor(10,10);
01914     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
01915     ///     lcd.window(); restore to full screen
01916     /// @endcode
01917     ///
01918     /// @param[in] x is the left edge in pixels.
01919     /// @param[in] y is the top edge in pixels.
01920     /// @param[in] width is the window width in pixels.
01921     /// @param[in] height is the window height in pixels.
01922     /// @returns @ref RetCode_t value.
01923     ///
01924     virtual RetCode_t window(loc_t x = 0, loc_t y = 0, dim_t width = (dim_t)-1, dim_t height = (dim_t)-1);
01925     
01926 
01927     /// Clear either the specified layer, or the active layer.
01928     ///
01929     /// The behavior is to clear the whole screen for the specified
01930     /// layer. When not specified, the active drawing layer is cleared.
01931     /// This command can also be used to specifically clear either,
01932     /// or both layers. See @ref clsw().
01933     ///
01934     /// @code
01935     ///     lcd.cls();
01936     /// @endcode
01937     ///
01938     /// @param[in] layers is optional. If not provided, the active layer
01939     ///     is cleared. If bit 0 is set, layer 0 is cleared, if bit
01940     ///     1 is set, layer 1 is cleared. If both are set, both layers
01941     ///     are cleared. Any other value does not cause an action.
01942     ///     
01943     /// @returns @ref RetCode_t value.
01944     ///
01945     virtual RetCode_t cls(uint16_t layers = 0);
01946 
01947     
01948     /// Clear the screen, or clear only the active window.
01949     ///
01950     /// The default behavior is to clear the whole screen. With the optional 
01951     /// parameter, the action can be restricted to the active window, which
01952     /// can be set with the See @ref window method.
01953     ///
01954     /// @code
01955     ///     lcd.window(20,20, 40,10);
01956     ///     lcd.clsw();
01957     /// @endcode
01958     ///
01959     /// @param[in] region is an optional parameter that defaults to FULLWINDOW
01960     ///         or may be set to ACTIVEWINDOW.
01961     /// @returns @ref RetCode_t value.
01962     ///
01963     RetCode_t clsw(RA8875::Region_t region = FULLWINDOW);
01964 
01965 
01966     /// Set the background color.
01967     ///
01968     /// @param[in] color is expressed in 16-bit format.
01969     /// @returns @ref RetCode_t value.
01970     ///
01971     virtual RetCode_t background(color_t color);
01972 
01973     
01974     /// Set the background color.
01975     ///
01976     /// @param[in] r is the red element of the color.
01977     /// @param[in] g is the green element of the color.
01978     /// @param[in] b is the blue element of the color.
01979     /// @returns @ref RetCode_t value.
01980     ///
01981     virtual RetCode_t background(unsigned char r, unsigned char g, unsigned char b);
01982     
01983 
01984     /// Set the foreground color.
01985     ///
01986     /// @param[in] color is expressed in 16-bit format.
01987     /// @returns @ref RetCode_t value.
01988     ///
01989     virtual RetCode_t foreground(color_t color);
01990     
01991 
01992     /// Set the foreground color.
01993     ///
01994     /// @param[in] r is the red element of the color.
01995     /// @param[in] g is the green element of the color.
01996     /// @param[in] b is the blue element of the color.
01997     /// @returns @ref RetCode_t value.
01998     ///
01999     virtual RetCode_t foreground(unsigned char r, unsigned char g, unsigned char b);
02000     
02001     
02002     /// Get the current foreground color value.
02003     ///
02004     /// @returns the current foreground color as @ref color_t.
02005     ///
02006     color_t GetForeColor(void);
02007     
02008     
02009     /// Draw a pixel in the specified color.
02010     ///
02011     /// @note Unlike many other operations, this does not
02012     ///         set the forecolor!
02013     ///
02014     /// @param[in] p is the point_t defining the location.
02015     /// @param[in] color is expressed in 16-bit format.
02016     /// @returns @ref RetCode_t value.
02017     ///
02018     virtual RetCode_t pixel(point_t p, color_t color);
02019     
02020     
02021     /// Draw a pixel in the current foreground color.
02022     ///
02023     /// @param[in] p is the point_t defining the location.
02024     /// @returns @ref RetCode_t value.
02025     ///
02026     virtual RetCode_t pixel(point_t p);
02027     
02028         
02029     /// Draw a pixel in the specified color.
02030     ///
02031     /// @note Unlike many other operations, this does not
02032     ///         set the forecolor!
02033     ///
02034     /// @param[in] x is the horizontal offset to this pixel.
02035     /// @param[in] y is the vertical offset to this pixel.
02036     /// @param[in] color defines the color for the pixel.
02037     /// @returns @ref RetCode_t value.
02038     ///
02039     virtual RetCode_t pixel(loc_t x, loc_t y, color_t color);
02040     
02041     
02042     /// Draw a pixel in the current foreground color.
02043     ///
02044     /// @param[in] x is the horizontal offset to this pixel.
02045     /// @param[in] y is the veritical offset to this pixel.
02046     /// @returns @ref RetCode_t value.
02047     ///
02048     virtual RetCode_t pixel(loc_t x, loc_t y);
02049     
02050     
02051     /// Get a pixel from the display.
02052     ///
02053     /// @param[in] x is the horizontal offset to this pixel.
02054     /// @param[in] y is the vertical offset to this pixel.
02055     /// @returns the pixel. See @ref color_t
02056     ///
02057     virtual color_t getPixel(loc_t x, loc_t y);
02058     
02059     
02060     /// Write an RGB565 stream of pixels to the display.
02061     ///
02062     /// @param[in] p is a pointer to a color_t array to write.
02063     /// @param[in] count is the number of pixels to write.
02064     /// @param[in] x is the horizontal position on the display.
02065     /// @param[in] y is the vertical position on the display.
02066     /// @returns @ref RetCode_t value.
02067     ///
02068     virtual RetCode_t pixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
02069     
02070     
02071     /// Get a stream of pixels from the display.
02072     ///
02073     /// @param[in] p is a pointer to a color_t array to accept the stream.
02074     /// @param[in] count is the number of pixels to read.
02075     /// @param[in] x is the horizontal offset to this pixel.
02076     /// @param[in] y is the vertical offset to this pixel.
02077     /// @returns @ref RetCode_t value.
02078     ///
02079     virtual RetCode_t getPixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
02080 
02081 
02082     /// Write a boolean stream to the display.
02083     ///
02084     /// This takes a bit stream in memory and using the current color settings
02085     /// it will stream it to the display. Along the way, each bit is translated
02086     /// to either the foreground or background color value and then that pixel
02087     /// is pushed onward.
02088     ///
02089     /// This is similar, but different, to the @ref pixelStream API, which is 
02090     /// given a stream of color values.
02091     /// 
02092     /// This is most often used for Soft Fonts, and for that reason, this method
02093     /// will scale the presentation based on the selected font size. 
02094     /// See @ref SetTextFontSize, So, users may want to SetTextFontSize(1) for
02095     /// 1:1 scaling.
02096     /// 
02097     /// @param[in] x is the horizontal position on the display.
02098     /// @param[in] y is the vertical position on the display.
02099     /// @param[in] w is the width of the rectangular region to fill.
02100     /// @param[in] h is the height of the rectangular region to fill.
02101     /// @param[in] boolStream is the inline memory image from which to extract
02102     ///         the bitstream.
02103     /// @returns @ref RetCode_t value.
02104     ///
02105     virtual RetCode_t booleanStream(loc_t x, loc_t y, dim_t w, dim_t h, const uint8_t * boolStream);
02106 
02107     
02108     /// Draw a line in the specified color
02109     ///
02110     /// @note As a side effect, this changes the current
02111     ///     foreground color for subsequent operations.
02112     ///
02113     /// @param[in] p1 is the point to start the line.
02114     /// @param[in] p2 is the point to end the line.
02115     /// @param[in] color defines the foreground color.
02116     /// @returns @ref RetCode_t value.
02117     ///
02118     RetCode_t line(point_t p1, point_t p2, color_t color);
02119 
02120 
02121     /// Draw a line
02122     ///
02123     /// Draws a line using the foreground color setting.
02124     ///
02125     /// @param[in] p1 is the point to start the line.
02126     /// @param[in] p2 is the point to end the line.
02127     /// @returns @ref RetCode_t value.
02128     ///
02129     RetCode_t line(point_t p1, point_t p2);
02130 
02131     
02132     /// Draw a line in the specified color
02133     ///
02134     /// @note As a side effect, this changes the current
02135     ///     foreground color for subsequent operations.
02136     ///
02137     /// @param[in] x1 is the horizontal start of the line.
02138     /// @param[in] y1 is the vertical start of the line.
02139     /// @param[in] x2 is the horizontal end of the line.
02140     /// @param[in] y2 is the vertical end of the line.
02141     /// @param[in] color defines the foreground color.
02142     /// @returns @ref RetCode_t value.
02143     ///
02144     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2, color_t color);
02145 
02146 
02147     /// Draw a line
02148     ///
02149     /// Draws a line using the foreground color setting.
02150     ///
02151     /// @param[in] x1 is the horizontal start of the line.
02152     /// @param[in] y1 is the vertical start of the line.
02153     /// @param[in] x2 is the horizontal end of the line.
02154     /// @param[in] y2 is the vertical end of the line.
02155     /// @returns @ref RetCode_t value.
02156     ///
02157     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2);
02158 
02159 
02160     /// Draw a thick line
02161     ///
02162     /// Draw a line of a specified thickness and color.
02163     ///
02164     /// In order to draw a thick line, this draws filled circles using 
02165     /// bresenham's algorithm to move the center point of the circle.
02166     /// As a result, this is much slower than drawing a 1-pixel line which
02167     /// uses the hardware line drawing algorithm.
02168     ///
02169     /// Drawing multiple parallel lines to create a thick line is faster,
02170     /// however the line drawing was not guaranteed to fill every pixel
02171     /// on the diagonals.
02172     ///
02173     /// @param[in] p1 is the point to start the line.
02174     /// @param[in] p2 is the point to end the line.
02175     /// @param[in] thickness is the line thickness.
02176     /// @param[in] color defines the foreground color.
02177     /// @returns @ref RetCode_t value.
02178     /// 
02179     RetCode_t ThickLine(point_t p1, point_t p2, dim_t thickness, color_t color);
02180 
02181 
02182     /// Draw a rectangle in the specified color
02183     ///
02184     /// @note As a side effect, this changes the current
02185     ///     foreground color for subsequent operations.
02186     ///
02187     /// @param[in] rect defines the rectangle.
02188     /// @param[in] color defines the foreground color.
02189     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02190     /// @returns @ref RetCode_t value.
02191     ///
02192     RetCode_t rect(rect_t rect, color_t color, fill_t fillit = NOFILL);
02193     
02194 
02195     /// Draw a filled rectangle in the specified color
02196     ///
02197     /// @note As a side effect, this changes the current
02198     ///     foreground color for subsequent operations.
02199     ///
02200     /// @param[in] rect defines the rectangle.
02201     /// @param[in] color defines the foreground color.
02202     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02203     /// @returns @ref RetCode_t value.
02204     ///
02205     RetCode_t fillrect(rect_t rect, color_t color, fill_t fillit = FILL);
02206 
02207 
02208     /// Draw a rectangle in the specified color
02209     ///
02210     /// @note As a side effect, this changes the current
02211     ///     foreground color for subsequent operations.
02212     ///
02213     /// @param[in] x1 is the horizontal start of the line.
02214     /// @param[in] y1 is the vertical start of the line.
02215     /// @param[in] x2 is the horizontal end of the line.
02216     /// @param[in] y2 is the vertical end of the line.
02217     /// @param[in] color defines the foreground color.
02218     /// @param[in] fillit is optional to FILL the rectangle. default is FILL.
02219     /// @returns @ref RetCode_t value.
02220     ///
02221     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02222         color_t color, fill_t fillit = NOFILL);
02223 
02224 
02225     /// Draw a filled rectangle in the specified color
02226     ///
02227     /// @note As a side effect, this changes the current
02228     ///     foreground color for subsequent operations.
02229     ///
02230     /// @param[in] x1 is the horizontal start of the line.
02231     /// @param[in] y1 is the vertical start of the line.
02232     /// @param[in] x2 is the horizontal end of the line.
02233     /// @param[in] y2 is the vertical end of the line.
02234     /// @param[in] color defines the foreground color.
02235     /// @param[in] fillit is optional to NOFILL the rectangle. default is FILL.
02236     /// @returns @ref RetCode_t value.
02237     ///
02238     virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02239         color_t color, fill_t fillit = FILL);
02240 
02241 
02242     /// Draw a rectangle
02243     ///
02244     /// Draws a rectangle using the foreground color setting.
02245     ///
02246     /// @param[in] x1 is the horizontal start of the line.
02247     /// @param[in] y1 is the vertical start of the line.
02248     /// @param[in] x2 is the horizontal end of the line.
02249     /// @param[in] y2 is the vertical end of the line.
02250     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02251     /// @returns @ref RetCode_t value.
02252     ///
02253     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02254         fill_t fillit = NOFILL);
02255 
02256 
02257     /// Draw a filled rectangle with rounded corners using the specified color.
02258     ///
02259     /// This draws a rounded rectangle. A numbers of checks are made on the values,
02260     /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
02261     /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
02262     /// > 1/2 the length of that side (width or height), an error value is returned.
02263     ///
02264     /// @note As a side effect, this changes the current
02265     ///     foreground color for subsequent operations.
02266     ///
02267     /// @param[in] x1 is the horizontal start of the line and must be <= x2.
02268     /// @param[in] y1 is the vertical start of the line and must be <= y2.
02269     /// @param[in] x2 is the horizontal end of the line and must be >= x1.
02270     /// @param[in] y2 is the vertical end of the line and must be >= y1.
02271     /// @param[in] radius1 defines the horizontal radius of the curved corner. Take care
02272     ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
02273     ///         is returned.
02274     /// @param[in] radius2 defines the vertical radius of the curved corner. Take care
02275     ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
02276     ///         is returned.
02277     /// @param[in] color defines the foreground color.
02278     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02279     /// @returns @ref RetCode_t value.
02280     ///
02281     RetCode_t fillroundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02282         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
02283 
02284 
02285     /// Draw a filled rectangle with rounded corners using the specified color.
02286     ///
02287     /// This draws a rounded rectangle. A numbers of checks are made on the values,
02288     /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
02289     /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
02290     /// > 1/2 the length of that side (width or height), an error value is returned.
02291     ///
02292     /// @note As a side effect, this changes the current
02293     ///     foreground color for subsequent operations.
02294     ///
02295     /// @param[in] r is the rectangle to draw.
02296     /// @param[in] radius1 defines the horizontal radius of the curved corner. Take care
02297     ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
02298     ///         is returned.
02299     /// @param[in] radius2 defines the vertical radius of the curved corner. Take care
02300     ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
02301     ///         is returned.
02302     /// @param[in] color defines the foreground color.
02303     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02304     /// @returns @ref RetCode_t value.
02305     ///
02306     RetCode_t fillroundrect(rect_t r, 
02307         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
02308 
02309 
02310     /// Draw a rectangle with rounded corners using the specified color.
02311     ///
02312     /// This draws a rounded rectangle. A numbers of checks are made on the values,
02313     /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
02314     /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
02315     /// > 1/2 the length of that side (width or height), an error value is returned.
02316     ///
02317     /// @note As a side effect, this changes the current
02318     ///     foreground color for subsequent operations.
02319     ///
02320     /// @param[in] r is the rectangle to draw.
02321     /// @param[in] radius1 defines the horizontal radius of the curved corner. Take care
02322     ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
02323     ///         is returned.
02324     /// @param[in] radius2 defines the vertical radius of the curved corner. Take care
02325     ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
02326     ///         is returned.
02327     /// @param[in] color defines the foreground color.
02328     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02329     /// @returns @ref RetCode_t value.
02330     ///
02331     RetCode_t roundrect(rect_t r, 
02332         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
02333 
02334 
02335     /// Draw a rectangle with rounded corners using the specified color.
02336     ///
02337     /// This draws a rounded rectangle. A numbers of checks are made on the values,
02338     /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
02339     /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
02340     /// > 1/2 the length of that side (width or height), an error value is returned.
02341     ///
02342     /// @note As a side effect, this changes the current
02343     ///     foreground color for subsequent operations.
02344     ///
02345     /// @param[in] x1 is the horizontal start of the line and must be <= x2.
02346     /// @param[in] y1 is the vertical start of the line and must be <= y2.
02347     /// @param[in] x2 is the horizontal end of the line and must be >= x1.
02348     /// @param[in] y2 is the vertical end of the line and must be >= y1.
02349     /// @param[in] radius1 defines the horizontal radius of the curved corner. Take care
02350     ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
02351     ///         is returned.
02352     /// @param[in] radius2 defines the vertical radius of the curved corner. Take care
02353     ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
02354     ///         is returned.
02355     /// @param[in] color defines the foreground color.
02356     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02357     /// @returns @ref RetCode_t value.
02358     ///
02359     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02360         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
02361 
02362 
02363     /// Draw a rectangle with rounded corners.
02364     ///
02365     /// This draws a rounded rectangle. A numbers of checks are made on the values,
02366     /// and it could reduce this to drawing a line (if either x1 == x2, or y1 == y2),
02367     /// or a single point (x1 == x2 && y1 == y2). If the radius parameters are
02368     /// > 1/2 the length of that side (width or height), an error value is returned.
02369     ///
02370     /// @param[in] x1 is the horizontal start of the line and must be <= x2.
02371     /// @param[in] y1 is the vertical start of the line and must be <= y2.
02372     /// @param[in] x2 is the horizontal end of the line and must be >= x1.
02373     /// @param[in] y2 is the vertical end of the line and must be >= y1.
02374     /// @param[in] radius1 defines the horizontal radius of the curved corner. Take care
02375     ///         that this value < 1/2 the width of the rectangle, or bad_parameter 
02376     ///         is returned.
02377     /// @param[in] radius2 defines the vertical radius of the curved corner. Take care
02378     ///         that this value < 1/2 the height of the rectangle, or bad_parameter 
02379     ///         is returned.
02380     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02381     /// @returns @ref RetCode_t value.
02382     ///
02383     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02384         dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
02385 
02386 
02387     /// Draw a triangle in the specified color.
02388     ///
02389     /// @note As a side effect, this changes the current
02390     ///     foreground color for subsequent operations.
02391     ///
02392     /// @param[in] p1 is point 1.
02393     /// @param[in] p2 is point 2.
02394     /// @param[in] p3 is point 3.
02395     /// @param[in] color defines the foreground color.
02396     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02397     /// @returns @ref RetCode_t value.
02398     ///
02399     RetCode_t filltriangle(point_t p1, point_t p2, point_t p3, color_t color, fill_t fillit = FILL);
02400 
02401     /// Draw a triangle in the specified color.
02402     ///
02403     /// @note As a side effect, this changes the current
02404     ///     foreground color for subsequent operations.
02405     ///
02406     /// @param[in] p1 is point 1.
02407     /// @param[in] p2 is point 2.
02408     /// @param[in] p3 is point 3.
02409     /// @param[in] color defines the foreground color.
02410     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02411     /// @returns @ref RetCode_t value.
02412     ///
02413     RetCode_t triangle(point_t p1, point_t p2, point_t p3, color_t color, fill_t fillit = NOFILL);
02414     
02415     /// Draw a triangle in the specified color.
02416     ///
02417     /// @note As a side effect, this changes the current
02418     ///     foreground color for subsequent operations.
02419     ///
02420     /// @param[in] x1 is the horizontal for point 1.
02421     /// @param[in] y1 is the vertical for point 1. 
02422     /// @param[in] x2 is the horizontal for point 2.
02423     /// @param[in] y2 is the vertical for point 2.
02424     /// @param[in] x3 is the horizontal for point 3.
02425     /// @param[in] y3 is the vertical for point 3.
02426     /// @param[in] color defines the foreground color.
02427     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02428     /// @returns @ref RetCode_t value.
02429     ///
02430     RetCode_t triangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02431         loc_t x3, loc_t y3, color_t color, fill_t fillit = NOFILL);
02432     
02433 
02434     /// Draw a filled triangle in the specified color.
02435     ///
02436     /// @note As a side effect, this changes the current
02437     ///     foreground color for subsequent operations.
02438     ///
02439     /// @param[in] x1 is the horizontal for point 1.
02440     /// @param[in] y1 is the vertical for point 1.
02441     /// @param[in] x2 is the horizontal for point 2.
02442     /// @param[in] y2 is the vertical for point 2.
02443     /// @param[in] x3 is the horizontal for point 3.
02444     /// @param[in] y3 is the vertical for point 3.
02445     /// @param[in] color defines the foreground color.
02446     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02447     /// @returns @ref RetCode_t value.
02448     ///
02449     RetCode_t filltriangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02450         loc_t x3, loc_t y3, color_t color, fill_t fillit = FILL);
02451 
02452 
02453     /// Draw a triangle
02454     ///
02455     /// Draws a triangle using the foreground color setting.
02456     ///
02457     /// @param[in] x1 is the horizontal for point 1.
02458     /// @param[in] y1 is the vertical for point 1.
02459     /// @param[in] x2 is the horizontal for point 2.
02460     /// @param[in] y2 is the vertical for point 2.
02461     /// @param[in] x3 is the horizontal for point 3.
02462     /// @param[in] y3 is the vertical for point 3.
02463     /// @param[in] fillit is optional to FILL the rectangle. default is NOFILL.
02464     /// @returns @ref RetCode_t value.
02465     ///
02466     RetCode_t triangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
02467         loc_t x3, loc_t y3, fill_t fillit = NOFILL);
02468     
02469 
02470     /// Draw a circle using the specified color.
02471     ///
02472     /// @note As a side effect, this changes the current
02473     ///     foreground color for subsequent operations.
02474     ///
02475     /// @param[in] p defines the center of the circle.
02476     /// @param[in] radius defines the size of the circle.
02477     /// @param[in] color defines the foreground color.
02478     /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
02479     /// @returns @ref RetCode_t value.
02480     ///
02481     RetCode_t circle(point_t p, dim_t radius, color_t color, fill_t fillit = NOFILL);
02482 
02483 
02484     /// Draw a filled circle using the specified color.
02485     ///
02486     /// @note As a side effect, this changes the current
02487     ///     foreground color for subsequent operations.
02488     ///
02489     /// @param[in] p defines the center of the circle.
02490     /// @param[in] radius defines the size of the circle.
02491     /// @param[in] color defines the foreground color.
02492     /// @param[in] fillit is optional to FILL the circle. default is FILL.
02493     /// @returns @ref RetCode_t value.
02494     ///
02495     RetCode_t fillcircle(point_t p, dim_t radius, color_t color, fill_t fillit = FILL);
02496 
02497 
02498     /// Draw a circle.
02499     ///
02500     /// Draws a circle using the foreground color setting.
02501     ///
02502     /// @param[in] p defines the center of the circle.
02503     /// @param[in] radius defines the size of the circle.
02504     /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
02505     /// @returns @ref RetCode_t value.
02506     ///
02507     RetCode_t circle(point_t p, dim_t radius, fill_t fillit = NOFILL);
02508 
02509 
02510     /// Draw a circle using the specified color.
02511     ///
02512     /// @note As a side effect, this changes the current
02513     ///     foreground color for subsequent operations.
02514     ///
02515     /// @param[in] x is the horizontal center of the circle.
02516     /// @param[in] y is the vertical center of the circle.
02517     /// @param[in] radius defines the size of the circle.
02518     /// @param[in] color defines the foreground color.
02519     /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
02520     /// @returns @ref RetCode_t value.
02521     ///
02522     RetCode_t circle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = NOFILL);
02523 
02524 
02525     /// Draw a filled circle using the specified color.
02526     ///
02527     /// @note As a side effect, this changes the current
02528     ///     foreground color for subsequent operations.
02529     ///
02530     /// @param[in] x is the horizontal center of the circle.
02531     /// @param[in] y is the vertical center of the circle.
02532     /// @param[in] radius defines the size of the circle.
02533     /// @param[in] color defines the foreground color.
02534     /// @param[in] fillit is optional to FILL the circle. default is FILL.
02535     /// @returns @ref RetCode_t value.
02536     ///
02537     RetCode_t fillcircle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = FILL);
02538 
02539 
02540     /// Draw a circle.
02541     ///
02542     /// Draws a circle using the foreground color setting.
02543     ///
02544     /// @param[in] x is the horizontal center of the circle.
02545     /// @param[in] y is the vertical center of the circle.
02546     /// @param[in] radius defines the size of the circle.
02547     /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
02548     /// @returns @ref RetCode_t value.
02549     ///
02550     RetCode_t circle(loc_t x, loc_t y, dim_t radius, fill_t fillit = NOFILL);
02551 
02552     /// Draw an Ellipse using the specified color
02553     ///
02554     /// @note As a side effect, this changes the current
02555     ///     foreground color for subsequent operations.
02556     ///
02557     /// @param[in] x is the horizontal center of the ellipse.
02558     /// @param[in] y is the vertical center of the ellipse.
02559     /// @param[in] radius1 defines the horizontal radius of the ellipse.
02560     /// @param[in] radius2 defines the vertical radius of the ellipse.
02561     /// @param[in] color defines the foreground color.
02562     /// @param[in] fillit defines whether the circle is filled or not.
02563     /// @returns @ref RetCode_t value.
02564     ///
02565     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
02566         color_t color, fill_t fillit = NOFILL);
02567 
02568 
02569     /// Draw a filled Ellipse using the specified color
02570     ///
02571     /// @note As a side effect, this changes the current
02572     ///     foreground color for subsequent operations.
02573     ///
02574     /// @param[in] x is the horizontal center of the ellipse.
02575     /// @param[in] y is the vertical center of the ellipse.
02576     /// @param[in] radius1 defines the horizontal radius of the ellipse.
02577     /// @param[in] radius2 defines the vertical radius of the ellipse.
02578     /// @param[in] color defines the foreground color.
02579     /// @param[in] fillit defines whether the circle is filled or not.
02580     /// @returns @ref RetCode_t value.
02581     ///
02582     RetCode_t fillellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
02583         color_t color, fill_t fillit = FILL);
02584 
02585 
02586     /// Draw an Ellipse
02587     ///
02588     /// Draws it using the foreground color setting.
02589     ///
02590     /// @param[in] x is the horizontal center of the ellipse.
02591     /// @param[in] y is the vertical center of the ellipse.
02592     /// @param[in] radius1 defines the horizontal radius of the ellipse.
02593     /// @param[in] radius2 defines the vertical radius of the ellipse.
02594     /// @param[in] fillit defines whether the circle is filled or not.
02595     /// @returns @ref RetCode_t value.
02596     ///
02597     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
02598     
02599 
02600 
02601     /// Block Move
02602     ///
02603     /// The Block Move API activates the RA8875 Block Transfer Engine. Due to the complex
02604     /// set of possible operations, the user should read the related sections of the
02605     /// RA8875 user manual.
02606     ///
02607     /// Some operations may require that other registers are configured, such as the
02608     /// foreground and background color registers, and others. Those must be set
02609     /// outside of this API.
02610     ///
02611     /// @code
02612     /// // Block Move Demo
02613     /// 
02614     /// // Calibrate the resistive touch screen, and store the data on the
02615     /// // local file system.
02616     /// //
02617     /// void CalibrateTS(void)
02618     /// {
02619     ///    FILE * fh;
02620     ///    tpMatrix_t matrix;
02621     ///    RetCode_t r;
02622     ///    Timer testperiod;
02623     /// 
02624     ///    r = lcd.TouchPanelCalibrate("Calibrate the touch panel", &matrix);
02625     ///    if (r == noerror) {
02626     ///        fh = fopen("/local/tpcal.cfg", "wb");
02627     ///        if (fh) {
02628     ///            fwrite(&matrix, sizeof(tpMatrix_t), 1, fh);
02629     ///            fclose(fh);
02630     ///            printf("  tp cal written.\r\n");
02631     ///             lcd.cls();
02632     ///         } else {
02633     ///             printf("  couldn't open tpcal file.\r\n");
02634     ///         }
02635     ///     } else {
02636     ///         printf("error return: %d\r\n", r);
02637     ///     }
02638     ///     lcd.cls();
02639     /// }
02640     /// 
02641     /// // Try to load a previous resistive touch screen calibration from storage. If it
02642     /// // doesn't exist, activate the touch screen calibration process.
02643     /// //
02644     /// void InitTS(void)
02645     /// {
02646     ///     FILE * fh;
02647     ///     tpMatrix_t matrix;
02648     /// 
02649     ///     fh = fopen("/local/tpcal.cfg", "rb");
02650     ///     if (fh) {
02651     ///         fread(&matrix, sizeof(tpMatrix_t), 1, fh);
02652     ///         fclose(fh);
02653     ///         lcd.TouchPanelSetMatrix(&matrix);
02654     ///         printf("  tp cal loaded.\r\n");
02655     ///     } else {
02656     ///         CalibrateTS();
02657     ///     }
02658     /// }
02659     ///
02660     /// int main()
02661     /// {
02662     ///     point_t src;
02663     ///     point_t dst;
02664     ///     TouchCode_t touch;
02665     ///     const dim_t RECT_W = 100;
02666     ///     const dim_t RECT_H = 100;
02667     ///     
02668     ///     pc.baud(460800);    //I like a snappy terminal, so crank it up!
02669     ///     pc.printf("\r\nRA8875 BTE Move Test - Build " __DATE__ " " __TIME__ "\r\n");
02670     ///     lcd.init(LCD_W,LCD_H,LCD_C, BL_NORM);
02671     ///     lcd.TouchPanelInit();
02672     ///     #ifndef CAP_TOUCH
02673     ///     InitTS();   // Calibration for resistive touch panel
02674     ///     #endif
02675     ///     
02676     ///     RetCode_t r = lcd.RenderImageFile(0,0,"/local/fullscrn.jpg");
02677     ///     if (r) pc.printf("  Error: %d; %s\r\n", r, lcd.GetErrorMessage(r));
02678     ///     while (1) {
02679     ///         touch = lcd.TouchPanelReadable();
02680     ///         if (touch) {
02681     ///             point_t xy = lcd.TouchCoordinates();
02682     ///             TouchCode_t t = lcd.TouchCode();
02683     /// 
02684     ///             if (t == touch) {
02685     ///                 src = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_W, LCD_H);
02686     ///             } else if (t == release) {
02687     ///                 dst = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_W, LCD_H);
02688     ///                 r = lcd.BlockMove(0,0,dst, 0,0,src, RECT_W,RECT_H, 0x2, 0xC);
02689     ///             }
02690     ///         }
02691     ///     }
02692     /// }
02693     /// @endcode
02694     ///
02695     /// @param[in] dstLayer layer [5B.7]. layer value is 0 or 1 representing layer 1 and 2.
02696     /// @param[in] dstDataSelect [50.5] defines the destination data type 0: block, 1: linear.
02697     /// @param[in] dstPoint [58-5B] is a point_t defining the destination coordinate.
02698     /// @param[in] srcLayer layer [57.7]. layer value is 0 or 1 representing layer 1 and 2.
02699     /// @param[in] srcDataSelect [50.6] defines the source data type 0: block, 1: linear.
02700     /// @param[in] srcPoint [54-57] is a point_t defining the source coordinate.
02701     /// @param[in] bte_width [5C-5D]. operation width.
02702     /// @param[in] bte_height [5E-5F]. operation height.
02703     /// @param[in] bte_op_code [51.3-0] defines the raster operation function 
02704     ///             (write/read/move/...)
02705     /// @param[in] bte_rop_code [51.7-4] defines what type of BTE operation to perform
02706     ///             (what is placed at the destination)
02707     /// @returns @ref RetCode_t value.
02708     ///
02709     RetCode_t BlockMove(uint8_t dstLayer, uint8_t dstDataSelect, point_t dstPoint,
02710         uint8_t srcLayer, uint8_t srcDataSelect, point_t srcPoint,
02711         dim_t bte_width, dim_t bte_height,
02712         uint8_t bte_op_code, uint8_t bte_rop_code);
02713 
02714 
02715     /// Control display power
02716     ///
02717     /// @param[in] on when set to true will turn on the display, when false it is turned off.
02718     /// @returns @ref RetCode_t value.
02719     ///
02720     RetCode_t Power(bool on);
02721 
02722 
02723     /// Reset the display controller via the Software Reset interface.
02724     ///
02725     /// @returns @ref RetCode_t value.
02726     ///
02727     RetCode_t Reset(void);
02728     
02729 
02730     /// Set backlight brightness.
02731     ///
02732     /// When the built-in PWM is used to control the backlight, this 
02733     /// API can be used to set the brightness.
02734     /// 
02735     /// @param[in] brightness ranges from 0 (off) to 255 (full on)
02736     /// @returns @ref RetCode_t value.
02737     ///
02738     RetCode_t Backlight_u8(uint8_t brightness);
02739 
02740     
02741     /// Get backlight brightness.
02742     ///
02743     /// @returns backlight setting from 0 (off) to 255 (full on).
02744     /// 
02745     uint8_t GetBacklight_u8(void);
02746 
02747     /// Set backlight brightness.
02748     ///
02749     /// When the built-in PWM is used to control the backlight, this 
02750     /// API can be used to set the brightness.
02751     /// 
02752     /// @param[in] brightness ranges from 0.0 (off) to 1.0 (full on)
02753     /// @returns @ref RetCode_t value.
02754     ///
02755     RetCode_t Backlight(float brightness);
02756 
02757 
02758     /// Get backlight brightness.
02759     ///
02760     /// @returns backlight setting from 0 (off) to 1.0 (full on).
02761     /// 
02762     float GetBacklight(void);
02763 
02764 
02765     /// Select a User Font for all subsequent text.
02766     ///
02767     /// @note Tool to create the fonts is accessible from its creator
02768     ///     available at http://www.mikroe.com. 
02769     ///     For version 1.2.0.0, choose the "Export for TFT and new GLCD"
02770     ///     format.
02771     ///
02772     /// @param[in] font is a pointer to a specially formed font resource.
02773     /// @returns @ref RetCode_t value.
02774     ///
02775     virtual RetCode_t SelectUserFont(const uint8_t * font = NULL);
02776 
02777     /// Get the currently selected user font.
02778     ///
02779     /// @returns a pointer to the font, or null, if no user font is selected.
02780     ///
02781     virtual const uint8_t * GetUserFont(void) { return font; }
02782 
02783     /// Get the @ref color_t value from a DOS color index.
02784     ///
02785     /// See @ref PredefinedColors, @ref color_t.
02786     /// 
02787     /// @code
02788     ///     color_t color = DOSColor(12);
02789     /// @endcode
02790     ///
02791     /// @param[in] i is the color index, in the range 0 to 15;
02792     /// @returns the @ref color_t value of the selected index, 
02793     ///     or 0 (@ref Black) if the index is out of bounds.
02794     ///
02795     color_t DOSColor(int i);
02796 
02797 
02798     /// Get the color name (string) from a DOS color index.
02799     ///
02800     /// See @ref PredefinedColors, @ref color_t.
02801     /// 
02802     /// @code
02803     ///     printf("color is %s\n", DOSColorNames(12));
02804     /// @endcode
02805     ///
02806     /// @param[in] i is the color index, in the range 0 to 15;
02807     /// @returns a pointer to a string with the color name,
02808     ///     or NULL if the index is out of bounds.
02809     /// 
02810     const char * DOSColorNames(int i);
02811 
02812 
02813     /// Advanced method indicating the start of a graphics stream.
02814     ///
02815     /// This is called prior to a stream of pixel data being sent.
02816     /// This may cause register configuration changes in the derived
02817     /// class in order to prepare the hardware to accept the streaming
02818     /// data.
02819     ///
02820     /// Following this command, a series of See @ref _putp() commands can
02821     /// be used to send individual pixels to the screen.
02822     ///
02823     /// To conclude the graphics stream, See @ref _EndGraphicsStream should
02824     /// be called.
02825     ///
02826     /// @returns @ref RetCode_t value.
02827     ///
02828     virtual RetCode_t _StartGraphicsStream(void);
02829 
02830     
02831     /// Advanced method to put a single color pixel to the screen.
02832     ///
02833     /// This method may be called as many times as necessary after 
02834     /// See @ref _StartGraphicsStream() is called, and it should be followed 
02835     /// by _EndGraphicsStream.
02836     ///
02837     /// @code
02838     ///     _putp(DOSColor(12));
02839     /// @endcode
02840     ///
02841     /// @param[in] pixel is a color value to be put on the screen.
02842     /// @returns @ref RetCode_t value.
02843     ///
02844     virtual RetCode_t _putp(color_t pixel);
02845 
02846     
02847     /// Advanced method indicating the end of a graphics stream.
02848     ///
02849     /// This is called to conclude a stream of pixel data that was sent.
02850     /// This may cause register configuration changes in the derived
02851     /// class in order to stop the hardware from accept the streaming
02852     /// data.
02853     ///
02854     /// @returns @ref RetCode_t value.
02855     ///
02856     virtual RetCode_t _EndGraphicsStream(void);
02857 
02858 
02859     /// Set the SPI port frequency (in Hz).
02860     ///
02861     /// This uses the mbed SPI driver, and is therefore dependent on
02862     /// its capabilities. The RA8875 can accept writes via SPI faster
02863     /// than a read can be performed. The frequency set by this API
02864     /// is for the SPI writes. It will automatically reduce the SPI
02865     /// clock rate when a read is performed, and restore it for the 
02866     /// next write. Alternately, the 2nd parameters permits setting
02867     /// the read speed rather than letting it compute it automatically.
02868     ///
02869     /// @note The primary effect of this is to recover more CPU cycles
02870     ///     for your application code. Keep in mind that when more than
02871     ///     one command is sent to the display controller, that it
02872     ///     will wait for the controller to finish the prior command.
02873     ///     In this case, the performance is limited by the RA8875.
02874     ///
02875     /// @param[in] Hz is the frequency in Hz, tested range includes the
02876     ///     range from 1,000,000 (1MHz) to 10,000,000 (10 MHz). Values
02877     ///     outside this range will be accepted, but operation may
02878     ///     be unreliable. This depends partially on your hardware design
02879     ///     and the wires connecting the display module.
02880     ///     The default value is 5,000,000, which should work for most
02881     ///     applications as a starting point.
02882     /// @param[in] Hz2 is an optional parameter and will set the read
02883     ///     speed independently of the write speed.
02884     /// @returns @ref RetCode_t value.
02885     ///
02886     RetCode_t frequency(unsigned long Hz = RA8875_DEFAULT_SPI_FREQ, unsigned long Hz2 = 0);
02887 
02888 
02889     /// This method captures the specified area as a 24-bit bitmap file.
02890     ///
02891     /// Even though this is a 16-bit display, the stored image is in
02892     /// 24-bit format.
02893     ///
02894     /// This method will interrogate the current display setting and
02895     /// create a bitmap based on those settings. For instance, if 
02896     /// only layer 1 is visible, then the bitmap is only layer 1. However,
02897     /// if there is some other operation in effect (transparent mode).
02898     ///
02899     /// If the idle callback is registered, it will be activated passing
02900     /// a parameter indicating the percent complete, which may be of value.
02901     ///
02902     /// @param[in] x is the left edge of the region to capture
02903     /// @param[in] y is the top edge of the region to capture
02904     /// @param[in] w is the width of the region to capture
02905     /// @param[in] h is the height of the region to capture.
02906     /// @param[in] Name_BMP is the filename to write the image to.
02907     /// @param[in] bitsPerPixel is optional, defaults to 24, and only 
02908     ///             accepts the values 24, 8
02909     ///             NOTE: The downscaling is CPU intensive, and the operation
02910     ///             takes longer.
02911     /// @returns @ref RetCode_t value.
02912     ///
02913     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP, uint8_t bitsPerPixel = 24);
02914 
02915     
02916     /// This method captures the specified area as a 24-bit bitmap file
02917     /// and delivers it to the previously attached callback.
02918     ///
02919     /// Even though this is a 16-bit display, the stored image is in
02920     /// 24-bit format.
02921     ///
02922     /// This method will interrogate the current display setting and
02923     /// create a bitmap based on those settings. For instance, if 
02924     /// only layer 1 is visible, then the bitmap is only layer 1. However,
02925     /// if there is some other operation in effect (transparent mode), it
02926     /// will return the blended image.
02927     ///
02928     /// If the idle callback is registered, it will be activated passing
02929     /// a parameter indicating the percent complete, which may be of value.
02930     ///
02931     /// @param[in] x is the left edge of the region to capture
02932     /// @param[in] y is the top edge of the region to capture
02933     /// @param[in] w is the width of the region to capture
02934     /// @param[in] h is the height of the region to capture.
02935     /// @param[in] bitsPerPixel is optional, defaults to 24, and only 
02936     ///             accepts the values 24, 8
02937     ///             NOTE: The downscaling is CPU intensive, and the operation
02938     ///             takes longer.
02939     /// @returns @ref RetCode_t value.
02940     ///
02941     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h, uint8_t bitsPerPixel = 24);
02942 
02943     
02944     /// PrintScreen callback registration.
02945     ///
02946     /// This method attaches a simple c-compatible callback of type PrintCallback_T.
02947     /// Then, the PrintScreen(x,y,w,h) method is called. Each chunk of data in the
02948     /// BMP file to be created is passed to this callback.
02949     /// 
02950     /// @param callback is the optional callback function. Without a callback function
02951     ///     it will unregister the handler.
02952     ///
02953     void AttachPrintHandler(PrintCallback_T callback = NULL) { c_callback = callback; }
02954 
02955 
02956     /// PrintScreen callback registration.
02957     ///
02958     /// This method attaches a c++ class method as a callback of type PrintCallback_T.
02959     /// Then, the PrintScreen(x,y,w,h) method is called. Each chunk of data in the
02960     /// BMP file to be created is passed to this callback.
02961     /// 
02962     /// @param object is the class hosting the callback function.
02963     /// @param method is the callback method in the object to activate.
02964     ///
02965     template <class T>
02966     void AttachPrintHandler(T *object, RetCode_t (T::*method)(void)) { 
02967         obj_callback    = (FPointerDummy *)object; 
02968         method_callback = (uint32_t (FPointerDummy::*)(uint32_t, uint8_t *, uint16_t))method;
02969     }
02970 
02971 
02972     /// This method captures the specified area as a 24-bit bitmap file,
02973     /// including the option of layer selection.
02974     ///
02975     /// @note This method is deprecated as the alternate PrintScreen API
02976     ///         automatically examines the display layer configuration.
02977     ///         Therefore, calls to this API will ignore the layer parameter
02978     ///         and automatically execute the other method.
02979     ///
02980     /// Even though this is a 16-bit display, the stored image is in
02981     /// 24-bit format.
02982     ///
02983     /// @param[in] layer is 0 or 1 to select the layer to extract.
02984     /// @param[in] x is the left edge of the region to capture
02985     /// @param[in] y is the top edge of the region to capture
02986     /// @param[in] w is the width of the region to capture
02987     /// @param[in] h is the height of the region to capture.
02988     /// @param[out] Name_BMP is the filename to write the image to.
02989     /// @returns @ref RetCode_t value.
02990     ///
02991     RetCode_t PrintScreen(uint16_t layer, loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
02992 
02993     
02994     /// idle callback registration.
02995     ///
02996     /// This method attaches a simple c-compatible callback of type IdleCallback_T.
02997     /// Then, at any time when the display driver is waiting, it will call the
02998     /// registered function. This is probably most useful if you want to service
02999     /// a watchdog, when you may have called an API that will "hang" waiting
03000     /// on the user.
03001     ///
03002     /// @code
03003     /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason, uint16_t param)
03004     /// {
03005     ///     static uint16_t lastProgress = 0xFFFF;
03006     ///
03007     ///     if (reason == RA8875::progress && param != lastProgress) {
03008     ///         printf("Progress %3d%%\r\n", param);
03009     ///         lastProgress = progress;
03010     ///     }
03011     ///     return noerror;
03012     /// }
03013     ///
03014     ///     ...
03015     ///     lcd.AttachIdleHandler(myIdle_handler);
03016     ///     ...
03017     ///     RetCode_t r = lcd.PrintScreen(0,0,LCD_W,LCD_H,"/local/print.bmp");
03018     ///     if (r ...)
03019     /// @endcode
03020     ///
03021     ///
03022     /// @param callback is the idle callback function. Without a callback function
03023     ///     it will unregister the handler.
03024     ///
03025     void AttachIdleHandler(IdleCallback_T callback = NULL) { idle_callback = callback; }
03026 
03027 
03028 #ifdef PERF_METRICS
03029     /// Clear the performance metrics to zero.
03030     void ClearPerformance();
03031     
03032     /// Count idle time.
03033     ///
03034     /// @param[in] t is the amount of idle time to accumulate.
03035     ///
03036     void CountIdleTime(uint32_t t);
03037     
03038     /// Report the performance metrics for drawing functions using
03039     /// the available serial channel.
03040     ///
03041     /// @param[in,out] pc is the serial channel to write to.
03042     ///
03043     void ReportPerformance(Serial & pc);
03044 #endif
03045 
03046 
03047 private:
03048     /// Touch panel parameters - common to both resistive and capacitive
03049     
03050     /// Data type to indicate which TP, if any, is in use.
03051     typedef enum {
03052         TP_NONE,            ///< no touch panel in use
03053         TP_RES,             ///< resistive touch panel using RA8875
03054         TP_FT5206,          ///< Capacitive touch panel using FT5206
03055         TP_CAP=TP_FT5206,   ///< DEPRECATED: used TP_CAP5206 for that chip-set
03056         TP_GSL1680,         ///< Capacitive touch panel using GSL1680 chip
03057     } WhichTP_T;
03058     
03059     /// boolean flag set true when using Capacitive touch panel, and false
03060     /// for resistive.
03061     WhichTP_T useTouchPanel;    ///< Indicates which TP is selected for use.
03062         
03063     /// Touch State used by TouchPanelReadable. See @ref TouchCode_t.
03064     TouchCode_t touchState;
03065 
03066     ////////////////// Start of Capacitive Touch Panel parameters
03067     
03068     int RoundUp(int value, int roundTo);
03069 public:
03070     uint8_t FT5206_TouchPositions(void);
03071 private:
03072     uint8_t FT5206_ReadRegU8(uint8_t reg);
03073     uint8_t GSL1680_TouchPositions(void);
03074     uint8_t GSL1680_ReadRegU8(uint8_t reg, uint8_t * buf, int count);
03075     RetCode_t FT5206_Init();
03076     RetCode_t GSL1680_Init();
03077 
03078     void TouchPanelISR(void);
03079     uint16_t numberOfTouchPoints;
03080     uint8_t gesture;            ///< Holds the reported gesture information (which doesn't work well for the FT5206)
03081     
03082     /// Touch Information data structure
03083     typedef struct {
03084         uint8_t touchID;        ///< Contains the touch ID, which is the "order" of touch, from 0 to n-1
03085         TouchCode_t touchCode;  ///< Contains the touch code; no_touch, touch, held, release
03086         point_t coordinates;    ///< Contains the X,Y coordinate of the touch
03087     } touchInfo_T;
03088 
03089     touchInfo_T * touchInfo;   /// Storage allocated by the constructor to contains the touch information
03090 
03091     #if MBED_VERSION >= MBED_ENCODE_VERSION(5,8,0)
03092     Thread eventThread;
03093     EventQueue queue;
03094     #endif
03095     InterruptIn * m_irq;
03096     I2C * m_i2c;
03097     int m_addr;                 /// I2C Address of the Cap Touch Controller
03098     //uint8_t data[2];            /// Transfer data for the I2C interface
03099 
03100     bool panelTouched;
03101     
03102     ////////////////// Start of Resistive Touch Panel parameters
03103     
03104     /// Resistive Touch Panel register name definitions
03105     #define TPCR0   0x70
03106     #define TPCR1   0x71
03107     #define TPXH    0x72
03108     #define TPYH    0x73
03109     #define TPXYL   0x74
03110     #define INTC1   0xF0
03111     #define INTC2   0xF1
03112 
03113     /// Specify the default settings for the Touch Panel, where different from the chip defaults
03114     #define TP_MODE_DEFAULT             TP_MODE_AUTO
03115     #define TP_DEBOUNCE_DEFAULT         TP_DEBOUNCE_ON
03116     #define TP_ADC_CLKDIV_DEFAULT       TP_ADC_CLKDIV_8
03117 
03118     #define TP_ADC_SAMPLE_DEFAULT_CLKS  TP_ADC_SAMPLE_8192_CLKS
03119 
03120     /// Other Touch Panel params
03121     #define TPBUFSIZE   16       // Depth of the averaging buffers for x and y data
03122 
03123     // Needs both a ticker and a timer. (could have created a timer from the ticker, but this is easier).
03124     // on a touch, the timer is reset.
03125     // the ticker monitors the timer to see if it has been a long time since
03126     // a touch, and if so, it then clears the sample counter so it doesn't get partial old
03127     // and partial new.
03128     
03129     /// Touch Panel ticker
03130     /// This it bound to a timer to call the _TouchTicker() function periodically.
03131     ///
03132     Ticker touchTicker;
03133     
03134     /// Touch Panel timer
03135     /// Reset on a touch, to expire on a non-touch
03136     ///
03137     Timer timeSinceTouch;
03138     
03139     /// keeps track of which sample we're collecting to filter out the noise.
03140     int touchSample;
03141     
03142     /// Private function for touch ticker callback.
03143     void _TouchTicker(void);
03144     
03145     /// Touch Panel calibration matrix.
03146     tpMatrix_t tpMatrix;
03147 
03148     /// RESISTIVE TP: The fully qualified filename for the RESISTIVE touch panel configuration settings.
03149     const char * tpFQFN;
03150     
03151     /// RESISTIVE TP: The text message shown to the user during the calibration process.
03152     const char * tpCalMessage;
03153 
03154     /// Internal method that performs the TS Cal when the user has so-configured it
03155     RetCode_t _internal_ts_cal();
03156 
03157 
03158     ////////////////// End of Touch Panel parameters
03159 
03160 
03161     /// Internal function to put a character using the built-in (internal) font engine
03162     ///
03163     /// @param[in] c is the character to put to the screen.
03164     /// @returns the character put.
03165     ///
03166     int _internal_putc(int c);
03167     
03168     /// Internal function to put a character using the external font engine
03169     ///
03170     /// @param[in] c is the character to put to the screen.
03171     /// @returns the character put.
03172     ///
03173     int _external_putc(int c);
03174     
03175     /// Internal function to get the actual width of a character when using the external font engine
03176     ///
03177     /// @param[in] c is the character to get the width.
03178     /// @returns the width in pixels of the character. zero if not found.
03179     ///
03180     int _external_getCharWidth(int c);
03181     
03182     /// Write color to an RGB register set
03183     ///
03184     /// This API takes a color value, and writes it into the specified
03185     /// color registers, which are a trio of 3 registers. The actual
03186     /// trio write is performed based on whether the display is configured
03187     /// for 8 or 16 bits per pixel.
03188     ///
03189     /// @param[in] regAddr is the register address starting the trio
03190     /// @param[in] color is the color to write
03191     /// @returns @ref RetCode_t value.
03192     ///
03193     RetCode_t _writeColorTrio(uint8_t regAddr, color_t color);
03194     
03195     /// Read color from an RGB register set
03196     ///
03197     /// This API reads a color value from a trio of registers. The actual
03198     /// trio write is performed based on whether the display is configured
03199     /// for 8 or 16 bits per pixel.
03200     ///
03201     /// @param[in] regAddr is the register address starting the trio
03202     /// @returns color_t value
03203     ///
03204     color_t _readColorTrio(uint8_t regAddr);
03205     
03206     
03207     /// Convert a 16-bit color value to an 8-bit value
03208     ///
03209     /// @param[in] c16 is the 16-bit color value to convert.
03210     /// @returns 8-bit color value.
03211     ///
03212     uint8_t _cvt16to8(color_t c16);
03213 
03214     /// Convert an 8-bit color value to a 16-bit value
03215     ///
03216     /// @param[in] c8 is the 8-bit color value to convert.
03217     /// @returns 16-bit color value.
03218     ///
03219     color_t _cvt8to16(uint8_t c8);
03220     
03221     /// Select the peripheral to use it.
03222     ///
03223     /// @param[in] chipsel when true will select the peripheral, and when false
03224     ///     will deselect the chip. This is the logical selection, and
03225     ///     the pin selection is the invert of this.
03226     /// @returns @ref RetCode_t value.
03227     ///
03228     RetCode_t _select(bool chipsel);
03229 
03230     /// Wait while the status register indicates the controller is busy.
03231     ///
03232     /// @param[in] mask is the mask of bits to monitor.
03233     /// @returns true if a normal exit.
03234     /// @returns false if a timeout exit.
03235     ///
03236     bool _WaitWhileBusy(uint8_t mask);
03237 
03238     /// Wait while the the register anded with the mask is true.
03239     ///
03240     /// @param[in] reg is the register to monitor
03241     /// @param[in] mask is the bit mask to monitor
03242     /// @returns true if it was a normal exit
03243     /// @returns false if it was a timeout that caused the exit.
03244     ///
03245     bool _WaitWhileReg(uint8_t reg, uint8_t mask);
03246 
03247     /// set the spi port to either the write or the read speed.
03248     ///
03249     /// This is a private API used to toggle between the write
03250     /// and the read speed for the SPI port to the RA8875, since
03251     /// it can accept writes faster than reads.
03252     ///
03253     /// @param[in] writeSpeed when true selects the write frequency,
03254     ///     and when false it selects the read frequency.
03255     ///
03256     void _setWriteSpeed(bool writeSpeed);
03257 
03258     /// The most primitive - to write a data value to the SPI interface.
03259     ///
03260     /// @param[in] data is the value to write.
03261     /// @returns a value read from the port, since SPI is often shift
03262     ///     in while shifting out.
03263     ///
03264     unsigned char _spiwrite(unsigned char data);
03265     
03266     /// The most primitive - to read a data value to the SPI interface.
03267     ///
03268     /// This is really just a specialcase of the write command, where
03269     /// the value zero is written in order to read.
03270     ///
03271     /// @returns a value read from the port, since SPI is often shift
03272     ///     in while shifting out.
03273     ///
03274     unsigned char _spiread();
03275     
03276     const uint8_t * pKeyMap;
03277     
03278     SPI spi;                        ///< spi port
03279     bool spiWriteSpeed;             ///< indicates if the current mode is write or read
03280     unsigned long spiwritefreq;     ///< saved write freq
03281     unsigned long spireadfreq;      ///< saved read freq
03282     DigitalOut cs;                  ///< RA8875 chip select pin, assumed active low
03283     DigitalOut res;                 ///< RA8875 reset pin, assumed active low
03284     DigitalOut * m_wake;            ///< GSL1680 wake pin
03285     
03286     // display metrics to avoid lengthy spi read queries
03287     uint8_t screenbpp;              ///< configured bits per pixel
03288     dim_t screenwidth;              ///< configured screen width
03289     dim_t screenheight;             ///< configured screen height
03290     rect_t windowrect;              ///< window commands are held here for speed of access 
03291     bool portraitmode;              ///< set true when in portrait mode (w,h are reversed)
03292     
03293     const unsigned char * font;     ///< reference to an external font somewhere in memory
03294     uint8_t extFontHeight;          ///< computed from the font table when the user sets the font
03295     uint8_t extFontWidth;           ///< computed from the font table when the user sets the font
03296     
03297     loc_t cursor_x, cursor_y;       ///< used for external fonts only
03298     
03299     #ifdef PERF_METRICS
03300     typedef enum
03301     {
03302         PRF_CLS,
03303         PRF_DRAWPIXEL,
03304         PRF_PIXELSTREAM,
03305         PRF_BOOLSTREAM,
03306         PRF_READPIXEL,
03307         PRF_READPIXELSTREAM,
03308         PRF_DRAWLINE,
03309         PRF_DRAWRECTANGLE,
03310         PRF_DRAWROUNDEDRECTANGLE,
03311         PRF_DRAWTRIANGLE,
03312         PRF_DRAWCIRCLE,
03313         PRF_DRAWELLIPSE,
03314         PRF_BLOCKMOVE,
03315         METRICCOUNT
03316     } method_e;
03317     unsigned long metrics[METRICCOUNT];
03318     unsigned long idletime_usec;
03319     void RegisterPerformance(method_e method);
03320     Timer performance;
03321     #endif
03322     
03323     RetCode_t _printCallback(RA8875::filecmd_t cmd, uint8_t * buffer, uint16_t size);
03324     
03325     FILE * _printFH;             ///< PrintScreen file handle
03326     
03327     RetCode_t privateCallback(filecmd_t cmd, uint8_t * buffer, uint16_t size) {
03328         if (c_callback != NULL) {
03329             return (*c_callback)(cmd, buffer, size);
03330         }
03331         else {
03332             if (obj_callback != NULL && method_callback != NULL) {
03333                 return (obj_callback->*method_callback)(cmd, buffer, size);
03334             }
03335         }
03336         return noerror;
03337     }
03338     
03339     RetCode_t (* c_callback)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
03340     FPointerDummy  *obj_callback;
03341     RetCode_t (FPointerDummy::*method_callback)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
03342     RetCode_t (* idle_callback)(IdleReason_T reason, uint16_t param);
03343 };
03344 
03345 
03346 //}     // namespace
03347 
03348 //using namespace SW_graphics;
03349 
03350 
03351 #ifdef TESTENABLE
03352 //      ______________  ______________  ______________  _______________
03353 //     /_____   _____/ /  ___________/ /  ___________/ /_____   ______/
03354 //          /  /      /  /            /  /                  /  /
03355 //         /  /      /  /___         /  /__________        /  /
03356 //        /  /      /  ____/        /__________   /       /  /
03357 //       /  /      /  /                       /  /       /  /
03358 //      /  /      /  /__________  ___________/  /       /  /
03359 //     /__/      /_____________/ /_____________/       /__/
03360 
03361 #include "WebColors.h"
03362 #include <algorithm>
03363 
03364 extern "C" void mbed_reset();
03365 
03366 /// This activates a small set of tests for the graphics library. 
03367 ///
03368 /// Call this API and pass it the reference to the display class.
03369 /// It will then run a series of tests. It accepts interaction via
03370 /// stdin to switch from automatic test mode to manual, run a specific
03371 /// test, or to exit the test mode.
03372 ///
03373 /// @param[in] lcd is a reference to the display class.
03374 /// @param[in] pc is a reference to a serial interface, typically the USB to PC.
03375 ///
03376 void RunTestSet(RA8875 & lcd, Serial & pc);
03377 
03378 
03379 // To enable the test code, uncomment this section, or copy the
03380 // necessary pieces to your "main()".
03381 //
03382 // #include "mbed.h"
03383 // #include "RA8875.h"
03384 // RA8875 lcd(p5, p6, p7, p12, NC, "tft");    // MOSI, MISO, SCK, /ChipSelect, /reset, name
03385 // Serial pc(USBTX, USBRX);
03386 // extern "C" void mbed_reset();
03387 // int main()
03388 // {
03389 //     pc.baud(460800);    // I like a snappy terminal, so crank it up!
03390 //     pc.printf("\r\nRA8875 Test - Build " __DATE__ " " __TIME__ "\r\n");
03391 // 
03392 //     pc.printf("Turning on display\r\n");
03393 //     lcd.init();
03394 //     lcd.Reset();
03395 //     lcd.Power(true);  // display power is on, but the backlight is independent
03396 //     lcd.Backlight(0.5);
03397 //     RunTestSet(lcd, pc);
03398 // }
03399 
03400 #endif // TESTENABLE
03401 
03402 #endif