Diff: RA8875.h

Revision:

198:9b6851107426

Parent:

197:853d08e2fb53

Child:

199:fb06805f447f

--- a/RA8875.h	Tue Feb 11 21:51:42 2020 +0000
+++ b/RA8875.h	Sat Mar 28 15:01:38 2020 +0000
@@ -2,22 +2,27 @@
 /// @mainpage RA8875 Display Controller Driver library
 ///
 /// The RA8875 Display controller is a powerful interface for low cost displays. It
-/// can support displays up to 800 x 480 pixels x 16-bit color.
+/// can support displays up to 800 x 480 pixels x 16-bit color and has an integrated
+/// 2D graphics engine which significantly unburdens the hosting cpu. The 2D engine
+/// handles many drawing primitives; such as line, rectangle, triangle, circles, and
+/// each either filled or unfilled. Further, it supports fonts - both internal and
+/// with specific formats of external font roms.
 ///
 /// @image html Example_Program.png "Image of an Example Program"
 ///
+/// In more detail:
+///
 /// Aside from 800 x 480 pixel displays, another common implementation is
 /// 480 x 272 x 16 with two layers. The two layers can be exchanged, or blended
-/// in various ways (transparency, OR, AND, and more). It includes graphics
-/// acceleration capabilities for drawing primitives, such as line, rectangle,
-/// circles, and more.
+/// in various ways (transparency, OR, AND, and more). 
 ///
 /// It is not a display for video-speed animations, and maybe could hold its own
-/// as a slow picture frame, at least when using the SPI ports. How the performance
-/// differs using I2C, 8-bit parallel or 16-bit parallel has not been evaluated.
-/// Certainly the parallel interface option would be expected to be a lot faster.
+/// as a slow picture frame, at least when using the SPI interface. How the 
+/// performance differs using I2C, 8-bit parallel or 16-bit parallel has not 
+/// been evaluated. Certainly the parallel interface option would be expected to be 
+/// a lot faster.
 ///
-/// What it is good at is performing as a basic display for appliance or simple
+/// What it is good at is performing as a basic display for appliances or simple
 /// home automation, and because of the built-in capability to draw lines, circles,
 /// ellipses, rectangles, rounded rectangles, and triangles, it does a lot of the
 /// work that your host micro would otherwise be doing, and in many cases it does
@@ -29,26 +34,46 @@
 /// Without the hardware acceleration built into the RA8875, the host would have to
 /// compute every point, set the graphics cursor to that point, and fill in that
 /// point with the target color. A diagonal line of some length might take 100
-/// interactions instead of just a few. Other drawing primitives are similarly easy.
+/// transactions instead of just a few. Other drawing primitives are similarly easy.
 ///
 /// It has some built-in fonts, which can be enhanced with optional font-chips, and
-/// with the provided software font engine, and a few instructions, you can convert
-/// most any True Type Font into the data structures suitable for this display.
+/// with the software font engine that is part of this library. Instructions are provided
+/// to convert most any True Type Font into the data structures suitable for this display.
+/// The user of this library is expected to respect the copyright of those fonts (there 
+/// are open-source fonts that can be found on the web).
 ///
 /// To round out the features, this library offers the ability to render Bitmap (BMP),
-/// Icon (ICO), Join Photographic Experts Group (JPG), and Graphics Interchange Format
+/// Icon (ICO), Joint Photographic Experts Group (JPG), and Graphics Interchange Format
 /// (GIF) images. These are implemented primarily in software, taking advantage of the
-/// hardware acceleration where it can.
+/// hardware acceleration where it can. There are some limitations, based on available
+/// memory.
 ///
 /// When you are satisfied with what appears on screen, there is a PrintScreen method
-/// to pull that image back out and write it to a file system as a BitMap image.
+/// to pull that image back out of the display RAM and write it to a file system as a 
+/// BitMap image.
+///
+///
+/// The RA8875 has an integrated PWM, commonly used for backlight brightness, keypad scanning
+/// (for a 4 x 5 matrix) and an integrated resistive touch-panel support. Support for capacitive
+/// touch screens is also integrated in this library, in a manner that makes the resistive and
+/// capacitive interfaces nearly API identical. The capacitive touch support was crafted to
+/// interface with either the FT5206 or the GSL1680 controller chips (two popular controllers
+/// commonly integrated with the RA8875).
 ///
