Revision 79:544eb4964795, committed 2014-12-28

Comitter:

WiredHome

Date:

Sun Dec 28 19:55:16 2014 +0000

Parent:

78:faf49c381591

Child:

80:cc4fab58179c

Commit message:

cleaned up touch screen support, which included renaming the APIs to better reflect their purpose.; remove dead code, added documentation for methods that were missing it.; major refactor to the constructor, to move needed code to init().

Changed in this revision

--- a/DisplayDefs.h	Sun Dec 28 03:14:35 2014 +0000
+++ b/DisplayDefs.h	Sun Dec 28 19:55:16 2014 +0000
@@ -5,11 +5,12 @@
 
 typedef uint16_t color_t;
 
-/// return values from functions
+/// return values from functions. Use this number, or use the 
+/// lookup function to get a text string. @see GetErrorMessage.
+///
 typedef enum
 {
     noerror,                ///< no errors, command completed successfully
-    no_touch = noerror,
     bad_parameter,          ///< one or more parameters are invalid
     file_not_found,         ///< specified file could not be found
     not_bmp_format,         ///< file is not a .bmp file
@@ -17,7 +18,7 @@
     not_supported_format,   ///< file format is not yet supported
     image_too_big,          ///< image is too large for the screen
     not_enough_ram,         ///< could not allocate ram for scanline
-    touch,    
+    LastErrCode,            // Private marker.
 } RetCode_t;
 
 /// type that manages locations, which is typically an x or y pixel location,

--- a/GraphicsDisplay.cpp	Sun Dec 28 03:14:35 2014 +0000
+++ b/GraphicsDisplay.cpp	Sun Dec 28 19:55:16 2014 +0000
@@ -228,9 +228,9 @@
     return noerror;
 }
 
-void GraphicsDisplay::WindowMax(void)
+RetCode_t GraphicsDisplay::WindowMax(void)
 {
-    window(0,0, width(),height());
+    return window(0,0, width(),height());
 }
 
 RetCode_t GraphicsDisplay::_putp(color_t color)
@@ -248,18 +248,17 @@
     return noerror;
 }
 
-void GraphicsDisplay::fill(int x, int y, int w, int h, color_t color)
+RetCode_t GraphicsDisplay::fill(int x, int y, int w, int h, color_t color)
 {
-    fillrect(x,y, x+w, y+h, color);
+    return fillrect(x,y, x+w, y+h, color);
 }
 
 RetCode_t GraphicsDisplay::cls(uint16_t layers)
 {
-    fill(0, 0, width(), height(), _background);
-    return noerror;
+    return fill(0, 0, width(), height(), _background);
 }
 
-void GraphicsDisplay::blit(int x, int y, int w, int h, const int * color)
+RetCode_t GraphicsDisplay::blit(int x, int y, int w, int h, const int * color)
 {
     window(x, y, w, h);
     _StartGraphicsStream();
@@ -267,7 +266,7 @@
         _putp(color[i]);
     }
     _EndGraphicsStream();
-    WindowMax();
+    return WindowMax();
 }
 
 #ifdef LOCALFONT
@@ -384,11 +383,11 @@
 
     PixelHeight = BMP_Info.biHeight;
     PixelWidth = BMP_Info.biWidth;
+    INFO("(%d,%d) (%d,%d) (%d,%d)", x,y, PixelWidth,PixelHeight, width(), height());
     if (PixelHeight > height() + y || PixelWidth > width() + x) {
         fclose(Image);
         return(image_too_big);
     }
-    INFO("(%d,%d) (%d,%d)", x,y, PixelWidth,PixelHeight);
     if (BMP_Info.biBitCount <= 8) {
         int paletteSize;
         // Read the color palette
@@ -448,7 +447,7 @@
         offset = fileOffset + j * (lineBufSize + padd);     // start of line
         fseek(Image, offset, SEEK_SET);
         fread(lineBuffer, 1, lineBufSize, Image);           // read a line - slow !
-        INFO("offset: %6X", offset);
+        //INFO("offset: %6X", offset);
         for (i = 0; i < PixelWidth; i++) {                  // copy pixel data to TFT
             if (BPP_t == 4) {
                 uint8_t dPix = lineBuffer[i/2];
@@ -456,18 +455,14 @@
                     dPix >>= 4;
                 dPix &= 0x0F;
                 pixelBuffer[i] = RGBQuadToRGB16(colorPalette, dPix);
-                //_putp(RGBQuadToRGB16(colorPalette, dPix));
             } else if (BPP_t == 8) {
                 pixelBuffer[i] = RGBQuadToRGB16(colorPalette, lineBuffer[i]);
-                //_putp(RGBQuadToRGB16(colorPalette, lineBuffer[i]));
             } else if (BPP_t == 16) {
                 pixelBuffer[i] = lineBuffer[i];
-                //_putp(lineBuffer[i]);
             } else if (BPP_t == 24) {
                 color_t color;
                 color = RGB(lineBuffer[i*3+2], lineBuffer[i*3+1], lineBuffer[i*3+0]);
                 pixelBuffer[i] = color;
-                //putp(color);
             }
         }
         pixelStream(pixelBuffer, PixelWidth, x, y++);
@@ -566,5 +561,3 @@
 {
     return height() / 8;
 }
-
-

--- a/GraphicsDisplay.h	Sun Dec 28 03:14:35 2014 +0000
+++ b/GraphicsDisplay.h	Sun Dec 28 19:55:16 2014 +0000
@@ -169,7 +169,9 @@
     /// This restores the 'window' to the full screen, so that 
     /// other operations (@see cls) would clear the whole screen.
     ///
-    virtual void WindowMax(void);
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    virtual RetCode_t WindowMax(void);
     
     /// method to put a single color pixel to the screen.
     ///
@@ -178,13 +180,24 @@
     /// by _EndGraphicsStream.
     ///
     /// @param[in] pixel is a color value to be put on the screen.
-    /// @returns error code.
+    /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t _putp(color_t pixel);
 
+    /// method to fill a region.
+    ///
+    /// This method fills a region with the specified color.
+    ///
+    /// @param[in] x is the left-edge of the region.
+    /// @param[in] y is the top-edge of the region.
+    /// @param[in] w specifies the width of the region.
+    /// @param[in] h specifies the height of the region.
+    /// @returns success/failure code. @see RetCode_t.
+    /// 
+    virtual RetCode_t fill(int x, int y, int w, int h, color_t color);
     
-    virtual void fill(int x, int y, int w, int h, color_t color);
-    virtual void blit(int x, int y, int w, int h, const int * color);    
+    
+    virtual RetCode_t blit(int x, int y, int w, int h, const int * color);    
     
     /// This method transfers one character from the external font data
     /// to the screen.

--- a/RA8875.cpp	Sun Dec 28 03:14:35 2014 +0000
+++ b/RA8875.cpp	Sun Dec 28 19:55:16 2014 +0000
@@ -70,13 +70,23 @@
 #define POLLWAITuSec 10
 
 // Private RawKeyMap for the Keyboard interface
-static const uint8_t KeyMap[22] = {
+static const uint8_t DefaultKeyMap[22] = {
     0,
     1,  2,  3,  4,  5,  6,  7,  8,  9, 10,
     11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
     255
 };
 
+static const char * ErrMessages[] = {
+    "noerror",                ///< no errors, command completed successfully
+    "bad_parameter",          ///< one or more parameters are invalid
+    "file_not_found",         ///< specified file could not be found
+    "not_bmp_format",         ///< file is not a .bmp file
+    "not_ico_format",         ///< file is not a .ico file
+    "not_supported_format",   ///< file format is not yet supported
+    "image_too_big",          ///< image is too large for the screen
+    "not_enough_ram",         ///< could not allocate ram for scanline
+};
 
 RA8875::RA8875(PinName mosi, PinName miso, PinName sclk, PinName csel, PinName reset, const char *name)
     : GraphicsDisplay(name)
@@ -84,29 +94,103 @@
     , cs(csel)
     , res(reset)
 {
-    font = NULL;                        // no external font, use internal.
-    select(false);                      // deselect the display
-    frequency(RA8875_DEFAULT_SPI_FREQ); // data rate
-    Reset();
-    Power(true);
-    Backlight_u8(255);
-    pKeyMap = KeyMap;
-#ifdef PERF_METRICS
-    performance.start();
-    ClearPerformance();
-#endif
 }
 
-
 //RA8875::~RA8875()
 //{
 //}
 
+RetCode_t RA8875::init(bool poweron, int width, int height, int color_bpp)
+{
+    INFO("init(%d,%d,%d,%d)", poweron, width, height, color_bpp);
+    font = NULL;                        // no external font, use internal.
+    pKeyMap = DefaultKeyMap;            // set default key map
+    _select(false);                      // deselect the display
+    frequency(RA8875_DEFAULT_SPI_FREQ); // data rate
+    Reset();
+    WriteCommand(0x88, 0x0B);                   // PLLC1 - Phase Lock Loop registers
+    wait_ms(1);
+    WriteCommand(0x89, 0x02);
+    wait_ms(1);
+
+    // System Config Register (SYSR)
+    if (color_bpp == 16) {
+        WriteCommand(0x10, 0x0C);               // 16-bpp (65K colors) color depth, 8-bit interface
+    } else { // color_bpp == 8
+        WriteCommand(0x10, 0x00);               // 8-bpp (256 colors)
+    }
+    // Pixel Clock Setting Register (PCSR)
+    WriteCommand(0x04, 0x82);                   // PDAT on PCLK falling edge, PCLK = 4 x System Clock
+    wait_ms(1);
+
+    // Horizontal Settings
+    WriteCommand(0x14, width/8 - 1);            //HDWR//Horizontal Display Width Setting Bit[6:0]
+    WriteCommand(0x15, 0x02);                   //HNDFCR//Horizontal Non-Display Period fine tune Bit[3:0]
+    WriteCommand(0x16, 0x03);                   //HNDR//Horizontal Non-Display Period Bit[4:0]
+    WriteCommand(0x17, 0x01);                   //HSTR//HSYNC Start Position[4:0]
+    WriteCommand(0x18, 0x03);                   //HPWR//HSYNC Polarity ,The period width of HSYNC.
+
+    // Vertical Settings
+    WriteCommand(0x19, (height-1)&0xFF);        //VDHR0 //Vertical Display Height Bit [7:0]
+    WriteCommand(0x1a, (height-1)>>8);          //VDHR1 //Vertical Display Height Bit [8]
+    WriteCommand(0x1b, 0x0F);                   //VNDR0 //Vertical Non-Display Period Bit [7:0]
+    WriteCommand(0x1c, 0x00);                   //VNDR1 //Vertical Non-Display Period Bit [8]
+    WriteCommand(0x1d, 0x0e);                   //VSTR0 //VSYNC Start Position[7:0]
+    WriteCommand(0x1e, 0x06);                   //VSTR1 //VSYNC Start Position[8]
+    WriteCommand(0x1f, 0x01);                   //VPWR //VSYNC Polarity ,VSYNC Pulse Width[6:0]
+
+    if (width >= 800 && height >= 480 && color_bpp > 8) {
+        WriteCommand(0x20, 0x00);               // DPCR - 1-layer mode when the resolution is too high
+    } else {
+        WriteCommand(0x20, 0x80);               // DPCR - 2-layer mode
+    }
+
+    // Set display image to Blue on Black as default
+    window(0,0, width, height);             // Initialize to full screen
+    SetTextCursorControl();
+    foreground(Blue);
+    background(Black);
+    cls(3);
+
+    Power(poweron);
+    if (poweron)
+        Backlight_u8(255);
+#ifdef PERF_METRICS
+    performance.start();
+    ClearPerformance();
+#endif
+    return noerror;
+}
+
+
+RetCode_t RA8875::Reset(void)
+{
+    RetCode_t ret;
+    
+    ret = WriteCommand(0x01, 0x01);   // Apply Display Off, Reset
+    wait_ms(2);                     // no idea if I need to wait, or how long
+    if (ret == noerror) {
+        ret = WriteCommand(0x01, 0x00);   // Display off, Remove reset
+        wait_ms(2);                     // no idea if I need to wait, or how long
+    }
+    return ret;
+}
+
+
+const char * RA8875::GetErrorMessage(RetCode_t code)
+{
+    if (code >= LastErrCode)
+        code = bad_parameter;
+    return ErrMessages[code];
+}
+
+
 uint16_t RA8875::GetDrawingLayer(void)
 {
     return (ReadCommand(0x41) & 0x01);
 }
 
+
 RetCode_t RA8875::SelectDrawingLayer(uint16_t layer)
 {
     unsigned char mwcr1 = ReadCommand(0x41) & ~0x01; // retain all but the currently selected layer
@@ -152,6 +236,7 @@
     return noerror;
 }
 
+
 color_t RA8875::GetBackgroundTransparencyColor(void)
 {
     RGBQUAD q;
@@ -186,20 +271,23 @@
     return WriteCommand(0xF0, value);   // INT
 }
 
+
 RetCode_t RA8875::SetKeyMap(const uint8_t * CodeList)
 {
     pKeyMap = CodeList;
     return noerror;
 }
 
+
 bool RA8875::readable(void)
 {
     return (ReadCommand(0xF1) & 0x10);  // check KS status - true if kbhit
 }
 
+
 uint8_t RA8875::getc(void)
 {
-    //#define GETC_DEV
+    //#define GETC_DEV      // for development
 #ifdef GETC_DEV
     uint8_t keyCode1, keyCode2;
 #endif
@@ -270,6 +358,7 @@
     return key;
 }
 
+
 #ifdef PERF_METRICS
 void RA8875::ClearPerformance()
 {
@@ -278,6 +367,7 @@
     idletime_usec = 0;
 }
 
+
 void RA8875::RegisterPerformance(method_e method)
 {
     unsigned long elapsed = performance.read_us();
@@ -286,11 +376,13 @@
         metrics[method] = elapsed;
 }
 
+
 void RA8875::CountIdleTime(uint32_t t)
 {
     idletime_usec += t;
 }
 
+
 void RA8875::ReportPerformance(Serial & pc)
 {
     pc.printf("\r\nPerformance Metrics\r\n");
@@ -310,13 +402,13 @@
 #else
     // This should be a little faster, but doesn't work...
     INFO("WriteCommandW(%02X, %04X)", command, data);
-    select(true);
-    spiwrite(0x80);
-    spiwrite(command);
-    //spiwrite(0x00);     // dummy
-    spiwrite(data & 0xFF);
-    spiwrite(data >> 8);
-    select(false);
+    _select(true);
+    _spiwrite(0x80);
+    _spiwrite(command);
+    //_spiwrite(0x00);     // dummy
+    _spiwrite(data & 0xFF);
+    _spiwrite(data >> 8);
+    _select(false);
 #endif
     return noerror;
 }
@@ -324,35 +416,35 @@
 
 RetCode_t RA8875::WriteCommand(unsigned char command, unsigned int data)
 {
-    select(true);
-    spiwrite(0x80);         // cmd: write command
-    spiwrite(command);
+    _select(true);
+    _spiwrite(0x80);         // cmd: write command
+    _spiwrite(command);
     if (data <= 0xFF) {   // only if in the valid range
-        spiwrite(0x00);
-        spiwrite(data);
+        _spiwrite(0x00);
+        _spiwrite(data);
     }
-    select(false);
+    _select(false);
     return noerror;
 }
 
 
 RetCode_t RA8875::WriteDataW(uint16_t data)
 {
-    select(true);
-    spiwrite(0x00);         // cmd: write data
-    spiwrite(data & 0xFF);
-    spiwrite(data >> 8);
-    select(false);
+    _select(true);
+    _spiwrite(0x00);         // cmd: write data
+    _spiwrite(data & 0xFF);
+    _spiwrite(data >> 8);
+    _select(false);
     return noerror;
 }
 
 
 RetCode_t RA8875::WriteData(unsigned char data)
 {
-    select(true);
-    spiwrite(0x00);
-    spiwrite(data);
-    select(false);
+    _select(true);
+    _spiwrite(0x00);
+    _spiwrite(data);
+    _select(false);
     return noerror;
 }
 
@@ -368,10 +460,10 @@
 {
     unsigned char data;
 
-    select(true);
-    spiwrite(0x40);
-    data = spiread();
-    select(false);
+    _select(true);
+    _spiwrite(0x40);
+    data = _spiread();
+    _select(false);
     return data;
 }
 
@@ -380,11 +472,11 @@
 {
     uint16_t data;
 
-    select(true);
-    spiwrite(0x40);
-    data  = spiread();
-    data |= (spiread() << 8);
-    select(false);
+    _select(true);
+    _spiwrite(0x40);
+    data  = _spiread();
+    data |= (_spiread() << 8);
+    _select(false);
     return data;
 }
 
@@ -393,13 +485,14 @@
 {
     unsigned char data;
 
-    select(true);
-    spiwrite(0xC0);         // These two bits are for the special "Status Read" [STSR]
-    data = spiread();
-    select(false);
+    _select(true);
+    _spiwrite(0xC0);         // These two bits are for the special "Status Read" [STSR]
+    data = _spiread();
+    _select(false);
     return data;
 }
 
+
 /// @todo add a timeout and return false, but how long
 /// to wait since some operations can be very long.
 bool RA8875::_WaitWhileBusy(uint8_t mask)
@@ -416,6 +509,7 @@
         return false;
 }
 
+
 /// @todo add a timeout and return false, but how long
 /// to wait since some operations can be very long.
 bool RA8875::_WaitWhileReg(uint8_t reg, uint8_t mask)
@@ -433,7 +527,6 @@
 }
 
 