-/// The controller additionally supports backlight control (via PWM), keypad scanning
-/// (for a 4 x 5 matrix) and resistive touch-panel support. Support for capacitive
-/// touch screens is also integrated, in a manner that makes the resistive and
-/// capacitive interfaces nearly API identical. The capacitive touch support is for
-/// either the FT5206 or the GSL1680 controller chips.
-///
+/// Recent Changes:
+/// * @ref RA8875::SelectDrawingLayer() returns the previously selected layer, making restore quicker.
+/// * @ref RA8875::SetGraphicsOrientation() has been improved to support 0 deg (typical landscape),
+///             90 deg, 180 deg, and 270 deg, and this includes bitmap and soft-font presentation, 
+///             as well as touch support and to return the previous angle.
+/// * @ref RA8875::SetBackgroundTransparencyColor() returns the previous color value, making 
+///             restore quicker.
+/// * @ref RA8875::SetWindow() accepts a rect_t, or an (x1,y1, x2,y2) point-pair, rather than a
+///             point-pair and a width,height. This makes it much more consisten with all other APIs.
+/// * @ref RA8875::SetLayerMode() returns the previous layer mode.
+/// * @ref RA8875::SetTextCursor() returns the previous cursor.
+/// * @ref RA8875::background() returns the previous color.
+/// * @ref RA8875::foreground() returns the previous color.
+
 /// Here's a few hints to get started:
 /// * @ref Display_Config
 /// * @ref Touch_Panel
@@ -58,22 +83,21 @@
 /// * @ref External_Resources
 /// * @ref Future_Plans
 ///
+/// @todo Integrate the touch as a runtime linkable feature, which can then eliminate
+///     the huge memory footprint for the GSL1680 firmware when it is not needed.
 /// @todo Move the global enums into the class (e.g. NOFILL becomes RA8875::NOFILL) to
 ///     avoid namespace clashes.
-/// @todo Integrate the touch as a runtime linkable feature, which can then eliminate
-///     the huge memory footprint for the GSL1680 firmware when it is not needed.
-/// @todo Integrate installed font-rom.
+/// @todo Integrate access to an installed font-rom.
 /// @todo Figure out how to "init()" in the constructor. I ran into some issues if
 ///     the display was instantiated before main(), and the code would not run,
 ///     thus the exposure and activation of the init() function. If the constructor
 ///     was within main(), then it seemed to work as expected.
-/// @todo Add Scroll support for text.
-/// @todo Add Hardware reset signal - but testing to date indicates it is not needed.
-/// @todo Add high level objects - x-y graph, meter, others... but these will
-///     probably be best served in another class, since they may not
-///     be needed for many uses.
+/// @todo Add Scroll support for text in a window.
+/// @todo Add Hardware reset signal - testing to date indicates it is not needed.
 /// @todo Add APIs for the 2nd RA8875 PWM channel. If the frequency can be independently
-///     controlled, it could be used as a simple beeper.
+///     controlled, it could be used as a simple sound channel (beeper).
+/// @todo Find out if 4-wire SPI can leverage 16-bit mode, and if so, how does the 
+///     performance change?
 ///
 /// @note As the author of this library, let me state that I am not affiliated with
 ///     Raio (silicon provider of the RA8875), or with BuyDisplay.com (where a lot
@@ -81,8 +105,8 @@
 ///     of the technology of the RA8875 chip.
 ///
 /// @copyright Copyright © 2012-2020 by Smartware Computing, all rights reserved.
-///     This library is predominantly, that of Smartware Computing, however some
-///     portions are compiled from the work of others. Where the contribution of
+///     This library is predominantly that of Smartware Computing, however some
+///     portions integrate the work of others. Where the contribution of
 ///     others was listed as copyright, that copyright is maintained, even as a
 ///     derivative work may have been created for better integration in this library.
 ///     See @ref Copyright_References.
@@ -135,8 +159,6 @@
 /// * 1 Layer - when the color depth is 16 bits per pixel
 /// * 2 Layers - when the color depth is 8 bits per pixel and the resolution is 480 x 272.
 ///
-///
-///
 /// @page Touch_Panel Touch Panel
 ///
 /// There is support for various touch panel interfaces.
@@ -316,25 +338,17 @@
 ///
 /// - Change the return values for several functions. Most functions return @ref RA8875::RetCode_t,
 ///     but would benefit from returning a data type related to that function. For example,
-///     @ref RA8875::SelectDrawingLayer() could return the current drawing layer even as a new
+///     @ref RA8875::SelectDrawingLayer() should return the current drawing layer even as a new
 ///     layer is defined. This can facilitate switching back and forth between configurations.
-///     Examples:
-///     - @ref RA8875::SelectDrawingLayer()
+///
+///     Review the API for these (and other) functions for this change:
 ///     - @ref RA8875::SelectUserFont()
-///     - @ref RA8875::SetBackgroundTransparencyColor()
-///     - @ref RA8875::SetLayerMode()
 ///     - @ref RA8875::SetLayerTransparency()
-///     - @ref RA8875::SetOrientation()
-///     - @ref RA8875::SetTextCursor()
 ///     - @ref RA8875::SetTextCursorControl()
 ///     - @ref RA8875::SetTextFont()
 ///     - @ref RA8875::SetTextFontControl()
 ///     - @ref RA8875::SetTextFontSize()
-///     - @ref RA8875::background()
-///     - @ref RA8875::foreground()
 ///     - @ref RA8875::Backlight()
-///     - @ref RA8875::window()
-///     - @ref RA8875::WindowMax()
 ///
 /// - Change the title-case of the functions to be consistent. Because this was adapted
 ///     from parts of several different libraries, it isn't very consistently titled.
@@ -380,6 +394,15 @@
 #define MBED_ENCODE_VERSION(major, minor, patch) ((major)*10000 + (minor)*100 + (patch))
 #endif
 
+#if defined(__GNUC__) || defined(__clang__)
+#define DEPRECATED(msg) __attribute__((deprecated(msg)))
+#elif defined(_MSC_VER)
+#define DEPRECATED __declspec(deprecated)
+#else
+#pragma message("WARNING: You need to implement DEPRECATED for this compiler")
+#define DEPRECATED
+#endif
+
 // Define this to enable code that monitors the performance of various
 // graphics commands.
 //#define PERF_METRICS
@@ -391,8 +414,9 @@
 /// @page PredefinedColors Predefined Colors
 ///
 /// Keep in mind that the color scheme shown here is unlikely to precisely match
-/// that on the actual display. The perceived color is additional affected by
-/// other attributes, such as the backlight brightness.
+/// that on the actual display. The perceived color is additionally affected by
+/// other attributes, such as the polarizer, backlight brightness, liquid crystal
+/// fluid properties, viewing angle, and more...
 ///
 /// These are the predefined colors that are typically used where any @ref color_t
 /// variable is applied.
@@ -418,22 +442,28 @@
 /// <td bgcolor='#00FFFF'>&nbsp;</td><td>@ref BrightCyan</td>
 /// </tr>
 /// <tr>
+/// <td bgcolor='#FF0000'>&nbsp;</td><td>@ref BrightRed</td>
 /// <td bgcolor='#FF5555'>&nbsp;</td><td>@ref Orange</td>
 /// <td bgcolor='#FF55FF'>&nbsp;</td><td>@ref Pink</td>
 /// <td bgcolor='#BBBB00'>&nbsp;</td><td>@ref Yellow</td>
-/// <td bgcolor='#FFFFFF'>&nbsp;</td><td>@ref White</td>
 /// </tr>
 /// <tr>