-
 dim_t RA8875::fontwidth(void)
 {
     if (font == NULL)
@@ -670,10 +763,10 @@
             WriteCommandW(0x2C, y);
         } else {
             WriteCommand(0x02);                 // RA8875 Internal Fonts
-            select(true);
+            _select(true);
             WriteData(c);
             _WaitWhileBusy(0x80);
-            select(false);
+            _select(false);
         }
     }
     return c;
@@ -725,13 +818,13 @@
         }
 #else
         WriteCommand(0x02);
-        select(true);
+        _select(true);
         while (*string != '\0') {
             WriteData(*string);
             ++string;
             _WaitWhileBusy(0x80);
         }
-        select(false);
+        _select(false);
 #endif
     }
     if (font)
@@ -848,14 +941,14 @@
     WriteCommand(0x40,0x00);    // Graphics write mode
     SetGraphicsCursor(x, y);
     WriteCommand(0x02);
-    select(true);
-    spiwrite(0x00);         // Cmd: write data
+    _select(true);
+    _spiwrite(0x00);         // Cmd: write data
     while (count--) {
-        spiwrite(*p >> 8);
-        spiwrite(*p & 0xFF);
+        _spiwrite(*p >> 8);
+        _spiwrite(*p & 0xFF);
         p++;
     }
-    select(false);
+    _select(false);
     REGISTERPERFORMANCE(PRF_PIXELSTREAM);
     return(noerror);
 }
@@ -870,12 +963,12 @@
     WriteCommand(0x40,0x00);    // Graphics write mode
     SetGraphicsCursorRead(x, y);
     WriteCommand(0x02);
-    select(true);
-    spiwrite(0x40);         // Cmd: read data
-    spiwrite(0x00);         // dummy read
-    pixel  = spiread();
-    pixel |= (spiread() << 8);
-    select(false);
+    _select(true);
+    _spiwrite(0x40);         // Cmd: read data
+    _spiwrite(0x00);         // dummy read
+    pixel  = _spiread();
+    pixel |= (_spiread() << 8);
+    _select(false);
     REGISTERPERFORMANCE(PRF_READPIXEL);
     return pixel;
 }
@@ -890,15 +983,15 @@
     WriteCommand(0x40,0x00);    // Graphics write mode
     SetGraphicsCursorRead(x, y);
     WriteCommand(0x02);
-    select(true);
-    spiwrite(0x40);         // Cmd: read data
-    spiwrite(0x00);         // dummy read
+    _select(true);
+    _spiwrite(0x40);         // Cmd: read data
+    _spiwrite(0x00);         // dummy read
     while (count--) {
-        pixel  = spiread();
-        pixel |= (spiread() << 8);
+        pixel  = _spiread();
+        pixel |= (_spiread() << 8);
         *p++ = pixel;
     }