+/// <td bgcolor='#FFFF00'>&nbsp;</td><td>@ref BrightYellow</td>
+/// <td bgcolor='#FFFFFF'>&nbsp;</td><td>@ref White</td>
 /// <td bgcolor='#00003F'>&nbsp;</td><td>@ref DarkBlue </td>
 /// <td bgcolor='#003F00'>&nbsp;</td><td>@ref DarkGreen</td>
-/// <td bgcolor='#003F3F'>&nbsp;</td><td>@ref DarkCyan </td>
-/// <td bgcolor='#3F0000'>&nbsp;</td><td>@ref DarkRed  </td>
 /// </tr>
 /// <tr>
+/// <td bgcolor='#003F3F'>&nbsp;</td><td>@ref DarkCyan </td>
+/// <td bgcolor='#3F0000'>&nbsp;</td><td>@ref DarkRed  </td>
 /// <td bgcolor='#3F003F'>&nbsp;</td><td>@ref DarkMagenta</td>
 /// <td bgcolor='#3F3F00'>&nbsp;</td><td>@ref DarkBrown  </td>
+/// </tr>
+/// <tr>
 /// <td bgcolor='#3F3F3F'>&nbsp;</td><td>@ref DarkGray   </td>
 /// <td bgcolor='#FFFFFF'>&nbsp;</td><td>&nbsp;</td>
+/// <td bgcolor='#FFFFFF'>&nbsp;</td><td>&nbsp;</td>
+/// <td bgcolor='#FFFFFF'>&nbsp;</td><td>&nbsp;</td>
 /// </tr>
 /// </table>
 /// </blockquote>
@@ -550,17 +580,6 @@
         ISO8859_4       ///< ISO8859-4 font
     } font_t;
 