-    select(false);
+    _select(false);
     REGISTERPERFORMANCE(PRF_READPIXELSTREAM);
     return noerror;
 }
@@ -1188,17 +1281,6 @@
 }
 
 
-RetCode_t RA8875::Reset(void)
-{
-    WriteCommand(0x01, 0x01);   // Apply Display Off, Reset
-    wait_ms(2);                     // no idea if I need to wait, or how long
-    WriteCommand(0x01, 0x00);   // Display off, Remove reset
-    wait_ms(2);                     // no idea if I need to wait, or how long
-    init(RA8875_DISPLAY_WIDTH, RA8875_DISPLAY_HEIGHT, RA8875_COLORDEPTH_BPP);
-    return noerror;
-}
-
-
 RetCode_t RA8875::Backlight_u8(unsigned char brightness)
 {
     static bool is_enabled = false;
@@ -1327,7 +1409,7 @@
 ///////////////////////////////////////////////////////////////
 // Private functions
 
-unsigned char RA8875::spiwrite(unsigned char data)
+unsigned char RA8875::_spiwrite(unsigned char data)
 {
     unsigned char retval;
 
@@ -1338,7 +1420,7 @@
 }
 
 
-unsigned char RA8875::spiread(void)
+unsigned char RA8875::_spiread(void)
 {
     unsigned char retval;
     unsigned char data = 0;
@@ -1350,65 +1432,13 @@
 }
 
 
-RetCode_t RA8875::select(bool chipsel)
+RetCode_t RA8875::_select(bool chipsel)
 {
     cs = (chipsel == true) ? 0 : 1;
     return noerror;
 }
 
 
-RetCode_t RA8875::init(int width, int height, int color_bpp)
-{
-    Backlight_u8(0);
-    WriteCommand(0x88, 0x0B);                   // PLLC1 - Phase Lock Loop registers
-    wait_ms(1);
-    WriteCommand(0x89, 0x02);
-    wait_ms(1);
-
-    // System Config Register (SYSR)
-    if (color_bpp == 16) {
-        WriteCommand(0x10, 0x0C);               // 16-bpp (65K colors) color depth, 8-bit interface
-    } else { // color_bpp == 8
-        WriteCommand(0x10, 0x00);               // 8-bpp (256 colors)
-    }
-    // Pixel Clock Setting Register (PCSR)
-    WriteCommand(0x04, 0x82);                   // PDAT on PCLK falling edge, PCLK = 4 x System Clock
-    wait_ms(1);
-
-    // Horizontal Settings
-    WriteCommand(0x14, width/8 - 1);            //HDWR//Horizontal Display Width Setting Bit[6:0]
-    WriteCommand(0x15, 0x02);                   //HNDFCR//Horizontal Non-Display Period fine tune Bit[3:0]
-    WriteCommand(0x16, 0x03);                   //HNDR//Horizontal Non-Display Period Bit[4:0]
-    WriteCommand(0x17, 0x01);                   //HSTR//HSYNC Start Position[4:0]
-    WriteCommand(0x18, 0x03);                   //HPWR//HSYNC Polarity ,The period width of HSYNC.
-
-    // Vertical Settings
-    WriteCommand(0x19, (height-1)&0xFF);        //VDHR0 //Vertical Display Height Bit [7:0]
-    WriteCommand(0x1a, (height-1)>>8);          //VDHR1 //Vertical Display Height Bit [8]
-    WriteCommand(0x1b, 0x0F);                   //VNDR0 //Vertical Non-Display Period Bit [7:0]
-    WriteCommand(0x1c, 0x00);                   //VNDR1 //Vertical Non-Display Period Bit [8]
-    WriteCommand(0x1d, 0x0e);                   //VSTR0 //VSYNC Start Position[7:0]
-    WriteCommand(0x1e, 0x06);                   //VSTR1 //VSYNC Start Position[8]
-    WriteCommand(0x1f, 0x01);                   //VPWR //VSYNC Polarity ,VSYNC Pulse Width[6:0]
-
-    if (width >= 800 && height >= 480 && color_bpp > 8) {
-        WriteCommand(0x20, 0x00);               // DPCR - 1-layer mode when the resolution is too high
-    } else {
-        WriteCommand(0x20, 0x80);               // DPCR - 2-layer mode
-    }
-
-    // Set display image to Blue on Black as default
-    window(0,0, width, height);             // Initialize to full screen
-    SetTextCursorControl();
-    foreground(Blue);
-    background(Black);
-    SelectDrawingLayer(1);
-    cls();
-    SelectDrawingLayer(0);
-    cls();
-    return noerror;
-}
-
 RetCode_t RA8875::PrintScreen(uint16_t layer, loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP)
 {
 #if 1
@@ -1426,6 +1456,7 @@
 #endif
 }
 
+
 RetCode_t RA8875::PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP)
 {
     BITMAPFILEHEADER BMP_Header;
@@ -2211,7 +2242,7 @@
             display.printf(" (%3d,%3d) => ", pTest[i].x, pTest[i].y);
             display.line(pTest[i].x-10, pTest[i].y, pTest[i].x+10, pTest[i].y, White);
             display.line(pTest[i].x, pTest[i].y-10, pTest[i].x, pTest[i].y+10, White);
-            while (!display.TouchPanelRead(&x, &y))
+            while (!display.TouchPanelA2DFiltered(&x, &y))
                 wait_ms(20);
             pSample[i].x = x;
             pSample[i].y = y;
@@ -2219,7 +2250,7 @@
             display.line(pTest[i].x, pTest[i].y-10, pTest[i].x, pTest[i].y+10, Black);
             display.foreground(Blue);
             display.printf(" (%4d,%4d)\r\n", x,y);
-            while (display.TouchPanelRead(&x, &y))
+            while (display.TouchPanelA2DFiltered(&x, &y))
                 wait_ms(20);
             wait(2);
         }
@@ -2244,7 +2275,7 @@
     t.start();
     do {
         point_t point = {0, 0};
-        if (display.TouchPanelPoint(&point)) {
+        if (display.TouchPanelReadable(&point)) {
             display.pixel(point.x, point.y, Red);
         }
     } while (t.read_ms() < 30000);
@@ -2415,4 +2446,4 @@
     }
 }
 
-#endif // TESTENABLE
\ No newline at end of file
+#endif // TESTENABLE

--- a/RA8875.h	Sun Dec 28 03:14:35 2014 +0000
+++ b/RA8875.h	Sun Dec 28 19:55:16 2014 +0000
@@ -67,7 +67,7 @@
 
 // What better place for some test code than in here and the companion
 // .cpp file. See also the bottom of this file.
-#define TESTENABLE
+//#define TESTENABLE
 
 /// DOS colors - slightly color enhanced
 #define Black       (color_t)(RGB(0,0,0))
@@ -121,6 +121,7 @@
 ///
 /// int main()
 /// {
+///     lcd.init(480,272,16);
 ///     lcd.printf("printing 3 x 2 = %d", 3*2);
 ///     lcd.circle(       400,25,  25,               BrightRed);
 ///     lcd.fillcircle(   400,25,  15,               RGB(128,255,128));
@@ -223,6 +224,7 @@
     ///
     /// int main()
     /// {
+    ///     lcd.init(true,255,480,272,16); // powerup, backlight full, w x h x c
     ///     lcd.printf("printing 3 x 2 = %d", 3*2);
     ///     lcd.circle(400,25, 25, BrightRed);
     /// }
@@ -245,6 +247,29 @@
     // at startup, and not at runtime.
     //~RA8875();
     
+    /// Initialize the driver.
+    ///
+    /// @param[in] power defines if the display should be left in the power-on or off state.
+    ///            If power is true (on), the backlight is set to 100%.
+    /// @param[in] width in pixels to configure the display for.
+    /// @param[in] height in pixels to configure the display for.
+    /// @param[in] color_bpp can be either 8 or 16, but must be consistent
+    ///     with the width and height parameters.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    RetCode_t init(bool poweron, int width, int height, int color_bpp);
+    
+    /// Get a pointer to the error code.
+    ///
+    /// This method returns a pointer to a text string that matches the
+    /// code. @see RetCode_t.
+    ///
+    /// @param[in] code is the return value from RetCode_t to look up.
+    /// @returns a pointer to the text message representing code. If code
+    ///     is not a valid value, then it returns the text for bad_parameter;
+    const char * GetErrorMessage(RetCode_t code);
+    
+    
     /// Select the drawing layer for subsequent commands.
     ///
     /// If the screen configuration is 480 x 272, or if it is 800 x 480 