-    /// display orientation argument for @ref SetOrientation()
-    /// with landscape mode as the normal (0 degree) orientation.
-    typedef enum
-    {
-        normal,         ///< normal (landscape) orientation
-        rotate_0 = normal,  ///< alternate to 'normal'
-        rotate_90,      ///< rotated clockwise 90 degree
-        rotate_180,     ///< rotated (clockwise) 180 degree
-        rotate_270,     ///< rotated clockwise 270 degree
-    } orientation_t;
-
     /// alignment control argument for @ref SetTextFontControl()
     typedef enum
     {
@@ -816,10 +835,10 @@
     ///
     /// Typical of the displays that are readily purchased, you will find 480x272 and 800x480 resolutions.
     ///
-    /// @param[in] width in pixels to configure the display for. This parameter is optional
-    ///             and the default is 480.
-    /// @param[in] height in pixels to configure the display for. This parameter is optional
-    ///             and the default is 272.
+    /// @param[in] width in pixels in landscape orientation to configure the display for. 
+    ///             This parameter is optional and the default is 480.
+    /// @param[in] height in pixels in landscape orientation to configure the display for. 
+    ///             This parameter is optional and the default is 272.
     /// @param[in] color_bpp can be either 8 or 16, but must be consistent
     ///             with the width and height parameters. This parameter is optional
     ///             and the default is 16.
@@ -880,12 +899,9 @@
     ///
     /// @param[in] layer is 0 or 1 to select the layer for subsequent
     ///     commands.
-    /// @param[out] prevLayer is an optiona pointer to where the previous layer
-    ///     will be written, making it a little easer to restore layers.
-    ///     Writes 0 or 1 when the pointer is not NULL.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t SelectDrawingLayer(uint16_t layer, uint16_t * prevLayer = NULL);
+    /// @returns previous drawing layer.
+    ///
+    virtual uint16_t SelectDrawingLayer(uint16_t layer);
 
 
     /// Get the currently active drawing layer.
@@ -928,9 +944,9 @@
     /// @endcode
     ///
     /// @param[in] mode sets the mode in the Layer Transparency Register.
-    /// @returns @ref RetCode_t value.
-    ///
-    RetCode_t SetLayerMode(LayerMode_T mode);
+    /// @returns @ref LayerMode_T as the previous layer value.
+    ///
+    LayerMode_T SetLayerMode(LayerMode_T mode);
 
 
     /// Get the Layer presentation mode.
@@ -971,9 +987,9 @@
     ///
     /// @param[in] color is optional and expressed in 16-bit format. If not
     ///     supplied, a default of Black is used.
-    /// @returns @ref RetCode_t value.
-    ///
-    RetCode_t SetBackgroundTransparencyColor(color_t color = RGB(0,0,0));
+    /// @returns @ref color_t as the previous color value.
+    ///
+    color_t SetBackgroundTransparencyColor(color_t color = RGB(0,0,0));
 
 
     /// Get the background color value used for transparency.
@@ -1258,7 +1274,7 @@
     ///
     ///     // Only if the touch panel is enabled, AND is configured as the resistive
     ///     // panel will the prior command be useful.
-    ///     lcd.init(LCD_W,LCD_H,LCD_C,40, false, true);
+    ///     lcd.init(LCD_PHYS_W,LCD_PHYS_H,LCD_C,40, false, true);
     ///
     /// @endcode
     ///
@@ -1706,9 +1722,9 @@
     ///
     /// @param[in] column is the horizontal position in character positions
     /// @param[in] row is the vertical position in character positions
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t locate(textloc_t column, textloc_t row);
+    /// @returns @ref point_t value that was the last location.
+    ///
+    virtual point_t locate(textloc_t column, textloc_t row);
 
     /// Enable word-wrap in _puts()
     ///
@@ -1732,9 +1748,9 @@
     ///
     /// @param[in] x is the horizontal position in pixels (from the left edge)
     /// @param[in] y is the vertical position in pixels (from the top edge)
-    /// @returns @ref RetCode_t value.
-    ///
-    RetCode_t SetTextCursor(loc_t x, loc_t y);
+    /// @returns @ref point_t value with the prior cursor position.
+    ///
+    point_t SetTextCursor(loc_t x, loc_t y);
 
 
     /// Prepare the controller to write text to the screen by positioning
@@ -1747,9 +1763,9 @@
     /// @endcode
     ///
     /// @param[in] p is the x:y point in pixels from the top-left.
-    /// @returns @ref RetCode_t value.
-    ///
-    RetCode_t SetTextCursor(point_t p);
+    /// @returns @ref point_t value with the prior cursor position.
+    ///
+    point_t SetTextCursor(point_t p);
 
 
     /// Get the current cursor position in pixels.
@@ -1814,9 +1830,9 @@
 
     /// @returns the basic display orientationas an @ref orientation_t value.
     ///
-    orientation_t GetOrientation();
-
-    /// Sets the display orientation.
+    orientation_t GetGraphicsOrientation();
+
+    /// Sets the basic graphics orientation.
     ///
     /// @note This command does not let you "merge" text onto an existing
     ///       image, since it reuses the memory for the new orientation.
@@ -1832,22 +1848,22 @@
     ///
     /// @code
     ///     lcd.cls();
-    ///     lcd.SetOrientation(RA8875::normal);
+    ///     lcd.SetGraphicsOrientation(RA8875::normal);
     ///     lcd.puts(30,30, "Normal Landscape");
     ///     wait_us(2500000);
     ///
     ///     lcd.cls();
-    ///     lcd.SetOrientation(RA8875::rotate_90);
+    ///     lcd.SetGraphicsOrientation(RA8875::rotate_90);
     ///     lcd.puts(30,30, "Rotated 90 Text\r\n");
     ///     wait_us(2500000);
     ///
     ///     lcd.cls();
-    ///     lcd.SetOrientation(RA8875::rotate_180);
+    ///     lcd.SetGraphicsOrientation(RA8875::rotate_180);
     ///     lcd.puts(30,30, "Rotated 180 Text\r\n");
     ///     wait_us(2500000);
     ///
     ///     lcd.cls();
-    ///     lcd.SetOrientation(RA8875::rotate_270);
+    ///     lcd.SetGraphicsOrientation(RA8875::rotate_270);
     ///     lcd.puts(30,30, "Rotated 270 Text\r\n");
     ///     wait_us(2500000);
     /// @endcode
@@ -1859,7 +1875,50 @@
     ///         - rotate_270 (clockwise)
     /// @returns @ref RetCode_t value.
     ///
-    RetCode_t SetOrientation(orientation_t angle = normal);
+    orientation_t SetGraphicsOrientation(orientation_t angle = normal);
+
+    /// Sets the text orientation - Normal or 90 degree.
+    ///
+    /// @attention This command is experimental.
+    ///
+    /// @note This command does not let you "merge" text onto an existing
+    ///       image, since it reuses the memory for the new orientation.
+    ///       Therefore, it is recommended that you issue a cls() prior
+    ///       to sending text to the screen, or you end with a blended
+    ///       image that is probably not as intended.
+    ///
+    /// @note This command only operates on the RA8875 internal fonts.
+    ///
+    /// @code
+    ///     lcd.cls();
+    ///     lcd.SetTextFontOrientation(RA8875::normal);
+    ///     lcd.puts(30,30, "Normal Landscape");
+    ///     wait_us(2500000);
+    ///
+    ///     lcd.cls();
+    ///     lcd.SetTextFontOrientation(RA8875::rotate_90);
+    ///     lcd.puts(30,30, "Rotated 90 Text\r\n");
+    ///     wait_us(2500000);
+    ///
+    ///     lcd.cls();
+    ///     lcd.SetTextFontOrientation(RA8875::rotate_180);
+    ///     lcd.puts(30,30, "Rotated 180 Text\r\n");
+    ///     wait_us(2500000);
+    ///
+    ///     lcd.cls();
+    ///     lcd.SetTextFontOrientation(RA8875::rotate_270);
+    ///     lcd.puts(30,30, "Rotated 270 Text\r\n");
+    ///     wait_us(2500000);
+    /// @endcode
+    ///
+    /// @param[in] angle defaults to normal, but can be rotated
+    ///         - normal | rotate_0
+    ///         - rotate_90 (sets the 90 degree display bit)
+    ///         - rotate_180
+    ///         - rotate_270 (sets the 90 degree display bit)
+    /// @returns @ref RetCode_t value.
+    ///
+    orientation_t SetTextFontOrientation(orientation_t angle);
 
 
     /// Control the font behavior.
@@ -2070,17 +2129,16 @@
     ///
     /// @code
     ///     rect_t r = {10,10, 90,90};
-    ///     lcd.window(r);
+    ///     r = lcd.SetWindow(r);
     ///     lcd.SetTextCursor(r.p1.x, r.p1.y);
     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
-    ///     lcd.window(); restore to full screen
+    ///     lcd.SetWindow(r); restore to previous window setting
     /// @endcode
     ///
     /// @param[in] r is the rect_t used to set the window.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t window(rect_t r);
-
+    /// @returns the previous window definition.
+    ///
+    rect_t SetWindow(rect_t r);
 
     /// Set the window, constraining where items are written to the screen.
     ///
@@ -2092,25 +2150,31 @@
     /// @note if no parameters are provided, it restores the window to full screen.
     ///
     /// @note If the initial text write is outside the window, it will be shown
-    /// where the cursor position it. Once the write hits the right edge of
+    /// where the cursor positions it. Once the write hits the right edge of
     /// the defined window, it will then wrap back to the left edge. Once it
     /// hits the bottom, it wraps to the top of the window. For this reason,
     /// it is common to set the text cursor to the window.
     ///
     /// @code
-    ///     lcd.window(10,10, 80,80);
+    ///     lcd.SetWindow(10,10, 80,80);
     ///     lcd.SetTextCursor(10,10);
     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
-    ///     lcd.window(); restore to full screen
+    ///     lcd.SetWindow(); restore to full screen
     /// @endcode
     ///
-    /// @param[in] x is the left edge in pixels.
-    /// @param[in] y is the top edge in pixels.
-    /// @param[in] width is the window width in pixels.
-    /// @param[in] height is the window height in pixels.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t window(loc_t x = 0, loc_t y = 0, dim_t width = (dim_t)-1, dim_t height = (dim_t)-1);
+    /// @param[in] x1 is the left edge in pixels.
+    /// @param[in] y1 is the top edge in pixels.
+    /// @param[in] x2 is the right edge in pixels.
+    /// @param[in] y2 is the bottom edge in pixels.
+    /// @returns the previous window definition.
+    ///
+    virtual rect_t SetWindow(loc_t x1 = 0, loc_t y1 = 0, loc_t x2 = (loc_t)-1, loc_t y2 = (loc_t)-1);
+
+    /// Get the current window setting, which constrains what is written to the screen.
+    ///
+    /// @returns the current window definition.
+    ///
+    virtual rect_t GetWindow();
 
 
     /// Clear either the specified layer, or the active layer.
@@ -2138,10 +2202,10 @@
     ///
     /// The default behavior is to clear the whole screen. With the optional
     /// parameter, the action can be restricted to the active window, which
-    /// can be set with the See @ref window method.
+    /// can be set with the See @ref SetWindow method.
     ///
     /// @code
-    ///     lcd.window(20,20, 40,10);
+    ///     lcd.SetWindow(20,20, 40,10);
     ///     lcd.clsw();
     /// @endcode
     ///
@@ -2155,9 +2219,9 @@
     /// Set the background color.
     ///
     /// @param[in] color is expressed in 16-bit format.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t background(color_t color);
+    /// @returns @ref color_t value as the previous background color.
+    ///
+    virtual color_t background(color_t color);
 
 
     /// Set the background color.
@@ -2165,17 +2229,17 @@
     /// @param[in] r is the red element of the color.
     /// @param[in] g is the green element of the color.
     /// @param[in] b is the blue element of the color.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t background(unsigned char r, unsigned char g, unsigned char b);
+    /// @returns @ref color_t value as the previous background color.
+    ///
+    virtual color_t background(unsigned char r, unsigned char g, unsigned char b);
 
 
     /// Set the foreground color.
     ///
     /// @param[in] color is expressed in 16-bit format.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t foreground(color_t color);
+    /// @returns @ref color_t value as the previous background color.
+    ///
+    virtual color_t foreground(color_t color);
 
 
     /// Set the foreground color.
@@ -2183,9 +2247,9 @@
     /// @param[in] r is the red element of the color.
     /// @param[in] g is the green element of the color.
     /// @param[in] b is the blue element of the color.
-    /// @returns @ref RetCode_t value.
-    ///
-    virtual RetCode_t foreground(unsigned char r, unsigned char g, unsigned char b);
+    /// @returns @ref color_t value as the previous background color.
+    ///
+    virtual color_t foreground(unsigned char r, unsigned char g, unsigned char b);
 
 
     /// Get the current foreground color value.
@@ -2195,6 +2259,13 @@
     color_t GetForeColor(void);
 
 
+    /// Get the current background color value.
+    ///
+    /// @returns the current background color as @ref color_t.
+    ///
+    color_t GetBackColor(void);
+
+
     /// Draw a pixel in the specified color.
     ///
     /// @note Unlike many other operations, this does not
@@ -2825,9 +2896,9 @@
     ///    if (r == noerror) {
     ///        fh = fopen("/local/tpcal.cfg", "wb");
     ///        if (fh) {
-    ///            fwrite(&matrix, sizeof(tpMatrix_t), 1, fh);
-    ///            fclose(fh);
-    ///            printf("  tp cal written.\r\n");
+    ///             fwrite(&matrix, sizeof(tpMatrix_t), 1, fh);
+    ///             fclose(fh);
+    ///             printf("  tp cal written.\r\n");
     ///             lcd.cls();
     ///         } else {
     ///             printf("  couldn't open tpcal file.\r\n");
@@ -2867,7 +2938,7 @@
     ///
     ///     pc.baud(460800);    //I like a snappy terminal, so crank it up!
     ///     pc.printf("\r\nRA8875 BTE Move Test - Build " __DATE__ " " __TIME__ "\r\n");
-    ///     lcd.init(LCD_W,LCD_H,LCD_C, BL_NORM);
+    ///     lcd.init(LCD_PHYS_W,LCD_PHYS_H,LCD_C, BL_NORM);
     ///     lcd.TouchPanelInit();
     ///     #ifndef CAP_TOUCH
     ///     InitTS();   // Calibration for resistive touch panel
@@ -2882,9 +2953,9 @@
     ///             TouchCode_t t = lcd.TouchCode();
     ///
     ///             if (t == touch) {
-    ///                 src = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_W, LCD_H);
+    ///                 src = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_PHYS_W, LCD_PHYS_H);
     ///             } else if (t == release) {
-    ///                 dst = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_W, LCD_H);
+    ///                 dst = ComputeTopLeftOfRect(xy, RECT_W/2, RECT_H/2, LCD_PHYS_W, LCD_PHYS_H);
     ///                 r = lcd.BlockMove(0,0,dst, 0,0,src, RECT_W,RECT_H, 0x2, 0xC);
     ///             }
     ///         }
@@ -3214,7 +3285,7 @@
     ///     ...
     ///     lcd.AttachIdleHandler(myIdle_handler);
     ///     ...
-    ///     RetCode_t r = lcd.PrintScreen(0,0,LCD_W,LCD_H,"/local/print.bmp");
+    ///     RetCode_t r = lcd.PrintScreen(0,0,LCD_PHYS_W,LCD_PHYS_H,"/local/print.bmp");
     ///     if (r ...)
     /// @endcode
     ///
@@ -3274,6 +3345,7 @@
     uint8_t GSL1680_ReadRegU8(uint8_t reg, uint8_t * buf, int count);
     RetCode_t FT5206_Init();
     RetCode_t GSL1680_Init();
+    void ReadResistive();       ///< Analyze the resistive touch
 
     void TouchPanelISR(void);
     uint16_t numberOfTouchPoints;
@@ -3295,23 +3367,11 @@
     InterruptIn * m_irq;
     I2C * m_i2c;
     int m_addr;                 /// I2C Address of the Cap Touch Controller
-    //uint8_t data[2];            /// Transfer data for the I2C interface
 
     bool panelTouched;
 
     ////////////////// Start of Resistive Touch Panel parameters
 
-#if 0
-    /// Resistive Touch Panel register name definitions
-    #define TPCR0   0x70
-    #define TPCR1   0x71
-    #define TPXH    0x72
-    #define TPYH    0x73
-    #define TPXYL   0x74
-    #define INTC1   0xF0
-    #define INTC2   0xF1
-#endif
-
     /// Specify the default settings for the Touch Panel, where different from the chip defaults
     #define TP_MODE_DEFAULT             TP_MODE_AUTO
     #define TP_DEBOUNCE_DEFAULT         TP_DEBOUNCE_ON
@@ -3487,10 +3547,11 @@
 
     // display metrics to avoid lengthy spi read queries
     uint8_t screenbpp;              ///< configured bits per pixel
-    dim_t screenwidth;              ///< configured screen width
-    dim_t screenheight;             ///< configured screen height
-    rect_t windowrect;              ///< window commands are held here for speed of access
-    bool portraitmode;              ///< set true when in portrait mode (w,h are reversed)
+    dim_t virt_screenwidth;         ///< configured screen width cached here for speed of access
+    dim_t virt_screenheight;        ///< configured screen height cached here for speed of access
+    rect_t windowrect;              ///< window rect cached here for speed of access
+    orientation_t screen_orientation;   ///< configured graphic orientation cached here for speed of access
+    orientation_t text_orientation; ///< configured text orientation cached here for speed of access
     bool wordwrap;                  ///< set true when wordwrap is in effect for _puts()
     const unsigned char * font;     ///< reference to an external font somewhere in memory
     uint8_t extFontHeight;          ///< computed from the font table when the user sets the font
@@ -3543,7 +3604,6 @@
     RetCode_t (FPointerDummy::*method_callback)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
     RetCode_t (* idle_callback)(IdleReason_T reason, uint16_t param);
 
-    orientation_t screen_orientation;
     point_t TranslateOrientation(point_t rawPoint);
 };