@@ -409,34 +434,40 @@
     RetCode_t TouchPanelInit(uint8_t bTpEnable, uint8_t bTpAutoManual, uint8_t bTpDebounce, 
         uint8_t bTpManualMode, uint8_t bTpAdcClkDiv, uint8_t bTpAdcSampleTime);
     
-    /// Poll the TouchPanel and on a touch event return the filtered x, y coordinates.
+    /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
     ///
     /// This method reads the touch controller, which has a 10-bit range for each the
-    /// x and the y axis. The returned values are not in display (pixel) units.
+    /// x and the y axis.
+    ///
+    /// @note The returned values are not in display (pixel) units but are in analog to
+    ///     digital converter units.
     /// 
     /// @note This API is usually not needed. @see TouchPanelCalibrate. 
-    ///     @see TouchPanelPoint.
+    ///     @see TouchPanelReadable.
     /// 
-    /// @param[out] x is the x position where the touch was registered.
-    /// @param[out] y is the y position where the touch was registered.
+    /// @param[out] x is the x scale a/d value.
+    /// @param[out] y is the y scale a/d value.
     /// @returns true if touch was detected, in which case the x and y values were set.
     ///
-    uint8_t TouchPanelRead(loc_t *x, loc_t *y);
+    bool TouchPanelA2DFiltered(loc_t *x, loc_t *y);
 
-    /// Poll the TouchPanel and on a touch event return the raw x, y coordinates.
+    /// Poll the TouchPanel and on a touch event return the a to d raw x, y coordinates.
     ///
     /// This method reads the touch controller, which has a 10-bit range for each the
     /// x and the y axis. A number of samples of the raw data are taken, filtered,
-    /// and the results are returned. The returned values are not in display (pixel) units.
+    /// and the results are returned. 
     ///
+    /// @note The returned values are not in display (pixel) units but are in analog to
+    ///     digital converter units.
+    /// 
     /// @note This API is usually not needed. @see TouchPanelCalibrate. 
-    ///     @see TouchPanelPoint.
+    ///     @see TouchPanelReadable.
     /// 
-    /// @param[out] x is the x position where the touch was registered.
-    /// @param[out] y is the y position where the touch was registered.
+    /// @param[out] x is the x scale a/d value.
+    /// @param[out] y is the y scale a/d value.
     /// @returns true if touch was detected, in which case the x and y values were set.
     ///
-    uint8_t TouchPanelReadRaw(loc_t *x, loc_t *y);
+    bool TouchPanelA2DRaw(loc_t *x, loc_t *y);
     
     /// Calibrate the touch panel.
     ///
@@ -448,7 +479,7 @@
     /// matrix on the next power cycle. By doing so, it can avoid the
     /// need to calibrate on every power cycle.
     ///
-    /// @note The methods "TouchPanelCalibrate", "TouchPanelPoint", and
+    /// @note The methods "TouchPanelCalibrate", "TouchPanelReadable", and
     ///     indirectly the "TouchPanelSetMatrix" methods are all derived
     ///     from a program by Carlos E. Vidales. See the copyright note
     ///     for further details. See also the article
@@ -487,26 +518,52 @@
     /// Get the screen calibrated point of touch.
     ///
     /// This method determines if there is a touch and if so it will provide
-    /// the screen-relative touch coordinates.
+    /// the screen-relative touch coordinates. This method can be used in
+    /// a manner similar to Serial.readable(), to determine if there was a 
+    /// touch and indicate that - but not care about the coordinates. Alternately,
+    /// if a valid pointer to a point_t is provided, then if a touch is detected
+    /// the point_t will be populated with data. 
     ///
     /// @code
     ///     Timer t;
     ///     t.start();
     ///     do {
     ///        point_t point = {0, 0};
-    ///        if (display.TouchPanelPoint(&point)) {
+    ///        if (display.TouchPanelReadable(&point)) {
     ///            display.pixel(point.x, point.y, Red);
     ///        }
     ///    } while (t.read_ms() < 30000);
     /// @endcode
     ///
     /// @param[out] touch is the touch point, if a touch is registered.
-    /// @returns 
-    ///             - touch: if a touch was registered, 
-    ///             - no_touch: if no touch was detected,
-    ///             - bad_parameter: if the calibration matrix is not defined.
+    /// @returns true if a touch was registered, and touch is updated.
+    /// @returns false if no touch was detected, or if the calibration matrix is not defined.
+    ///
+    bool TouchPanelReadable(point_t * touch = NULL);
+
+    /// Wait for a touch panel touch and return it.
+    /// 
+    /// This method is similar to Serial.getc() in that it will wait for a touch
+    /// and then return. In order to extract the coordinates of the touch, a
+    /// valid pointer to a point_t must be provided.
+    ///
+    /// @note There is no timeout on this function, so its use is not recommended.
     ///
-    RetCode_t TouchPanelPoint(point_t * touch);
+    /// @code
+    ///     Timer t;
+    ///     t.start();
+    ///     do {
+    ///        point_t point = {0, 0};
+    ///        display.TouchPanelGet(&point);
+    ///        display.pixel(point.x, point.y, Red);
+    ///    } while (t.read_ms() < 30000);
+    /// @endcode
+    ///
+    /// @param[out] touch is the touch point, if a touch is registered.
+    /// @returns true if a touch was registered, and touch is updated.
+    /// @returns false if no touch was detected, or if the calibration matrix is not defined.
+    ///
+    bool TouchPanelGet(point_t * touch);
 
     /// Set the calibration matrix for the touch panel.
     ///
@@ -584,7 +641,6 @@
         uint8_t longTimeAdjustment = 0,
         bool interruptEnable = false, bool wakeupEnable = false);
 
-
     /// Create Key Code definitions for the key matrix.
     ///
     /// This API provides a table of 22 key-code assignments for the matrix of keys.
@@ -1579,22 +1635,6 @@
     /// Touch Panel calibration matrix.
     tpMatrix_t tpMatrix;
 
-    /// Initialize the chip, which is normally done as part of the
-    /// constructor, so not typically called by the user.
-    ///
-    /// @note This API permits configuration, however it is not [yet]
-    ///     available to the end user. Be sure the parameters
-    ///     are consistent with each other - see the RA8875 user
-    ///     manual.
-    ///
-    /// @param[in] width in pixels to configure the display for.
-    /// @param[in] height in pixels to configure the display for.
-    /// @param[in] color_bpp can be either 8 or 16, but must be consistent
-    ///     with the width and height parameters.
-    /// @returns success/failure code. @see RetCode_t.
-    ///
-    RetCode_t init(int width, int height, int color_bpp);
-    
     /// Internal function to put a character using the built-in (internal) font engine
     ///
     /// @param[in] is the character to put to the screen.
@@ -1616,7 +1656,7 @@
     ///     the pin selection is the invert of this.
     /// @returns success/failure code. @see RetCode_t.
     ///
-    RetCode_t select(bool chipsel);
+    RetCode_t _select(bool chipsel);
 
     /// Wait while the status register indicates the controller is busy.
     ///
@@ -1652,7 +1692,7 @@
     /// @returns a value read from the port, since SPI is often shift
     ///     in while shifting out.
     ///
-    unsigned char spiwrite(unsigned char data);
+    unsigned char _spiwrite(unsigned char data);
     
     /// The most primitive - to read a data value to the SPI interface.
     ///
@@ -1662,7 +1702,7 @@
     /// @returns a value read from the port, since SPI is often shift
     ///     in while shifting out.
     ///
-    unsigned char spiread();
+    unsigned char _spiread();
     
     const uint8_t * pKeyMap;
     

--- a/RA8875_Touch.cpp	Sun Dec 28 03:14:35 2014 +0000
+++ b/RA8875_Touch.cpp	Sun Dec 28 19:55:16 2014 +0000
@@ -37,7 +37,7 @@
     return noerror;
 }
 
-unsigned char RA8875::TouchPanelRead(loc_t *x, loc_t *y)
+bool RA8875::TouchPanelA2DFiltered(loc_t *x, loc_t *y)
 {
     unsigned char touchready;
     static int xbuf[TPBUFSIZE], ybuf[TPBUFSIZE], sample = 0;
@@ -100,7 +100,7 @@
     return touchready;
 }
 
-unsigned char RA8875::TouchPanelReadRaw(loc_t *x, loc_t *y)
+bool RA8875::TouchPanelA2DRaw(loc_t *x, loc_t *y)
 {
     unsigned char touchready;
 
@@ -366,14 +366,14 @@
  *  operations to scale results by a factor of 2 or even 4.  
  *
  */
-RetCode_t RA8875::TouchPanelPoint(point_t * TouchPoint)
+bool RA8875::TouchPanelReadable(point_t * TouchPoint)
 {
-    RetCode_t retValue = no_touch;
+    bool touched = false;
     point_t screenpoint = {0, 0};
     
-    if (TouchPanelRead(&screenpoint.x, &screenpoint.y)) {
-        retValue = touch;
-        if (tpMatrix.Divider != 0 ) {
+    if (TouchPanelA2DFiltered(&screenpoint.x, &screenpoint.y)) {
+        touched = true;
+        if (tpMatrix.Divider != 0 && TouchPoint) {
             /* Operation order is important since we are doing integer */
             /*  math. Make sure you add all terms together before      */
             /*  dividing, so that the remainder is not rounded off     */
@@ -388,10 +388,10 @@
                               tpMatrix.Fn
                             ) / tpMatrix.Divider ;
         } else {
-            retValue = bad_parameter ;
+            touched = false;
         }
     }
-    return( retValue );
+    return touched;
 }